Transfer Transactions

Simulate payment route transfers for MXN (SPEI) and USD (ACH/wire) flows.

Simulation endpoints are available in development environments only — production returns 404 Not Found.

Trigger a transfer transaction against a configured payment route, exactly as if a real deposit had triggered it. Use this to test the transfer and webhook lifecycle end-to-end.

Prerequisites

Before you can simulate a payment route, you must create a payment route in the sandbox environment. The payment route creation endpoint is separate from the simulation endpoint.

For onramps (fiat → crypto), create a payment route:

curl -X POST https://api-dev.rain.xyz/v1/payment-routes \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "11111111-1111-1111-1111-111111111111",
    "source": {
      "currency": "usd",
      "rail": "ach"
    },
    "destination": {
      "currency": "usdc",
      "rail": "base",
      "address": {
        "type": "onchain",
        "address": "0x1234567890abcdef1234567890abcdef12345678"
      }
    }
  }'

For offramps (crypto → fiat), first create a payment account, then create a payment route:

# Step 1: Create a payment account
curl -X POST https://api-dev.rain.xyz/v1/payment-accounts \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "externalFiatAccount",
    "userId": "11111111-1111-1111-1111-111111111111",
    "nickname": "Test Checking Account",
    "externalFiatAccount": {
      "currency": "usd",
      "rail": "ach",
      "thirdParty": false,
      "beneficiaryFirstName": "John",
      "beneficiaryLastName": "Doe",
      "beneficiaryType": "individual",
      "beneficiaryAddress": {
        "addressLine1": "123 Main St",
        "city": "New York",
        "region": "NY",
        "postalCode": "10001",
        "countryCode": "US"
      },
      "bankName": "Test Bank",
      "bankAddress": {
        "addressLine1": "456 Bank Ave",
        "city": "New York",
        "region": "NY",
        "postalCode": "10002",
        "countryCode": "US"
      },
      "accountNumber": "123456789",
      "routingNumber": "000000000",
      "bankAccountType": "checking"
    }
  }'

# Step 2: Create the offramp payment route (use the payment account ID from step 1)
curl -X POST https://api-dev.rain.xyz/v1/payment-routes \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "11111111-1111-1111-1111-111111111111",
    "source": {
      "currency": "usdc",
      "rail": "base"
    },
    "destination": {
      "currency": "usd",
      "rail": "ach",
      "address": {
        "type": "paymentAccount",
        "id": "PAYMENT_ACCOUNT_ID_FROM_STEP_1"
      }
    },
    "refundAddress": "0x1234567890abcdef1234567890abcdef12345678"
  }'

The response includes the id field — this is your paymentRouteId to use in simulation requests.

See the Onramps and Offramps documentation for complete details on creating payment routes.

Endpoint

POST /v1/simulate/payment-routes

The /v1/simulate/automations endpoint has been renamed to /v1/simulate/payment-routes. The old path remains available as a deprecated alias during migration. Update your integrations to use /v1/simulate/payment-routes as the deprecated endpoint will be removed in a future release.

Supported payment route types:

• MXN payment routes — Both onramps (SPEI → crypto) and offramps (crypto → SPEI)
• USD payment routes — Both onramps (ACH/wire → crypto) and offramps (crypto → ACH/wire)

Simulating any other payment route type returns 422 Unprocessable Entity.

Supported chains

Payment routes can only be created on the following testnet chains in the sandbox environment:

• Ethereum Sepolia
• Avalanche Fuji
• Solana Devnet
• Polygon Amoy
• Base Sepolia

Once you have a payment route on a supported chain, you can simulate transfers against it.

Amount limits

Simulations accept at most $100 USD per call. For non-USD routes, Rain converts the amount to USD before checking the limit. Larger amounts return 400 with Amount must be at most $100.00 USD.

Onramp and offramp simulations require a minimum amount of $2 in the route’s source currency to move funds (for example, 2 MXN on an MXN route). On every route type, smaller amounts only trigger the micro-deposit webhook, create no transfer, and return 202 with { "success": true }.

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	—
Idempotency-Key	string (1–64 chars)	No	Optional idempotency/correlation key. If you omit it, the server generates a fresh UUID per request, so each call produces a new simulation.

Body

Field	Type	Required	Description
paymentRouteId	string (UUID)	Yes	The Rain payment route ID to simulate. Must belong to the calling tenant. You can send the deprecated alias automationId instead; if both are sent, paymentRouteId is used.
amount	string (decimal)	Yes	The source-currency amount to simulate, as a positive decimal string in major units (for example, "100" or "25.50"). Must be greater than 0, and its USD equivalent must be at most $100. Pattern: ^[0-9]+(\.[0-9]+)?$.
memo	string (max 500 chars)	No	Optional memo passed through to USD onramp simulations.

Example request

{
  "paymentRouteId": "a7f2c5b1-9e8d-4c3a-bb22-12c0a4d5b8f9",
  "amount": "100"
}

Response

The response format depends on the payment route type.

MXN payment routes (synchronous)

MXN payment route simulations of 2 MXN or more return immediately with the transaction ID:

200 OK

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

Field	Type	Description
transactionId	string (UUID)	The transaction ID. Call GET /v1/issuing/transactions/{transactionId} to fetch full details and current status.

The transaction starts in pending and progresses asynchronously, just like one triggered by a real deposit. Your webhook URL receives the same transactionTransfer webhooks as a real transfer:

• action created — sent when the transfer is initiated.
• action updated — sent on intermediate status changes (for example, awaiting_transfer → processing).
• action completed — sent when the transfer settles.

See Webhooks for payload schemas.

USD payment routes (asynchronous)

USD payment route simulations return HTTP 202 to indicate the request was accepted and the simulation is processing asynchronously:

202 Accepted

{
  "success": true
}

The response carries no transaction ID. For amounts of 2 USD or more, find the transfer by calling GET /v1/issuing/transactions?type=transfer filtered by userId once the webhooks arrive.

USD simulations trigger real webhook callbacks asynchronously. Your webhook URL receives transactionTransfer webhooks as the simulation progresses through the transfer lifecycle.

Errors

Status	When
400 Bad Request	Invalid body — missing required fields, malformed amount, or an amount over $100 USD.
404 Not Found	Endpoint not available in production, or the paymentRouteId doesn’t exist or belong to your tenant.
422 Unprocessable Entity	The payment route exists but is not eligible for simulation (for example, an unsupported flow type, or a route that is missing a required provider account or team).
500 Internal Server Error	Unhandled error during simulation.

Behavior notes

• No real funds move. Simulations are fully mocked end-to-end — you don’t need to pre-fund anything.
• MXN simulations create immediate transaction records. The transaction is queryable via the transactions API and fires webhooks as it progresses.
• USD simulations process asynchronously. The 202 response indicates the simulation request was accepted. Webhooks fire as the underlying providers process the simulated deposits.

Example

curl -X POST https://api-dev.rain.xyz/v1/simulate/payment-routes \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentRouteId": "a7f2c5b1-9e8d-4c3a-bb22-12c0a4d5b8f9",
    "amount": "100"
  }'