Onramps

Endpoint MigrationThe /v1/automations endpoints have been renamed to /v1/payment-routes. The old /v1/automations paths remain available as deprecated aliases during migration. Update your integrations to use /v1/payment-routes as the deprecated endpoints will be removed in a future release.

Overview

Onramps let your users convert fiat to stablecoin through a persistent payment route. When you create an onramp payment route, Rain generates a virtual account with unique banking credentials. Any funds sent to that virtual account are automatically converted to the destination stablecoin and delivered to the destination onchain address. Rain supports USD onramps over ACH and wire, and MXN onramps over SPEI. See MXN onramps for the differences.

Before you begin

Make sure you have:

API access to the payment routes endpoints.
A destination address: an onchain wallet address where converted stablecoin is delivered. This can be a Rain smart contract or an external wallet.
A bank account: your end users need a US bank account to initiate USD transfers, or a Mexican bank account to initiate MXN transfers over SPEI.

Restrictions

Onramp payment routes are subject to the same restrictions & availability rules as any other payment route, plus Rain’s Payments compliance checks. Rain also screens each deposit into a payment route and checks it against your program’s partner-managed limits. A deposit that Rain holds for review shows the transfer status pending_review until Rain releases or returns it.

Key concepts

Payment routes

A payment route creates a persistent pipe between a source and destination. For onramps:

Source: fiat via ACH or wire transfer (USD), or SPEI (MXN).
Destination: an onchain address on a supported chain.

When you create an onramp payment route, Rain generates a depositAddress containing virtual account banking credentials. This virtual account acts as the named beneficiary for incoming fiat transfers. See What a payment route is for how Rain determines direction for both onramps and offramps.

Virtual accounts

Virtual accounts are dedicated banking credentials that Rain generates for receiving fiat transfers, not payment accounts you register yourself. Each onramp payment route generates its own virtual account, giving your users unique ACH and wire transfer details.

First-party and third-party transfers

Virtual accounts support both first-party and third-party incoming transfers:

First-party: the user who owns the payment route sends funds from their own bank account.
Third-party: a different party sends funds to the virtual account on behalf of the user, for example an employer funding an employee’s account.

API flow

Action / API callExternal / userWebhook Rain sends you

The steps above, in text:

#	Actor	Step
–	User	Requests banking details from the partner
1	Partner	Calls `POST /payment-routes`
2	Rain	Returns the route with a `depositAddress`
3	Partner	Provides the virtual account details to the user
4	User	Sends an ACH or wire transfer to the virtual account
5	Rain	Converts the fiat to stablecoin
6	Destination	Receives the stablecoin deposit onchain
7	Rain	Sends a `transactionTransfer` webhook

Create an onramp payment route

To create an onramp payment route, call POST /payment-routes with a fiat source and an onchain destination. See Create an onramp payment route for the full request, response, and field reference; the shape is identical for onramps created from this page.

Destination address formatThe destination address must match the expected format for the destination rail:

EVM chains (Ethereum, Base, Polygon, Arbitrum, Optimism, Avalanche): must be a valid EVM address starting with 0x followed by 40 hexadecimal characters (for example, 0x1234567890abcdef1234567890abcdef12345678).
Solana: must be a valid Solana address in base58 format (32-44 characters).

If the address doesn’t match the destination rail format, the request fails.

MXN onramps

MXN onramps follow the same flow as USD onramps, with MXN as the source currency and SPEI as the rail. The API flow, webhooks, transfer transactions, and error handling on this page apply unchanged. Only the request and the deposit address differ.

Create the payment route

Set source.currency to mxn and source.rail to mx_spei. The destination is an onchain address, as for USD onramps. Optionally, set transferMessage to add a memo to every transaction the route creates. On every payment route, the memo can be up to 23 characters, and only ASCII letters, numbers, and spaces are allowed. destination.referenceId is a deprecated alias for the same value. If you send both, transferMessage takes precedence. This memo is separate from the transferMessage that Rain returns in the route’s depositAddress, described below.

Deposit address

