Offramps with Transfers

Enable users to offramp crypto to international fiat currencies using quotes and transfers for cross-border payments.

Overview

Offramps with transfers let your users convert stablecoin to international fiat currencies through a quote-based flow. Unlike payment routes, which create persistent pipes for USD offramps, transfers are one-time operations with locked exchange rates and fees. Use transfers for international payouts to currencies like COP, MXN, and BRL.

The process involves three steps:

1. Create a payment account: register the user’s bank account details as a payment account.
2. Create a quote: get a quote with the exchange rate, fees, and destination amount.
3. Create a transfer: execute the transfer using the quote before it expires.

Before you begin

Make sure you have:

• API access to the payment accounts, quotes, and transfers endpoints.
• User bank account details: the destination bank account information (details vary by country and rail).
• A stablecoin source: users need stablecoin on a supported chain to transfer.

Key concepts

Payment accounts

A payment account is a stored representation of a user’s bank account or other fiat destination. See Payment Accounts for the general concept and the US-specific fields; this page covers the additional fields required for international destinations. For international transfers, you’ll create an externalFiatAccount type payment account containing the user’s bank details for the destination country.

Quotes

A quote locks in the exact exchange rate, fees, and destination amount for a transfer, unlike an exchange rate preview, which is indicative only and doesn’t lock anything in. Quotes have an expiration time, so you must create the transfer before the quote expires. Key information in a quote includes:

• Exchange rate: the rate used for currency conversion, excluding fees.
• Fees: breakdown of Rain fees and any sender fees.
• Destination amount: the exact amount the user receives in fiat.
• Expiration: when the quote expires and is no longer valid.

Transfers

A transfer executes the movement of funds from crypto to fiat using a locked quote. When you create a transfer, Rain generates a depositAddress where the user sends their stablecoin. Once Rain receives the funds, it automatically converts and sends them to the destination bank account.

API flow

Action / API callExternal / networkWebhook Rain sends you

The steps above, in text:

#	Actor	Step
–	User	Provides bank details to you
1	You	Calls POST /payment-accounts
2	Rain	Returns the payment account
3	You	Calls POST /quotes
4	Rain	Returns the quote with exchange rate and fees
5	You	Displays the quote details to the user
6	You	Calls POST /transfers
7	Rain	Returns the transfer with a depositAddress
8	You	Provides the deposit address to the user
9	User	Sends stablecoin to the deposit address
10	Rain	Converts the stablecoin to fiat
11	Bank	Receives the fiat transfer
12	Rain	Sends a transactionTransfer webhook

Step 1: create a payment account

Before creating a quote, register the user’s bank account as a payment account with Create a payment account. Set externalFiatAccount.currency and rail to the destination’s currency and rail. The other required fields vary by country and rail, so see Payment account details for the fields each rail requires, including the extra beneficiary identification some rails need for third-party payouts.

Set thirdParty to false when the bank account belongs to the user initiating the transfer, or to true when it belongs to a different party, such as a vendor. The response returns the payment account’s id, which you reference when you create a quote.

Additional fields may be required depending on the transfer amount or specific compliance requirements. Contact your Rain representative for detailed requirements.

Step 2: create a quote

Once you have a payment account, request a quote to see the exchange rate, fees, and destination amount.

Request

Call Create a quote with the userId, a source (amount, currency and rail), and a destination (currency, rail, and an address of type paymentAccount with its id).

You can optionally specify a source address if you know which wallet will be sending the funds. Some rails may require this information.

Response

{
  "id": "8a2b3c4d-5e6f-7890-abcd-ef1234567890",
  "source": {
    "amount": "100",
    "currency": "usdc",
    "rail": "base"
  },
  "destination": {
    "amount": "415000",
    "currency": "cop",
    "rail": "co_ach",
    "address": {
      "type": "paymentAccount",
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
    }
  },
  "exchangeRate": 4200,
  "fees": {
    "rain": {
      "currency": "usdc",
      "amount": "1",
      "amountUSD": "1"
    },
    "sender": {
      "currency": "usdc",
      "amount": "0.5",
      "amountUSD": "0.5"
    }
  },
  "expiresAt": "2025-01-15T10:45:00Z"
}

