Card Authorizations

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 card authorization exactly as if a merchant had initiated it. Use this in sandbox to test authorization flows, webhook handling, and decline scenarios end-to-end. When the merchant currency differs from the billing currency (USD), the system applies FX conversion using current market rates plus applicable fees. To test how your integration handles declines, specify a decline reason in your request.

Endpoint

POST /v1/simulate/transactions/authorize

The card must be active and belong to your tenant. Cards in locked, canceled, or unactivated status cannot be used for simulation.

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 authorize against. Must belong to the calling tenant.
`amount`	integer	Yes	The transaction amount in cents (merchant currency). Must be a positive integer.
`currency`	string	Yes	The merchant currency code (for example, `"USD"`, `"EUR"`, `"GBP"`).
`merchantName`	string	Yes	The merchant name.
`merchantCategoryCode`	string	Yes	The merchant category code (MCC). For example, `"5814"` for fast food restaurants.
`declineReason`	string	No	Simulate a declined authorization. See Decline reasons below.

Example request

{
  "cardId": "a7f2c5b1-9e8d-4c3a-bb22-12c0a4d5b8f9",
  "amount": 5000,
  "currency": "USD",
  "merchantName": "Coffee Shop",
  "merchantCategoryCode": "5814"
}

Response

A successful response returns the transaction ID and status.

200 OK — Approved

{
  "transactionId": "f3a1c92e-1b3d-4d1e-bb22-12c0a4d5b8f9",
  "status": "authorized"
}

200 OK — Declined

{
  "transactionId": "f3a1c92e-1b3d-4d1e-bb22-12c0a4d5b8f9",
  "status": "declined",
  "declinedReason": "account_credit_limit_exceeded"
}

Field	Type	Description
`transactionId`	string (UUID)	The transaction ID.
`status`	string	The transaction status: `authorized` or `declined`.
`declinedReason`	string	Present when `status` is `declined`. The reason for the decline.

The transaction triggers the same webhooks as a real authorization:

transaction.requested — Sent when the authorization request arrives.
transaction.created — Sent when the authorization is approved.

See the transaction webhook reference for payload schemas.

Decline reasons

Use the declineReason field to simulate declined authorizations:

Value	Description
`account_credit_limit_exceeded`	The cardholder does not have sufficient available balance or credit limit.
`card_locked`	The card is locked and cannot be used for transactions.
`card_canceled`	The card has been canceled.
`card_not_activated`	The card has not been activated.
`blocked_mcc`	The transaction is declined because the merchant category is blocked.
`blocked_merchant`	The transaction is declined because the specific merchant is blocked.
`balance_inquiry_not_permitted`	Balance inquiry is not permitted for this card.
`expiry_mismatch`	The card’s expiration date does not match the value provided in the transaction.
`cvv_mismatch`	The card’s CVV does not match the value provided in the transaction.
`invalid_pin`	The PIN entered for the transaction is incorrect.
`restricted_country`	The transaction is declined because it originated from a restricted country.

Example declined authorization

{
  "cardId": "a7f2c5b1-9e8d-4c3a-bb22-12c0a4d5b8f9",
  "amount": 5000,
  "currency": "USD",
  "merchantName": "Online Casino",
  "merchantCategoryCode": "7995",
  "declineReason": "blocked_mcc"
}

Cross-currency transactions

When the currency differs from USD (the billing currency), the system applies FX conversion:

The merchant amount is converted to USD using current market rates.
A Visa foreign exchange fee (1%) is applied.
A Rain foreign exchange fee is applied (default 2%, or your tenant-specific rate if configured).

The billingAmount in the transaction record reflects the total USD amount after all conversions and fees.

Errors

Status	When
`400 Bad Request`	Invalid body — missing required fields, invalid `cardId` format, or invalid `declineReason` value.
`404 Not Found`	Endpoint not available in production, simulations are not enabled for your tenant, or the card does not exist.
`500 Internal Server Error`	Card validation failed (card not active, no processor card ID), invalid currency, or unhandled error during simulation.

Behavior notes

No real funds move. Simulations are fully mocked — the processor interaction is simulated internally.
The transaction record is real. The simulation creates a real transaction record, queryable via the transactions API, that fires the same webhooks as a real authorization.
Network is always VISA. Simulated authorizations use the VISA network regardless of the actual card network.

Example

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": "a7f2c5b1-9e8d-4c3a-bb22-12c0a4d5b8f9",
    "amount": 5000,
    "currency": "USD",
    "merchantName": "Coffee Shop",
    "merchantCategoryCode": "5814"
  }'

Introduction

Plan & Set Up Your Program

Build Your Program

Run Your Program

Rewards

Embedded Wallets

Card Authorizations

Endpoint

Headers

Body

Response

Decline reasons

Cross-currency transactions

Errors

Behavior notes

Example

​Endpoint

​Headers

​Body

​Response

​Decline reasons

​Cross-currency transactions

​Errors

​Behavior notes

​Example

Endpoint

Headers

Body

Response

Decline reasons

Cross-currency transactions

Errors

Behavior notes

Example