For MXN onramps, the route’s depositAddress carries a CLABE (clabeNumber, Clave Bancaria Estandarizada) and a transferMessage reference that Rain generates, instead of a US account number and routing number:

"depositAddress": {
  "type": "fiat",
  "clabeNumber": "032180000118359719",
  "transferMessage": "REF10421"
}

The user sends a SPEI transfer to the CLABE and includes the transferMessage as the transfer’s concepto, so Rain can match the deposit. A transfer that omits the concepto may not be matched to the route. Rain then converts the funds to the destination stablecoin and delivers them to the onchain address.

Manage payment routes

Use GET /payment-routes, GET /payment-routes/{paymentRouteId}, PATCH /payment-routes/{paymentRouteId}, and DELETE /payment-routes/{paymentRouteId} to list, retrieve, update, and remove onramp payment routes. Only transferMessage and senderFees can change on an onramp route, and MXN routes can’t be updated. See Manage payment routes for the full request and response examples.

Deleting a payment route closes the associated virtual account. A transfer that still arrives at those banking credentials isn’t processed. Rain holds it for manual handling, so contact Rain to return the funds. Notify your users before deleting a payment route.

What happens when funds are received

When a user sends funds to the virtual account:

Funds received: Rain receives the fiat transfer at the virtual account. Deposits under $2.00 don’t create a transfer. Rain sends a microDeposit.received webhook instead.
Transfer created: Rain creates a transaction of type transfer and sends a transactionTransfer webhook with action created.
Conversion: Rain automatically converts funds to the destination stablecoin.
Transfer: Rain sends stablecoin to the destination onchain address.
Transfer completed: the transfer reaches a final state, and Rain sends a transactionTransfer webhook with action completed.

Webhooks

Rain sends webhooks through the transfer lifecycle:

Resource	Action	Description
`transactionTransfer`	`created`	Sent when the transfer is created after funds are received
`transactionTransfer`	`updated`	Sent when Rain holds the transfer for review (`pending_review`), releases it, or returns the funds (`refunded`, with a `refundReason`)
`transactionTransfer`	`completed`	Sent when the transfer settles and crypto is delivered

There is no separate failure webhook. A returned deposit arrives as updated with status refunded; see Refund reasons. See Money Movement Webhooks for how a transfer moves through these events, and the transfer object reference for the full webhook payload schema.

Transfer transaction

Each successful onramp creates a transfer transaction that you can query via the Transactions API. Filter by type=transfer to see all transfer transactions. Example transfer transaction response:

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "type": "transfer",
  "transfer": {
    "userId": "11111111-1111-1111-1111-111111111111",
    "source": {
      "amount": "100.00",
      "currency": "usd",
      "rail": "ach",
      "originator": "ACME CORPORATION",
      "memo": "Invoice 10425",
      "referenceId": "021000029123456"
    },
    "destination": {
      "amount": "99.50",
      "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"
    },
    "fees": {
      "rain": { "currency": "usd", "amount": "0.50", "amountUSD": "0.50" },
      "sender": { "currency": "usd", "amount": "0.00", "amountUSD": "0.00" }
    },
    "exchangeRate": 1.0,
    "status": "settled",
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T10:45:00Z"
  }
}

To list the transfer transactions for a specific user, see View a virtual account’s transactions.

Settlement times

Transfer times vary by rail:

Rail	Typical settlement
ACH	1-3 business days
Wire	Same business day
SPEI	Near real-time

After fiat settlement, the conversion and onchain transfer typically complete within minutes.

Cutoff times

ACH and wire processing is subject to banking cutoff times. Transfers received after the cutoff are processed on the next business day.

Rail	Cutoff Time	Notes
ACH (Same-Day)	4:00 PM ET	Transfers submitted after this cutoff are processed the next business day
Wire (Fedwire)	5:45 PM ET	Transfers submitted after this cutoff are processed the next business day
SPEI (MXN)	None	SPEI operates 24/7, 365 days a year, so transfers are processed continuously

ACH and wire cutoff times apply on US business days only. ACH and wire transfers initiated on weekends or US federal holidays are processed on the next business day. SPEI transfers aren’t affected.

