challenge.requested - Rain

breaking changes

Migrated to challenge.requested

Breaking change: the 3DS notification webhook’s resource and action naming convention has changed, and several challenge fields have been renamed. Update your webhook handlers before upgrading.

Rain updated the 3DS notification webhook with a new resource and action naming convention and improved field names.

Breaking Changes

resource changed from "3ds" to "challenge"
action changed from "notification" to "requested"
challenge.ttl renamed to challenge.timeToLive
challenge.otp renamed to challenge.oneTimePassword

Payload Fields

Field	Type	Description
`id`	`string`	Unique per-delivery webhook ID (distinct from `body.id`)
`resource`	`string`	Always `"challenge"`
`action`	`string`	Always `"requested"`
`version`	`string` (optional)	The webhook version (`2.0.0`). May be absent for some tenants: treat it as optional when parsing
`body.challenge.startTime`	`string`	ISO 8601 timestamp of when the challenge started
`body.challenge.expiryTime`	`string`	ISO 8601 timestamp of when the challenge expires
`body.challenge.timeToLive`	`number`	Time remaining in seconds
`body.challenge.oneTimePassword`	`string` (optional)	One-time password to deliver to the cardholder. Absent for OOB challenges
`body.challenge.id`	`string` (uuid)	OOB only. Not sent for Forwarding challenges. Echo back as `challengeId` when calling `/3ds`
`body.transaction.amount`	`number`	Transaction amount in the currency’s minor unit (e.g., cents)
`body.transaction.currency`	`string`	Currency code (e.g., `USD`)
`body.transaction.merchantName`	`string`	Merchant name
`body.transaction.merchantCountry`	`string`	Merchant country
`body.transaction.id`	`string` (uuid)	OOB only. Not sent for Forwarding challenges. Echo back as `apataTransactionId` when calling `/3ds`
`body.card.id`	`string`	Rain card ID
`body.deliveryMethod`	`string`	Challenge delivery method: `SMS`, `EMAIL`, `WHATSAPP`, or `OTHER` (3DS Forwarding), or `PUSH` (Out-of-Band). See the 3DS guide
`body.id`	`string`	Unique ID for this webhook notification, use for idempotency

Example Payloads

{
    "id": "d4f8a2b1-3c5e-4a7f-9b1d-6e8f0a2c4d5e",
    "resource": "challenge",
    "action": "requested",
    "version": "2.0.0",
    "body": {
        "challenge": {
            "startTime": "2026-03-06T10:00:00.000Z",
            "expiryTime": "2026-03-06T10:05:00.000Z",
            "timeToLive": 300,
            "oneTimePassword": "123456"
        },
        "transaction": {
            "amount": 5000,
            "currency": "USD",
            "merchantName": "AMAZON",
            "merchantCountry": "US"
        },
        "card": {
            "id": "94534236-927b-44f3-9429-27994c7ebc49"
        },
        "deliveryMethod": "SMS",
        "id": "8f7c1a92-4b3d-4e5f-a6b7-c8d9e0f1a2b3"
    }
}

{
    "id": "d4f8a2b1-3c5e-4a7f-9b1d-6e8f0a2c4d5e",
    "resource": "challenge",
    "action": "requested",
    "version": "2.0.0",
    "body": {
        "challenge": {
            "startTime": "2026-03-06T10:00:00.000Z",
            "expiryTime": "2026-03-06T10:05:00.000Z",
            "timeToLive": 300,
            "id": "a1b2c3d4-0000-0000-0000-000000000001"
        },
        "transaction": {
            "amount": 5000,
            "currency": "USD",
            "merchantName": "AMAZON",
            "merchantCountry": "US",
            "id": "a1b2c3d4-0000-0000-0000-000000000002"
        },
        "card": {
            "id": "94534236-927b-44f3-9429-27994c7ebc49"
        },
        "deliveryMethod": "PUSH",
        "id": "8f7c1a92-4b3d-4e5f-a6b7-c8d9e0f1a2b3"
    }
}