Payment Routes

A payment route is a persistent pathway between a fiat source and a crypto destination (onramp), or a crypto source and a fiat destination (offramp). Creating a payment route doesn’t move any money. Rain returns the details a sender uses to fund the route, and money moves only when the sender sends funds to it.

What a payment route is

A payment route runs in one direction:

Onramp: The source is fiat (ACH or wire) and the destination is an onchain address. Rain returns a virtual account, converts any fiat sent to it to stablecoin (usdc or rusd), and delivers it to the destination address.
Offramp: The source is crypto (a stablecoin and chain) and the destination is a payment account. Rain returns a deposit address, converts any stablecoin sent to it to fiat, and delivers it to the destination account.

Partner / responseRain stepDirection

POST /payment-routes: the partner calls the endpoint with a source and destination.
Onramp or offramp?: determined by whether the source is fiat or crypto.
Onramp: Rain converts incoming fiat to stablecoin and returns a virtual account (ACH/wire details).
Offramp: Rain converts incoming stablecoin to fiat and returns an onchain deposit address.

The sender or receiver doesn’t have to be the customer. Anyone can fund a route on the customer’s behalf.

API flow

Creating a route is a single call. Everything after that happens when the sender funds it:

Action / API callExternal / senderWebhook Rain sends you

The steps above, in text:

#	Actor	Step
1	Partner	Calls `POST /payment-routes`
2	Rain	Returns the route with a `depositAddress`
3	Partner	Shares the virtual account or deposit address with the sender
4	Sender	Sends fiat (onramp) or stablecoin (offramp) to fund the route
5	Rain	Converts and settles the funds
6	Rain	Sends a `transactionTransfer` webhook

Before you begin

Make sure you have:

API access to the payment routes endpoints.
A destination address for onramps: an onchain wallet or a Rain smart contract that receives stablecoin.
A registered payment account for offramps, as the destination bank account.

Rain also subjects payment routes to regional and industry restrictions. Check those before you create one.

Create an onramp payment route

Call POST /payment-routes with a fiat source and an onchain destination.

curl -X POST https://api.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"
      }
    }
  }'

source.rail can be ach or wire. The generated virtual account supports both rails regardless of which one you specify. Setting the primary rail only helps with routing optimization. The response includes a depositAddress with the virtual account’s beneficiary and banking details. The virtual account is a named account: beneficiaryName carries your customer’s own name, so incoming transfers are addressed to them, not to Rain. Share these details with the sender so they can wire or ACH funds to the route.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "userId": "11111111-1111-1111-1111-111111111111",
  "status": "active",
  "source": {
    "currency": "usd",
    "rail": "ach"
  },
  "destination": {
    "currency": "usdc",
    "rail": "base",
    "address": {
      "type": "onchain",
      "address": "0x1234567890abcdef1234567890abcdef12345678"
    }
  },
  "depositAddress": {
    "type": "fiat",
    "beneficiaryName": "JOHN DOE",
    "beneficiaryAddress": "123 Main St, Austin, TX 78701, US",
    "beneficiaryBankName": "Partner Bank, N.A.",
    "beneficiaryBankAddress": "456 Bank Ave, New York, NY 10002, US",
    "accountNumber": "9876543210",
    "routingNumber": "021000021"
  },
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T10:00:00Z"
}

Create an offramp payment route

Call POST /payment-routes with a crypto source and a fiat destination that references a payment account id.

curl -X POST https://api.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": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    },
    "refundAddress": "0x9876543210fedcba9876543210fedcba98765432"
  }'

refundAddress is required whenever source is a crypto rail. If the transaction can’t be completed, Rain returns the crypto to this address.

The response includes an onchain depositAddress. Share this with the sender so they can send stablecoin to the route.

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "userId": "11111111-1111-1111-1111-111111111111",
  "status": "active",
  "source": {
    "currency": "usdc",
    "rail": "base"
  },
  "destination": {
    "currency": "usd",
    "rail": "ach",
    "address": {
      "type": "paymentAccount",
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
    }
  },
  "refundAddress": "0x9876543210fedcba9876543210fedcba98765432",
  "depositAddress": {
    "type": "onchain",
    "address": "0xabcdef1234567890abcdef1234567890abcdef12"
  },
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T10:00:00Z"
}

