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

# Simulating Transactions

> Test card flows, collateral deposits, and payment routes in sandbox without real funds.

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

Transaction simulation allows you to test your integration against Rain's APIs without processing real transactions. Simulations create real transaction records, trigger webhooks, and update balances — all without moving actual funds.

Use simulation to:

* Verify webhook handling for each transaction type
* Test decline scenarios and error handling
* Validate end-to-end flows before going live

## Available simulations

Rain provides simulation endpoints for the complete card transaction lifecycle, plus collateral funding and payment route transfers.

### Card authorization lifecycle

| Simulation                                                                       | Description                                                                |
| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [Card authorizations](/docs/simulating-transactions/card-authorizations)         | Create a new authorization, including cross-currency and decline scenarios |
| [Authorization updates](/docs/simulating-transactions/authorization-updates)     | Modify an open authorization amount (for example, adding a tip)            |
| [Authorization reversals](/docs/simulating-transactions/authorization-reversals) | Release all or part of an authorization hold                               |
| [Settlement](/docs/simulating-transactions/settlement)                           | Capture an open authorization to complete the transaction                  |
| [Refund](/docs/simulating-transactions/refund)                                   | Credit funds back to the cardholder after settlement                       |

### 3DS authentication

| Simulation                                                     | Description                                                     |
| -------------------------------------------------------------- | --------------------------------------------------------------- |
| [3DS challenges](/docs/simulating-transactions/3ds-challenges) | Trigger a 3DS authentication challenge to test webhook handling |

### Collateral and transfers

| Simulation                                                                   | Description                                                  |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------ |
| [Collateral funding](/docs/simulating-transactions/collateral-funding)       | Deposit collateral to a smart contract                       |
| [Transfer transactions](/docs/simulating-transactions/transfer-transactions) | Trigger MXN (SPEI) or USD (ACH/wire) payment route transfers |

## Getting started

1. **Get sandbox access.** Simulation endpoints are only available in the sandbox environment.

2. **Create test cards.** You need at least one active card to simulate card transactions. Use the [Create a card](/reference/cards/create-a-card-for-a-user) endpoint to issue cards in sandbox.

3. **Fund collateral.** For Rain-Managed programs fund the user's collateral contract; for Partner-Managed programs fund your program's contract. Unfunded contracts decline simulated authorizations with `account_credit_limit_exceeded`.

4. **Configure webhooks.** Set up a webhook endpoint to receive transaction events. Simulations fire the same webhooks as real transactions.

5. **Simulate a transaction.** Start with a [card authorization](/docs/simulating-transactions/card-authorizations) to see the full flow.

## Common patterns

### Testing the full authorization lifecycle

```bash theme={null}
# 1. Create an authorization
curl -X POST https://api-dev.rain.xyz/v1/simulate/transactions/authorize \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cardId": "YOUR_CARD_ID",
    "amount": 5000,
    "currency": "USD",
    "merchantName": "Test Merchant",
    "merchantCategoryCode": "5411"
  }'

# 2. Settle the authorization (use transactionId from step 1)
curl -X POST https://api-dev.rain.xyz/v1/simulate/transactions/TRANSACTION_ID/settle \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# 3. Refund the settled transaction
curl -X POST https://api-dev.rain.xyz/v1/simulate/transactions/TRANSACTION_ID/refund \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Testing decline scenarios

Use the `declineReason` parameter to simulate declined authorizations:

```bash theme={null}
curl -X POST https://api-dev.rain.xyz/v1/simulate/transactions/authorize \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cardId": "YOUR_CARD_ID",
    "amount": 5000,
    "currency": "USD",
    "merchantName": "Test Merchant",
    "merchantCategoryCode": "5411",
    "declineReason": "account_credit_limit_exceeded"
  }'
```

See [Card authorizations](/docs/simulating-transactions/card-authorizations#decline-reasons) for the full list of supported decline reasons.