3DS Challenges

Simulate 3DS authentication challenges to test your 3DS Forwarding webhook handling.

Simulation endpoints are available in development environments only — production returns 404 Not Found.

Trigger a 3DS authentication challenge against a card to test your 3DS Forwarding webhook integration. The endpoint generates a one-time password (OTP), sends a challenge.requested webhook to your configured endpoint, and returns the challenge credentials.

Use this to verify that your system receives and processes 3DS challenge webhooks correctly, without requiring a real card transaction.

This endpoint requires 3DS Forwarding to be enabled for your card program. Contact your Rain account manager to enable this feature.

Endpoint

POST /v1/simulate/3ds-challenge

Headers

Header	Type	Required	Description
Api-Key	string	Yes	Your tenant API key. The tenant scope is resolved from this key.
Content-Type	application/json	Yes	—

Body

Field	Type	Required	Description
cardId	string (UUID)	Yes	The Rain card ID to simulate the challenge for. Must be an active card belonging to your tenant or one of its subtenants.
transactionId	string (UUID)	Yes	The transaction ID to attach to the challenge.
amount	integer	Yes	The transaction amount in cents. Must be between 0 and 2147483647.
merchantName	string	Yes	The merchant name to include in the challenge details. Must not be empty.
deliveryMethod	string	Yes	The OTP delivery method: SMS, EMAIL, WHATSAPP, or PUSH.

Example request

{
  "cardId": "a7f2c5b1-9e8d-4c3a-bb22-12c0a4d5b8f9",
  "transactionId": "f3a1c92e-1b3d-4d1e-bb22-12c0a4d5b8f9",
  "amount": 5000,
  "merchantName": "Online Store",
  "deliveryMethod": "SMS"
}

Response

A successful response returns the challenge credentials, which your system should use to verify the OTP delivery in your test flow.

200 OK

{
  "challengeId": "b2c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
  "oneTimePassword": "482917",
  "expiryTime": "2026-05-12T17:25:00.000Z"
}

Field	Type	Description
challengeId	string (UUID)	Unique identifier for this challenge session.
oneTimePassword	string	The 6-digit OTP that your system should deliver to the cardholder.
expiryTime	string (ISO 8601)	When the challenge expires (5 minutes from creation).

The simulation triggers a challenge.requested webhook to your configured endpoint, containing the same challenge and transaction details as a real 3DS flow. Your webhook handler receives this payload and should deliver the OTP to the cardholder through the specified delivery method.

Errors

Status	When
400 Bad Request	Invalid body (missing required fields, empty merchantName, amount out of range, invalid deliveryMethod), or the card is not active or has no processor card ID.
404 Not Found	Endpoint not available in production, the card does not exist, or the card does not belong to your tenant.

Behavior notes

• No real transaction is created. This simulation only triggers the 3DS webhook — it does not create a transaction record or authorization hold.
• The webhook is real. Your configured webhook endpoint receives the challenge.requested event exactly as it would during a real 3DS flow.
• Currency is always USD. The webhook payload uses USD as the transaction currency.
• Merchant country is always US. The webhook payload uses US as the merchant country.

Example

curl -X POST https://api-dev.rain.xyz/v1/simulate/3ds-challenge \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cardId": "a7f2c5b1-9e8d-4c3a-bb22-12c0a4d5b8f9",
    "transactionId": "f3a1c92e-1b3d-4d1e-bb22-12c0a4d5b8f9",
    "amount": 5000,
    "merchantName": "Online Store",
    "deliveryMethod": "SMS"
  }'