> ## Documentation Index
> Fetch the complete documentation index at: https://rain-sandbox-trial.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 3DS Challenges

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

<Warning>
  **Beta Feature**

  The 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`.
</Warning>

Trigger a 3DS authentication challenge against a card to test your [3DS Forwarding](/docs/3ds) 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.

<Info>
  This endpoint requires [3DS Forwarding](/docs/3ds) to be enabled for your card program. Contact your Rain account manager to enable this feature.
</Info>

## 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`.                                          |

<Warning>
  The `PUSH` delivery method is not supported for simulation. Use `SMS`, `EMAIL`, or `WHATSAPP` instead.
</Warning>

```json title="Example request" theme={null}
{
  "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.

```json title="200 OK" theme={null}
{
  "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).              |

<Info>
  The simulation triggers a [`challenge.requested`](/changelog/webhooks/v2/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.
</Info>

## 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

```bash theme={null}
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"
  }'
```