Skip to main content

​
How Offramp Accounts Work

1

Register bank account

Add the user’s external bank account to HIFI by providing account details and account holder information.
2

Create offramp

Initiate an offramp transfer to get a conversion quote with current exchange rates and fees.
3

Accept quote

Accept the quote to execute the conversion. Stablecoins are converted to fiat and delivered to the registered bank account.
Each offramp account is configured for a specific currency and region (e.g., USD in the US, BRL in Brazil). You can create multiple offramp accounts per user for different currencies and regions.

​
Prerequisites

KYC Required: Users must complete KYC verification for the relevant rail before creating offramp accounts. For example, to create a USD offramp account, the user must have an active USD rail.

​
Creating Offramp Accounts

Create an offramp account using the Create Account endpoint. The required fields vary by region and currency.

​
USD Accounts

For USD offramps to US bank accounts:
Request Fields:
​
string
required
Always offramp for offramp accounts.
​
string
required
Account region. For US accounts, use us.
​
object
required
Account holder information.
​
object
required
US-specific bank account details.
Response:
Response Fields:
​
string
Unique account ID. Save this for creating offramp transfers to this account.
​
string
Account status: ACTIVE (ready to use), PENDING (being validated), or REJECTED (validation failed)
​
array
List of validation errors. Empty array means all fields are valid.

​
Global Network Accounts

Global Network accounts support multiple countries including China, Hong Kong, Brazil, Mexico, and Nigeria. These accounts require additional verification fields.
Additional Fields Required:
  • dateOfBirth - Account holder’s date of birth
  • idNumber - Chinese national ID number
  • nationality - Must be CHN
  • swiftCode - Bank’s SWIFT code
Additional Fields Required:
  • dateOfBirth - Account holder’s date of birth
  • idNumber - Hong Kong ID number
  • nationality - Must be HKG
  • swiftCode - Bank’s SWIFT code
Additional Fields Required:
  • dateOfBirth - Account holder’s date of birth
  • idNumber - CPF (Brazilian tax ID)
  • nationality - Must be BRA
  • pix - PIX key (email, phone, or CPF)
Additional Fields Required:
  • dateOfBirth - Account holder’s date of birth
  • idNumber - CURP (Mexican national ID)
  • nationality - Must be MEX
  • speiClabe - 18-digit CLABE number for SPEI transfers
Additional Fields Required:
  • dateOfBirth - Account holder’s date of birth
  • idNumber - Nigerian national ID or BVN
  • nationality - Must be NGA

​
Africa Rail Accounts (Beta)

Africa Rail supports multiple countries with bank accounts and mobile money (momo) payments.
Africa-Specific Fields:
​
string
required
Financial institution name (e.g., MTN, Vodafone, specific bank names)
​
string
required
Account type: momo (mobile money) or bank
​
string
required
Account or mobile money number
​
string
required
Currency code (e.g., ugx, kes, ugx)
​
string
required
Country code (e.g., uga, ken, gha)
Check the Africa Rail documentation for supported combinations of country, currency, and financial institution.

​
Using Offramp Accounts

Once created and active, reference the account when creating offramp transfers using the Create Offramp endpoint. Request:
The accountId from the account creation response tells HIFI which bank account should receive the fiat funds.
Complete Offramp Flow: See the Offramps documentation for the full process including quote acceptance, status tracking, and settlement timing.

​
Account Validation

After creating an offramp account, HIFI validates the account details:

​
Key Concepts

Users can have multiple offramp accounts for different currencies, regions, or payment methods. Each account has a unique ID referenced when creating offramps.Example scenarios:
  • One USD account for wire transfers
  • One BRL account for PIX transfers
  • One MXN account for SPEI transfers
  • Multiple accounts in the same currency for different banks
Don’t confuse these two concepts: - Account Type (type field): The region or country (e.g., us, brazil, mexico) - Transfer Type (within account-specific fields): The payment method (e.g., wire, ach, pix, spei) Not all transfer types are available in all regions. Check the API reference for supported combinations.
Offramp accounts support two payment scenarios: First Party Payments: Funds sent to the account holder (the user who completed KYC). This is the standard case where users receive money in their own bank account. Third Party Payments: Funds sent to someone other than the account holder. This enables use cases like: - Sending money to family members - Paying business partners or vendors - Disbursing funds to beneficiaries Both are supported, but third party payments may require additional compliance verification.
Different regions support different payment methods:
  • US: Wire, ACH, RTP
  • Brazil: PIX (instant payments)
  • Mexico: SPEI (electronic transfers)
  • Africa: Mobile money (momo) or bank transfers depending on country
  • China/Hong Kong: Bank transfers with SWIFT codes
Choose the payment method that best fits your users’ needs and local banking infrastructure.

​
Sample Code

​
Create and validate account

1

Create the account

2

Check validation status

The response includes the status. If ACTIVE, the account is ready immediately. If PENDING, wait for validation to complete or subscribe to account webhooks.
For REJECTED status, check the invalidFields array to see which fields need correction.
3

Use for offramps

Once active, use the account ID when creating offramp transfers:

​
Support multicurrency payouts

1

Create accounts for each region

Create separate accounts for each region where you need to send payouts (offramps) to the user:
2

Let users choose destination

If a user has multiple accounts, let them select which account to use when creating an offramp. Pass the appropriate accountId based on their selection.

​
Getting Help

  • 📧 Email: support@hifi.com
  • 💬 Slack: Message us in our shared Slack channel
  • Quickstart Guide - Step-by-step tutorial
  • Rails - Understand KYC requirements for different rails
  • Offramps - Complete guide to executing offramp transfers
  • Webhooks - Real-time account validation notifications
  • API Reference - Complete endpoint documentation