Quote fields

Field	Description
id	Unique identifier for the quote; pass this as quoteId when creating a transfer
source.amount	The amount of crypto the user sends
destination.amount	The amount of fiat the user receives
exchangeRate	The conversion rate (fiat per crypto unit), excluding fees
fees.rain	The fee charged to your platform
fees.sender	The fee you charge to the end user (configurable)
expiresAt	When this quote expires; create the transfer before this time

Quotes expire after a short period (typically 15 minutes). If the quote expires, you must create a new quote before creating a transfer.

Step 3: create a transfer

If the user is happy with the exchange rate and fees, create a transfer using the quote.

Request

Call Create a transfer with the quoteId from the quote. The parameters and headers are below.

Request parameters

Parameter	Type	Required	Description
quoteId	string	Yes	The ID of a valid, unexpired quote
refundAddress	string	Yes	The onchain address Rain returns funds to if the transfer fails or is refunded.
transferMessage	string	No	Optional message for the transfer. Must contain only ASCII alphanumeric characters and spaces. Maximum 50 characters.

Headers

Header	Required	Description
Api-Key	Yes	Your API key
Content-Type	Yes	Must be application/json
idempotency-key	Yes	A unique identifier for the request to ensure idempotent processing. Use this to safely retry requests without creating duplicate transfers.

Reusing an idempotency-key with a different request body returns a 409 conflict. Generate a new key for each distinct transfer.

Response

The response includes the transfer details along with a depositAddress where the user sends their stablecoin:

