Offramps with Transfers

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:

Create a payment account: register the user’s bank account details as a payment account.
Create a quote: get a quote with the exchange rate, fees, and destination amount.
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, you must register the user’s bank account as a payment account. The required fields vary by destination country.

Request: Colombian peso (COP)

curl -X POST https://api.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": "Maria Colombia Account",
    "externalFiatAccount": {
      "currency": "cop",
      "rail": "co_ach",
      "thirdParty": false,
      "beneficiaryType": "individual",
      "beneficiaryFirstName": "Maria",
      "beneficiaryLastName": "Garcia",
      "beneficiaryEmail": "maria@example.com",
      "beneficiaryAddress": {
        "line1": "Calle 100 #15-20",
        "city": "Bogota",
        "region": "Bogota D.C.",
        "postalCode": "110111",
        "countryCode": "CO"
      },
      "bankName": "Bancolombia",
      "accountNumber": "12345678901"
    }
  }'

Colombia supports multiple rails: co_ach for bank transfers, co_bre_b for Bancolombia transfers, and co_mobile_wallet for mobile wallet payments.

Request: Mexican peso (MXN)

curl -X POST https://api.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": "Carlos Mexico Account",
    "externalFiatAccount": {
      "currency": "mxn",
      "rail": "mx_spei",
      "thirdParty": false,
      "beneficiaryType": "individual",
      "beneficiaryFirstName": "Carlos",
      "beneficiaryLastName": "Lopez",
      "beneficiaryEmail": "carlos@example.com",
      "beneficiaryAddress": {
        "line1": "Av. Reforma 222",
        "city": "Mexico City",
        "region": "CDMX",
        "postalCode": "06600",
        "countryCode": "MX"
      },
      "bankName": "BBVA Mexico",
      "clabeNumber": "012345678901234567"
    }
  }'

Request: Brazilian real (BRL)

curl -X POST https://api.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": "Ana Brazil Account",
    "externalFiatAccount": {
      "currency": "brl",
      "rail": "br_pix",
      "thirdParty": false,
      "beneficiaryType": "individual",
      "beneficiaryFirstName": "Ana",
      "beneficiaryLastName": "Silva",
      "beneficiaryEmail": "ana@example.com",
      "taxNumber": "123.456.789-00",
      "beneficiaryAddress": {
        "line1": "Rua Augusta 1500",
        "city": "Sao Paulo",
        "region": "SP",
        "postalCode": "01304-001",
        "countryCode": "BR"
      },
      "bankName": "Itau",
      "pixCode": "ana@example.com"
    }
  }'

Brazil supports br_pix for instant PIX payments and br_ted for traditional bank transfers.

First-party and third-party transfersRain supports both first-party and third-party transfer destinations:

First-party (thirdParty: false): the bank account belongs to the same user initiating the transfer.
Third-party (thirdParty: true): the bank account belongs to a different party, for example a vendor or another individual.

Response

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "type": "externalFiatAccount",
  "nickname": "Maria Colombia Account",
  "userId": "11111111-1111-1111-1111-111111111111",
  "externalFiatAccount": {
    "currency": "cop",
    "rail": "co_ach",
    "thirdParty": false,
    "beneficiaryType": "individual",
    "beneficiaryFirstName": "Maria",
    "beneficiaryLastName": "Garcia",
    "beneficiaryEmail": "maria@example.com",
    "beneficiaryAddress": {
      "line1": "Calle 100 #15-20",
      "city": "Bogota",
      "region": "Bogota D.C.",
      "postalCode": "110111",
      "countryCode": "CO"
    },
    "bankName": "Bancolombia",
    "accountNumber": "12345678901"
  },
  "createdAt": "2025-01-15T10:25:00Z"
}

Required fields by rail

Colombia (COP)

Field	`co_ach`	`co_bre_b`	`co_mobile_wallet`
`beneficiaryFirstName`	Required	Required	Required
`beneficiaryLastName`	Required	Required	Required
`beneficiaryEmail`	Required	Required	Required
`beneficiaryAddress`	Required	Required	-
`bankName`	Required	Required	-
`accountNumber`	Required	Required	-
`phoneNumber`	-	-	Required

Mexico (MXN)

Field	`mx_spei`
`beneficiaryFirstName`	Required
`beneficiaryLastName`	Required
`beneficiaryEmail`	Required
`beneficiaryAddress`	Required
`bankName`	Required
`clabeNumber`	Required

Brazil (BRL)

Field	`br_pix`	`br_ted`
`beneficiaryFirstName`	Required	Required
`beneficiaryLastName`	Required	Required
`beneficiaryEmail`	Required	Required
`beneficiaryAddress`	Required	Required
`taxNumber` (CPF/CNPJ)	Required	Required
`bankName`	-	Required
`bankCode`	-	Required
`branchCode`	-	Required
`accountNumber`	-	Required
`pixCode`	Required	-

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

curl -X POST https://api.rain.xyz/v1/quotes \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "ee778224-43fd-4c27-ba26-aa5e8401d0dd",
    "source": {
      "amount": "100",
      "currency": "usdc",
      "rail": "base"
    },
    "destination": {
      "currency": "cop",
      "rail": "co_ach",
      "address": {
        "type": "paymentAccount",
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    }
  }'

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

