3DS Challenges

Beta FeatureThe Transaction Simulations feature is currently in beta. API endpoints and behavior may change as we continue to refine the product. 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.
`amount`	integer	Yes	The transaction amount in cents.
`merchantName`	string	Yes	The merchant name to include in the challenge details.
`deliveryMethod`	string	Yes	The OTP delivery method: `SMS`, `EMAIL`, or `WHATSAPP`.

The PUSH delivery method is not supported for simulation. Use SMS, EMAIL, or WHATSAPP instead.

Example request

{
  "cardId": "a7f2c5b1-9e8d-4c3a-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, invalid `deliveryMethod`), or the card is not active.
`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",
    "amount": 5000,
    "merchantName": "Online Store",
    "deliveryMethod": "SMS"
  }'

Introduction

Plan & Set Up Your Program

Build Your Program

Run Your Program

Rewards

Embedded Wallets

3DS Challenges

Endpoint

Headers

Body

Response

Errors

Behavior notes

Example

​Endpoint

​Headers

​Body

​Response

​Errors

​Behavior notes

​Example

Endpoint

Headers

Body

Response

Errors

Behavior notes

Example