Card Authorizations

Simulate card authorization flows, including cross-currency transactions and decline scenarios.

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 your tenant or one of its subtenants.
amount	integer	Yes	The transaction amount in cents (merchant currency). Must be between 1 and 2147483647.
currency	string	Yes	The merchant currency code (for example, "USD", "EUR", "GBP").
merchantName	string	Yes	The merchant name. Must not be empty.
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.
threeDSecure	boolean	No	Accepted by the endpoint but currently has no effect on the simulated authorization.

Any field not listed here returns 400.

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:

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

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 — or the card is not active or has no processor card ID.
404 Not Found	Endpoint not available in production, simulations are not enabled for your tenant, or the card does not exist.
422 Unprocessable Entity	The simulated authorization was not processed, so no transaction was created.
500 Internal Server Error	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"
  }'