challenge.requested

​

v2.0.0

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

Forwarding (SMS)

{
    "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"
    }
}