Supported configurations

Source (fiat)

Currency	Rails
USD	ACH, Wire
MXN	SPEI

Destination (crypto)

Currency	Rails (Chains)
USDC	Ethereum, Base, Polygon, Arbitrum, Optimism, Avalanche, Celo, Solana

MXN onramps are enabled per program. Contact your Rain representative to turn them on.

Rain regularly adds additional currencies and chains. Contact your Rain representative for the latest supported configurations.

Error handling

Errors return the HTTP status, its reason, and a message. Schema validation errors also carry "code": "FST_ERR_VALIDATION".

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid destination address for base rail"
}

Common errors when creating a payment route:

HTTP status	When it happens	What to do
`400`	The request is invalid: `source` or `destination` uses a currency or rail Rain doesn’t support (`body/source/rail must be equal to one of the allowed values`), the destination address doesn’t match the rail (`Invalid destination address for base rail`), or a route with the same source and destination already exists (`A payment route with the same source and destination already exists`).	Fix the request. Check the supported configurations above, or reuse the existing route.
`403`	Payment routes aren’t enabled for your program or for the rail (`Non-USD payment routes are not enabled for your team`), payment routes are blocked for the user or company, the user or company isn’t approved yet (`Team is not approved`), or a regional or industry restriction applies (`"code": "REGION_RESTRICTED"` or `"INDUSTRY_RESTRICTED"`).	Contact your Rain representative, or check restrictions & availability.
`404`	The user or company doesn’t exist.	Verify the `userId` or `companyId`.
`422`	Rain can’t verify the user’s or company’s compliance status (`"code": "COMPLIANCE_NOT_VERIFIED"`).	Complete the customer’s verification, then retry.
`503`	Rain can’t verify eligibility right now (`Eligibility could not be verified right now. Please try again.`).	Retry after a short delay.

Best practices

Monitor webhooks: set up webhook handlers to track transfer status in real time instead of polling.
Handle failures gracefully: fiat transfers can fail due to bank issues on the sender’s side. Implement retry logic and user notifications.
Validate destination addresses client-side: catch malformed onchain addresses before calling POST /payment-routes to avoid a round trip on an avoidable error.

What’s next

Payment routes

See the full request, response, and field reference shared by onramps and offramps.

Set up offramps

Enable fiat withdrawals from crypto.

Partner-managed limits

Set limits on onramp and offramp volume and handle deposits that exceed them.

Set up webhooks

Receive transfer notifications as they happen.

Introduction

Move Money with Payment Routes

Move Money with Quotes and Transfers

Set Fees and Limits

Track Money Movement

Overview

Before you begin

Restrictions

Key concepts

Payment routes

Virtual accounts

First-party and third-party transfers

API flow

Create an onramp payment route

MXN onramps

Create the payment route

Deposit address

Manage payment routes

What happens when funds are received

Webhooks

Transfer transaction

Settlement times

Cutoff times

Supported configurations

Source (fiat)

Destination (crypto)

Error handling

Best practices

What’s next

Payment routes

Set up offramps

Partner-managed limits

Set up webhooks

​Overview

​Before you begin

​Restrictions

​Key concepts

​Payment routes

​Virtual accounts

​First-party and third-party transfers

​API flow

​Create an onramp payment route

​MXN onramps

​Create the payment route

​Deposit address

​Manage payment routes

​What happens when funds are received

​Webhooks

​Transfer transaction

​Settlement times

​Cutoff times

​Supported configurations

​Source (fiat)

​Destination (crypto)

​Error handling

​Best practices

​What’s next

Payment routes

Set up offramps

Partner-managed limits

Set up webhooks

Overview

Before you begin

Restrictions

Key concepts

Payment routes

Virtual accounts

First-party and third-party transfers

API flow

Create an onramp payment route

MXN onramps

Create the payment route

Deposit address

Manage payment routes

What happens when funds are received

Webhooks

Transfer transaction

Settlement times

Cutoff times

Supported configurations

Source (fiat)

Destination (crypto)

Error handling

Best practices

What’s next