curl -X POST https://api.rain.xyz/v1/transfers \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: unique-request-id-12345" \
  -d '{
    "quoteId": "8a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "refundAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "transferMessage": "Payment for services"
  }'

Request parameters

Parameter	Type	Required	Description
`quoteId`	string	Yes	The ID of a valid, unexpired quote
`refundAddress`	string	Conditional	The onchain address Rain returns funds to if the transfer fails or is refunded. Required whenever the transfer’s source is a crypto rail; not applicable to a fiat source.
`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-15T11: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.
`createdAt`, `updatedAt`	When the transfer was created and last updated
`expiresAt`	When the transfer expires if funds aren’t deposited 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.

Alternative: fund a transfer from fiat

Instead of funding a transfer with crypto, you can quote a fiat source such as wire or ach. The transfer then comes back with a fiat depositAddress containing bank deposit instructions, and you send the source amount there instead of to an onchain address.

Quote request (fiat source)

curl -X POST https://api.rain.xyz/v1/quotes \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "amount": "100",
      "currency": "usd",
      "rail": "wire"
    },
    "destination": {
      "currency": "cop",
      "rail": "co_ach",
      "address": {
        "type": "paymentAccount",
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    }
  }'

Quote response (fiat source)

{
  "id": "9b3c4d5e-6f7a-8901-bcde-f23456789012",
  "source": {
    "amount": "100",
    "currency": "usd",
    "rail": "wire"
  },
  "destination": {
    "amount": "415000",
    "currency": "cop",
    "rail": "co_ach",
    "address": {
      "type": "paymentAccount",
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
    }
  },
  "exchangeRate": 4200,
  "fees": {
    "rain": {
      "currency": "usd",
      "amount": "1",
      "amountUSD": "1"
    },
    "sender": {
      "currency": "usd",
      "amount": "0.5",
      "amountUSD": "0.5"
    }
  },
  "expiresAt": "2025-01-15T10:45:00Z"
}

Transfer request (fiat source)

curl -X POST https://api.rain.xyz/v1/transfers \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: unique-request-id-67890" \
  -d '{
    "quoteId": "9b3c4d5e-6f7a-8901-bcde-f23456789012",
    "transferMessage": "Payment for services"
  }'

Transfer response (fiat source)

{
  "id": "5678efab-1234-46ab-8def-0123456789ab",
  "type": "transfer",
  "transfer": {
    "companyId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "source": {
      "amount": "100",
      "currency": "usd",
      "rail": "wire"
    },
    "destination": {
      "amount": "415000",
      "currency": "cop",
      "rail": "co_ach",
      "address": {
        "type": "paymentAccount",
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    },
    "exchangeRate": 4200,
    "fees": {
      "rain": {
        "currency": "usd",
        "amount": "1",
        "amountUSD": "1"
      },
      "sender": {
        "currency": "usd",
        "amount": "0.5",
        "amountUSD": "0.5"
      }
    },
    "quoteId": "9b3c4d5e-6f7a-8901-bcde-f23456789012",
    "status": "pending",
    "depositAddress": {
      "type": "fiat",
      "beneficiaryName": "Rain Liquidity LLC",
      "beneficiaryBankName": "SSB BANK",
      "accountNumber": "1234567890",
      "routingNumber": "043087080",
      "transferMessage": "RAIN-8A2B3C4D"
    },
    "createdAt": "2025-01-15T10:40:00Z",
    "updatedAt": "2025-01-15T10:40:00Z",
    "expiresAt": "2025-01-15T11:40:00Z"
  }
}

A fiat-source transfer returns a depositAddress with type: "fiat": the bank deposit instructions to fund it. Send exactly the source amount, and include the transferMessage reference with your payment so Rain can match the funds to the transfer. A fiat source doesn’t need a refundAddress.

What happens when crypto is deposited

When a user sends stablecoin to the deposit address:

Crypto received: Rain detects the incoming stablecoin transfer.
Transfer created: a transaction of type transfer is created, and a transactionTransfer webhook with action created is sent.
Validation: the amount and currency are validated against the transfer.
Conversion: stablecoin is converted to the destination fiat currency.
Status updates: as the transfer progresses, transactionTransfer webhooks with action updated are sent for status changes.
Fiat transfer: funds are sent to the user’s bank account via the specified rail.
Transfer completed: the transfer settles, and a transactionTransfer webhook with action completed is sent.

Webhooks

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

Resource	Action	Description
`transactionTransfer`	`created`	Sent when the transfer is initiated after crypto is received
`transactionTransfer`	`updated`	Sent when the transfer status changes during processing
`transactionTransfer`	`completed`	Sent when the fiat transfer settles at the destination bank

See 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`	Transfer is held for review before it continues processing
`settled`	Fiat successfully delivered to destination
`failed`	Transfer failed (see error details)
`cancelled`	Transfer was cancelled before completion
`expired`	Transfer expired before funds were deposited
`refunded`	Funds were returned to the sender