{
  "id": "1234abcd-5678-4901-9ef0-23456789abcd",
  "type": "transfer",
  "transfer": {
    "userId": "11111111-1111-1111-1111-111111111111",
    "source": {
      "amount": "100",
      "currency": "usdc",
      "rail": "base"
    },
    "destination": {
      "amount": "415000",
      "currency": "cop",
      "rail": "co_ach",
      "address": {
        "type": "paymentAccount",
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    },
    "exchangeRate": 4200,
    "fees": {
      "rain": {
        "currency": "usdc",
        "amount": "1",
        "amountUSD": "1"
      },
      "sender": {
        "currency": "usdc",
        "amount": "0.5",
        "amountUSD": "0.5"
      }
    },
    "quoteId": "8a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "status": "pending",
    "createdAt": "2025-01-15T10:40:00Z",
    "updatedAt": "2025-01-15T10:40:00Z",
    "expiresAt": "2025-01-16T10:40:00Z",
    "depositAddress": {
      "type": "onchain",
      "address": "0xabcdef1234567890abcdef1234567890abcdef12"
    }
  }
}

Response fields

Field	Description
userId / companyId	Identifies the owner of the transfer. userId for consumer accounts, companyId for corporate accounts. Mutually exclusive.
source.amount, destination.amount	The crypto amount sent and fiat amount received, same as on the quote
exchangeRate, fees	Locked in from the quote and unchanged for the life of the transfer
quoteId	The quote this transfer was created from
status	Current state of the transfer. See Transfer statuses below.
refundReason	Why Rain returned the funds. Present on refunded transfers. See Refund reasons.
createdAt, updatedAt	When the transfer was created and last updated
expiresAt	When the transfer expires if the user doesn’t deposit funds in time
depositAddress	The onchain address the user sends stablecoin to

The depositAddress is unique to this transfer. Only send the exact source amount of the specified currency (for example, 100 USDC on Base) to this address. Sending other tokens or incorrect amounts may result in failed transfers or loss of funds.

Deposit window

The transfer’s expiresAt is the deadline for sending funds to the deposit address: 24 hours after the transfer is created. This is separate from the quote’s expiresAt, which only limits when the transfer can be created. The exchange rate and fees from the quote hold for the whole deposit window.

If no deposit arrives by expiresAt, the transfer moves to expired. Funds sent after that are not converted at the original rate or a new one. Contact Rain support to have them returned to the sender.

What happens when a user deposits crypto

Rain creates the transfer when you call POST /transfers, and sends a transactionTransfer webhook with action created right away. Its status is awaiting_transfer until funds arrive.

When a user then sends stablecoin to the deposit address:

1. Crypto received: Rain detects the incoming stablecoin transfer.
2. Validation: Rain validates the amount and currency against the transfer.
3. Conversion: Rain converts the stablecoin to the destination fiat currency.
4. Status updates: as the transfer progresses, Rain sends transactionTransfer webhooks with action updated for status changes.
5. Fiat transfer: Rain sends the funds to the user’s bank account via the specified rail.
6. Transfer completed: the transfer settles, and Rain sends a transactionTransfer webhook with action completed.

Webhooks

Rain sends webhooks during the transfer lifecycle to keep you informed of status changes:

Resource	Action	Description
transactionTransfer	created	Sent when you create the transfer, before the sender’s funds arrive
transactionTransfer	updated	Sent when the transfer status changes during processing, including a hold for review (pending_review) and a return of the funds (refunded)
transactionTransfer	completed	Sent when the fiat transfer settles at the destination bank

See Money Movement Webhooks for how a transfer moves through these events, and the transfer object reference for the full webhook payload schema.

Transfer statuses

Status	Description
pending	Transfer created, waiting for crypto deposit
awaiting_transfer	Transfer initialized, awaiting funds to be sent to the deposit address
processing	Funds received, conversion and fiat transfer in progress
pending_review	Rain is holding the transfer for review before it continues
settled	Fiat successfully delivered to destination
failed	Transfer failed
cancelled	Transfer was cancelled before completion
expired	Transfer expired before the user deposited funds
refunded	Rain returned the funds to the sender. See Refund reasons

Rain checks a transfer against your program’s partner-managed limits when you create it. A transfer over the limit is rejected with 400 Bad Request.

Query transfers

You can query all transfer transactions via the Transactions API. Filter by type=transfer to see transfer transactions.

To get a specific transaction by ID, call Get a transaction by its ID.

Cancel a transfer

To cancel a transfer that hasn’t completed, call DELETE /v1/transfers/{transactionId} with the transaction ID the create call returned.

A successful cancel returns 200 with the transfer, its status now cancelled. Once a transfer passes the point where Rain can stop it, the call returns 409 with Transfer can no longer be cancelled.

Supported configurations

Source (crypto)

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

Destination (fiat)

Currency	Country	Rails
USD	United States	ach, wire
MXN	Mexico	mx_spei
CAD	Canada	ca_interac
BRL	Brazil	br_pix, br_ted
COP	Colombia	co_ach, co_bre_b, co_mobile_wallet
ARS	Argentina	ar_transfers_3
EUR	Eurozone	sepa
GBP	United Kingdom	gb_local
KES	Kenya	ke_pesalink
NGN	Nigeria	ng_local
ZAR	South Africa	za_local
SAR	Saudi Arabia	sa_mada
INR	India	in_neft, in_imps
PHP	Philippines	ph_local
AED	United Arab Emirates	ae_uaefts
AUD	Australia	au_becs
MYR	Malaysia	my_duitnow
TRY	Turkey	tr_local
IDR	Indonesia	id_local
CNY	China	cn_cnaps
CLP	Chile	cl_tef
PEN	Peru	pe_cce
THB	Thailand	th_local
VND	Vietnam	vn_ibps
DOP	Dominican Republic	do_ach
HNL	Honduras	hn_local
UYU	Uruguay	uy_local
AOA	Angola	✱
BDT	Bangladesh	✱
BOB	Bolivia	✱
CRC	Costa Rica	✱
CZK	Czechia	✱
DKK	Denmark	✱
EGP	Egypt	✱
ETB	Ethiopia	✱
GHS	Ghana	✱
GTQ	Guatemala	✱
HUF	Hungary	✱
ILS	Israel	✱
JMD	Jamaica	✱
JPY	Japan	✱
MWK	Malawi	✱
NPR	Nepal	✱
NOK	Norway	✱
PKR	Pakistan	✱
PLN	Poland	✱
QAR	Qatar	✱
RON	Romania	✱
RWF	Rwanda	✱
RSD	Serbia	✱
SGD	Singapore	✱
KRW	South Korea	✱
LKR	Sri Lanka	✱
SEK	Sweden	✱
CHF	Switzerland	✱
TZS	Tanzania	✱
UGX	Uganda	✱
UAH	Ukraine	✱
XOF	West Africa (WAEMU)	✱

See Money Movement Limits for per-corridor limits, supported use cases, settlement times and cutoffs, and Payment Account Details for the bank fields each rail requires.

✱ Supported currencies available upon request. Contact your Rain representative to enable them for your organization.

Error handling

Errors return the HTTP status, its reason, and a message:

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Quote has already been used"
}

