Offramps

Enable users to offramp crypto to fiat using payment routes with payment accounts.

Overview

Offramps let your users convert stablecoin to fiat through a persistent payment route. The process involves two steps:

1. Create a payment account: register the user’s bank account details as a payment account.
2. Create an offramp payment route: set up the route that converts crypto to fiat and sends it to the payment account.

When a user sends stablecoin to the route’s deposit address, funds are automatically converted to fiat and transferred to their registered bank account.

Rain supports USD offramps over ACH and wire, and MXN offramps over SPEI. See MXN offramps for the differences.

Before you begin

Make sure you have:

• API access to the payment accounts and payment routes endpoints.
• User bank account details: the destination bank account information (account number, routing number, and beneficiary details, or a CLABE for MXN).
• A stablecoin source: users need stablecoin on a supported chain to offramp.

Restrictions

Offramp 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 accounts

A payment account is a stored representation of a user’s bank account or other fiat destination. Once created, you can use it as a destination for both payment routes (persistent offramps) and transfers (one-time international payments via quotes). Payment accounts let you:

• Pre-validate bank account details before creating transfers.
• Reuse the same destination across multiple payment routes or transfers.
• Track payments associated with specific accounts.

For offramps, you create an externalFiatAccount type payment account containing the user’s bank details.

Payment routes

An offramp payment route creates a persistent pipe from crypto to fiat:

• Source: stablecoin on a supported chain.
• Destination: a payment account, the user’s bank account.

When you create an offramp payment route, Rain generates a depositAddress containing an onchain wallet address. Any stablecoin sent to this address is automatically converted to fiat and transferred to the payment account.

API flow

Action / API callExternal / networkWebhook Rain sends you

The steps above, in text:

#	Actor	Step
–	User	Provides bank details to the partner
1	Partner	Calls POST /payment-accounts
2	Rain	Returns the payment account
3	Partner	Calls POST /payment-routes
4	Rain	Returns the route with a depositAddress
5	Partner	Provides the deposit address to the user
6	User	Sends stablecoin to the deposit address
7	Rain	Converts the stablecoin to fiat
8	Bank	Receives the fiat transfer
9	Rain	Sends a transactionTransfer webhook

Step 1: create a payment account

Before creating an offramp payment route, you must register the user’s bank account as a payment account. Call POST /payment-accounts with the externalFiatAccount type. See Register a bank account for the full request, response, supported fields, and the first-party/third-party distinction for the account owner.

Step 2: create an offramp payment route

Once you have a payment account, create an offramp payment route by calling POST /payment-routes.

See Create an offramp payment route for the full request, response, and field reference.

Refund address required

The refundAddress field is mandatory when creating an offramp payment route. Set this to a valid onchain address where stablecoin can be returned if a transaction cannot be completed. Funds may be returned due to:

• Destination bank account issues (closed account, invalid details, account restrictions).
• Partner-managed limits being exceeded.
• Compliance or regulatory holds.
• Failed fiat transfers rejected by the receiving bank.

If you don’t provide refundAddress, Rain rejects the payment route creation request. Make sure the refund address is a wallet you control and can receive the source stablecoin on the specified chain.

Address format requirements

The refund address must match the expected format for the source 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 source rail format, the request fails.

The response’s depositAddress is unique to this payment route. Only send the specified source currency (for example, USDC on Base) to this address. Rain doesn’t process or return other tokens automatically, so sending them may result in loss of funds.

MXN offramps

MXN offramps follow the same two steps as USD offramps, with MXN as the destination currency and SPEI as the rail. The refund address, deposit address, webhooks, and transfer transactions work as described on this page. Only the payment account and the route’s destination differ.

Payment account

Register the beneficiary’s Mexican bank account with currency set to mxn, rail set to mx_spei, and a clabeNumber (the account’s 18-digit CLABE) instead of accountNumber and routingNumber. Set beneficiaryType to individual or business and provide the matching name fields, as described in Register a bank account. MXN/SPEI accounts don’t need bankAccountType, beneficiaryAddress, bankName, or bankAddress. See Payment account details for the full field list.

Payment route

Create the route with destination.currency set to mxn, destination.rail set to mx_spei, and destination.address referencing the payment account. Send the refundAddress as for any offramp.

Optionally, set transferMessage. On MXN offramps, this memo surfaces as the reference on the outgoing SPEI transfer to the beneficiary’s bank account. 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.