Query transfers

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

curl -X GET "https://api.rain.xyz/v1/issuing/transactions?type=transfer" \
  -H "Api-Key: YOUR_API_KEY"

Or get a specific transaction by ID:

curl -X GET "https://api.rain.xyz/v1/issuing/transactions/1234abcd-5678-4901-9ef0-23456789abcd" \
  -H "Api-Key: YOUR_API_KEY"

Cancel a transfer

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

curl -X DELETE https://api.rain.xyz/v1/transfers/1234abcd-5678-4901-9ef0-23456789abcd \
  -H "Api-Key: YOUR_API_KEY"

A successful cancel returns 200 with the transfer, its status now cancelled. Once a transfer passes the point where it can be stopped, 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
RUSD	Ethereum, Base, Polygon, Arbitrum, Optimism, Avalanche, Celo, Solana

Source (fiat)

Currency	Rails
USD	`ach`, `wire`

Destination (fiat)

Currency	Country	Rails
COP	Colombia	`co_ach`, `co_bre_b`, `co_mobile_wallet`
MXN	Mexico	`mx_spei`
BRL	Brazil	`br_pix`, `br_ted`

Additional currencies and rails are being added regularly. Contact your Rain representative for the latest supported configurations.

Error handling

Quote errors

Error	Description	Resolution
`quote_expired`	The quote has expired	Create a new quote
`unsupported_currency_pair`	The source/destination currency combination is not supported	Check supported configurations above
`invalid_amount`	The amount is outside allowed limits	Verify minimum/maximum transfer limits
`payment_account_not_found`	The specified payment account doesn’t exist	Verify the payment account ID

Transfer errors

Error	HTTP Status	Description	Resolution
`quote_expired`	400	The quote used for this transfer has expired	Create a new quote and transfer
`invalid_deposit`	400	The deposited amount doesn’t match the expected amount	Ensure the exact amount is sent
`transfer_expired`	400	The transfer expired before funds were deposited	Create a new quote and transfer
`compliance_failed`	400	The transfer failed compliance checks	Contact support for details
`TransferPersistenceError`	503	The transfer was initiated but could not be persisted due to a temporary issue	Don’t retry immediately. The transfer processes asynchronously and completes automatically.

If you receive a 503 response with TransferPersistenceError, your transfer has already been initiated with the payment provider. Rain automatically reconciles the transfer asynchronously. Don’t retry the request, since this could result in duplicate transfers. Use the idempotency-key header to safely handle retries in case of network timeouts.

Best practices

Use idempotency keys: always include a unique idempotency-key header with each transfer request to prevent duplicate transfers on retries.
Display quote details: show users the exchange rate, fees, and destination amount before they confirm the transfer.
Handle expiration: implement logic to refresh quotes if the user takes too long to confirm.
Monitor webhooks: set up webhook handlers to track transfer status in real time.
Validate bank details: create payment accounts during user onboarding to catch errors early.
Provide clear instructions: make sure users understand they must send the exact amount to the deposit address.
Handle 503 responses: if you receive a 503 error, don’t retry immediately. The transfer may have been initiated and is reconciled automatically.

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.

Set up webhooks

Receive transfer notifications as they happen.

​Overview

​Before you begin

​Key concepts

​Payment accounts

​Quotes

​Transfers

​API flow

​Step 1: create a payment account

​Request: Colombian peso (COP)

​Request: Mexican peso (MXN)

​Request: Brazilian real (BRL)

​Response

​Required fields by rail

​Colombia (COP)

​Mexico (MXN)

​Brazil (BRL)

​Step 2: create a quote

​Request

​Response

​Quote fields

​Step 3: create a transfer

​Request

​Request parameters

​Headers

​Response

​Response fields

​Alternative: fund a transfer from fiat

​Quote request (fiat source)

​Quote response (fiat source)

​Transfer request (fiat source)

​Transfer response (fiat source)

​What happens when crypto is deposited

​Webhooks

​Transfer statuses

​Query transfers

​Cancel a transfer

​Supported configurations

​Source (crypto)

​Source (fiat)

​Destination (fiat)

​Error handling

​Quote errors

​Transfer errors

​Best practices

​What’s next

Set up onramps

Set up offramps

Payment accounts

Set up webhooks

Overview

Before you begin

Key concepts

Payment accounts

Quotes

Transfers

API flow

Step 1: create a payment account

Request: Colombian peso (COP)

Request: Mexican peso (MXN)

Request: Brazilian real (BRL)

Response

Required fields by rail

Colombia (COP)

Mexico (MXN)

Brazil (BRL)

Step 2: create a quote

Request

Response

Quote fields

Step 3: create a transfer

Request

Request parameters

Headers

Response

Response fields

Alternative: fund a transfer from fiat

Quote request (fiat source)

Quote response (fiat source)

Transfer request (fiat source)

Transfer response (fiat source)

What happens when crypto is deposited

Webhooks

Transfer statuses

Query transfers

Cancel a transfer

Supported configurations

Source (crypto)

Source (fiat)

Destination (fiat)

Error handling

Quote errors

Transfer errors

Best practices

What’s next