Simulating Transactions

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

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.

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	Create a new authorization, including cross-currency and decline scenarios
Authorization updates	Modify an open authorization amount (for example, adding a tip)
Authorization reversals	Release all or part of an authorization hold
Settlement	Capture an open authorization to complete the transaction
Refund	Credit funds back to the cardholder after settlement

3DS authentication

Simulation	Description
3DS challenges	Trigger a 3DS authentication challenge to test webhook handling

Collateral and transfers

Simulation	Description
Collateral funding	Deposit collateral to a smart contract
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 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 to see the full flow.

Common patterns

Testing the full authorization lifecycle

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

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 for the full list of supported decline reasons.