Errors that happen after Rain creates a transfer don’t come back on the request. Track them through the transfer’s status and refundReason instead. For example, a deposit window that runs out moves the transfer to expired, and a deposit that doesn’t match the transfer is refunded with the reason amount_mismatch. See Refund reasons.

Quote errors

HTTP status	When it happens	What to do
400	The request is invalid: a missing or malformed field, an amount out of range, or a currency and rail combination Rain can’t route.	Fix the request. Check the supported configurations above and Money Movement Limits.
401	The API key is missing or invalid.	Send a valid API key.
403	Money movement or the requested rail isn’t enabled for your organization, the user or company isn’t approved yet, or the payment account belongs to a different user or company.	Contact your Rain representative, or verify the user’s status and payment account.
404	The user, company, or payment account doesn’t exist.	Verify the IDs.
503	The quote service is temporarily unavailable.	Retry after a short delay.

Transfer errors

HTTP status	When it happens	What to do
400	The request is invalid (for example a missing refundAddress or idempotency-key, or an invalid transferMessage), the quote has expired, or the balance is insufficient.	Fix the request, or create a new quote.
401	The API key is missing or invalid.	Send a valid API key.
403	Transfers aren’t enabled for your organization, or the quote belongs to a different organization.	Contact your Rain representative, or use a quote your organization created.
404	The quote doesn’t exist.	Verify the quoteId.
409	The quote was already used, the idempotency-key was reused with a different request body, or another request for the same account is in progress.	Create a new quote, use a new key for a new transfer, or retry shortly.
422	The sender’s KYC is incomplete. The body includes "code": "SENDER_KYC_INCOMPLETE".	Complete the user’s KYC, then retry.
503	The transfer service is temporarily unavailable.	Retry with the same idempotency-key.

A 503 can happen after Rain has already started the transfer. Retry with the same idempotency-key so Rain returns the existing transfer instead of creating a duplicate. Never retry a 503 with a new key.

Best practices

1. Use idempotency keys: always include a unique idempotency-key header with each transfer request to prevent duplicate transfers on retries.
2. Display quote details: show users the exchange rate, fees, and destination amount before they confirm the transfer.
3. Handle expiration: implement logic to refresh quotes if the user takes too long to confirm.
4. Monitor webhooks: set up webhook handlers to track transfer status in real time.
5. Validate bank details: create payment accounts during user onboarding to catch errors early.
6. Provide clear instructions: make sure users understand they must send the exact amount to the deposit address.
7. Handle 503 responses: retry a 503 with the same idempotency-key, never a new one.

What’s next

Set up onramps

Enable fiat deposits into crypto.

Set up offramps

Enable fiat withdrawals from crypto via payment routes.

Payment accounts

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

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.