Only send the exact source currency to a depositAddress. Sending other tokens or currencies may result in failed conversions or loss of funds.

Response fields

Both the onramp and offramp responses above share the same shape:

Field	Description
`id`	Unique identifier for the payment route.
`userId`	ID of the individual user this route belongs to. Omitted for company teams, which use `companyId` instead.
`status`	Current state of the route: `active`, `pending`, `frozen`, or `deleted`. A `pending` route is awaiting the customer’s verification and has no `depositAddress` yet; the `paymentRoute.created` webhook fires when it becomes `active`.
`source.currency`, `source.rail`	The currency and rail funds arrive on.
`destination.currency`, `destination.rail`	The currency and rail funds are delivered on.
`destination.address`	For offramps, the referenced payment account. For onramps, the onchain address funds are delivered to.
`depositAddress`	The banking credentials a sender wires or ACHs to (onramp) or the onchain address a sender sends stablecoin to (offramp).
`refundAddress`	Present only when `source` is a crypto rail (offramps). The onchain address Rain returns funds to if the transaction can’t complete.
`createdAt`, `updatedAt`	Timestamps for when the route was created and last updated.

Optional fields

Two more fields are accepted when you create (or later update) a route:

transferMessage: a memo of up to 23 ASCII letters, digits, and spaces. It surfaces as the wire memo on USD offramps and as the SPEI concepto on MXN offramps.
senderFees: an array of fees you charge the sender on every transfer the route processes, each { "type": "flat" | "variable", "amount": "..." }. A flat amount is in the source currency; a variable amount is a percentage below 100. Sender fees must be enabled for your program.

Supported rails

The following table lists the supported rails for each direction:

Direction	Fiat rail	Crypto rail	Stablecoin currency
Onramp	`ach`, `wire`	`ethereum`, `polygon`, `optimism`, `arbitrum`, `avalanche`, `base`, `celo`, `solana`	`usdc`, `rusd`
Offramp	`ach`, `wire`	`ethereum`, `polygon`, `optimism`, `arbitrum`, `avalanche`, `base`, `celo`, `solana`	`usdc`, `rusd`

MXN routes pair the mx_spei rail and mxn currency with usdc in either direction. See MXN onramps and MXN offramps for the differences.

Manage payment routes

To retrieve all payment routes for your team, call GET /payment-routes. The response carries them in a paymentRoutes array. Filter with userId or companyId, and page with limit (default 20, max 100) and cursor (the last route’s id from the previous page).

curl -X GET https://api.rain.xyz/v1/payment-routes \
  -H "Api-Key: YOUR_API_KEY"

To retrieve a single payment route, call GET /payment-routes/{paymentRouteId}.

curl -X GET https://api.rain.xyz/v1/payment-routes/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Api-Key: YOUR_API_KEY"

To update a payment route, call PATCH /payment-routes/{paymentRouteId}. Only transferMessage, refundAddress (offramp routes only), and senderFees can change; the route’s source, destination, and deposit address are immutable. MXN routes can’t be updated: delete the route and create a new one instead.

curl -X PATCH https://api.rain.xyz/v1/payment-routes/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "transferMessage": "INVOICE 1042" }'

To remove a payment route, call DELETE /payment-routes/{paymentRouteId}. A successful delete returns 204 with no body, and the route no longer appears in list or get responses.

curl -X DELETE https://api.rain.xyz/v1/payment-routes/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Api-Key: YOUR_API_KEY"

Introduction

Set Up Money Movement

Money Movement

Subtenants

Reconciliation

Payment Routes

What a payment route is

API flow

Before you begin

Create an onramp payment route

Create an offramp payment route

Response fields

Optional fields

Supported rails

Manage payment routes

What’s next

Payment Accounts

Onramps

Offramps

Restrictions

​What a payment route is

​API flow

​Before you begin

​Create an onramp payment route

​Create an offramp payment route

​Response fields

​Optional fields

​Supported rails

​Manage payment routes

​What’s next

Payment Accounts

Onramps

Offramps

Restrictions

What a payment route is

API flow

Before you begin

Create an onramp payment route

Create an offramp payment route

Response fields

Optional fields

Supported rails

Manage payment routes

What’s next