Once the route is active, stablecoin sent to its depositAddress is converted and sent to the user’s bank account over SPEI. MXN payment routes can’t be updated after creation, and a PATCH returns 422. To change one, delete it and create a new one.

Manage payment accounts

Use GET /payment-accounts, GET /payment-accounts/{paymentAccountId}, and DELETE /payment-accounts/{paymentAccountId} to list, retrieve, and remove payment accounts. See Manage payment accounts for the full request and response examples.

Deleting a payment account doesn’t delete the payment routes that reference it, but those routes can no longer pay out. Delete the payment route first, then delete the payment account.

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 offramp payment routes. Only transferMessage, refundAddress, and senderFees can change, and MXN routes can’t be updated. See Manage payment routes for the full request and response examples.

What happens when crypto is deposited

When a user sends stablecoin to the deposit address:

1. Crypto received: Rain detects the incoming stablecoin transfer. Deposits under 2.00 of the source token don’t create a transfer.
2. Transfer created: Rain creates a transaction of type transfer and sends a transactionTransfer webhook with action created.
3. Conversion: Rain converts stablecoin to fiat.
4. Fiat transfer: Rain sends funds to the user’s bank account via the specified rail.
5. Transfer completed: the transfer settles, 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 crypto is 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 Rain’s outgoing fiat transfer settles

There is no separate failure webhook. A returned transfer, including a bank return after completed, 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 offramp 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": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "type": "transfer",
  "transfer": {
    "userId": "11111111-1111-1111-1111-111111111111",
    "source": {
      "amount": "100.00",
      "currency": "usdc",
      "rail": "base",
      "address": {
        "type": "onchain",
        "address": "0x1234567890abcdef1234567890abcdef12345678"
      },
      "originator": "0x1234567890abcdef1234567890abcdef12345678",
      "referenceId": "0x9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b"
    },
    "destination": {
      "amount": "99.50",
      "currency": "usd",
      "rail": "ach",
      "address": {
        "type": "paymentAccount",
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    },
    "depositAddress": {
      "type": "onchain",
      "address": "0xabcdef1234567890abcdef1234567890abcdef12"
    },
    "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:35:00Z",
    "updatedAt": "2025-01-15T10:40:00Z"
  }
}

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

Settlement times

After crypto is received, fiat transfer times vary by rail:

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

Cutoff times

ACH and wire processing is subject to banking cutoff times. Rain processes transfers initiated after the cutoff 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 (crypto)

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

Destination (fiat)

Currency	Rails
USD	ACH, Wire
MXN	SPEI

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

Rain regularly adds additional currencies and rails. 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": "Refund address is required for crypto source payment routes"
}

Payment account errors

HTTP status	When it happens	What to do
400	A USD account is missing routingNumber, accountNumber, bankAccountType, or beneficiaryAddress (routingNumber is required for USD accounts), the routing number fails the 9-digit ABA check (Invalid routing number), the account number isn’t 4-17 digits (Account number must be 4-17 digits), or the name fields don’t match beneficiaryType.	Verify the details with the user and send every field listed in Payment account details.
403	Non-USD accounts aren’t enabled for your program (Non-USD fiat accounts are not enabled for your team), or payment accounts are blocked for the user or company (Payment accounts not allowed for this user or company).	Contact your Rain representative.
404	The user or company doesn’t exist (User not found, Company not found).	Verify the userId or companyId.

Payment route errors

HTTP status	When it happens	What to do
400	refundAddress is missing or doesn’t match the source rail (Invalid refund address for base rail), the payment account doesn’t exist for this user or company (Payment account not found), its rail or currency doesn’t match the destination (Payment account rail "wire" does not match destination rail "ach"), the banking partner rejects the routing number for wire (Invalid routing number for wire payment account), or a route with the same source and destination already exists.	Fix the request, 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"), or you sent a PATCH to an MXN route (This payment route cannot be updated.).	Complete the customer’s verification, or delete and recreate the MXN route.
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

1. Validate bank details early: create payment accounts during user onboarding to catch errors before the user attempts to offramp.
2. Use nicknames: assign meaningful nicknames to payment accounts for easy identification.
3. Monitor webhooks: set up webhook handlers to track transfer status in real time.
4. Handle failures gracefully: fiat transfers can fail due to bank issues. Implement retry logic and user notifications.

What’s next

Payment accounts

See the full request, response, and field reference for registering a bank account.

Payment routes

See the full request, response, and field reference for creating a payment route.

Set up onramps

Enable fiat deposits into 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.