Skip to main content
An Offramp Account is a user’s external bank account where they receive fiat money from stablecoin conversions. When users offramp, their stablecoins are converted to fiat and sent directly to this registered account.

​
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: 
curl -X POST "https://sandbox.hifibridge.com/v2/users/usr_abc123/accounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rail": "offramp",
    "type": "us",
    "accountHolder": {
      "type": "individual",
      "name": "John Doe",
      "phone": "+18573491112",
      "email": "[email protected]",
      "address": {
        "addressLine1": "123 Main St",
        "city": "New York",
        "stateProvinceRegion": "NY",
        "postalCode": "10010",
        "country": "USA"
      }
    },
    "us": {
      "transferType": "wire",
      "accountType": "checking",
      "accountNumber": "99485843",
      "routingNumber": "011002877",
      "bankName": "HIFI Bank",
      "currency": "usd"
    }
  }'
Request Fields:
​
rail
string
required
Always offramp for offramp accounts.
​
type
string
required
Account region. For US accounts, use us.
​
accountHolder
object
required
Account holder information. Must match user’s KYC data for compliance.
​
us
object
required
US-specific bank account details.
Response: 
{
  "status": "ACTIVE",
  "invalidFields": [],
  "message": "Account created successfully",
  "id": "acc_abc123"
}
Response Fields:
​
id
string
Unique account ID. Save this for creating offramp transfers to this account.
​
status
string
Account status: ACTIVE (ready to use), PENDING (being validated), or REJECTED (validation failed)
​
invalidFields
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. 
curl -X POST "https://sandbox.hifibridge.com/v2/users/usr_abc123/accounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rail": "offramp",
    "type": "chinaGlobalNetwork",
    "accountHolder": {
      "type": "individual",
      "name": "John Doe",
      "dateOfBirth": "1990-01-01",
      "idNumber": "110101199001011234",
      "nationality": "CHN",
      "address": {
        "addressLine1": "123 Main Street",
        "city": "Beijing",
        "stateProvinceRegion": "BJ",
        "postalCode": "100000",
        "country": "CHN"
      }
    },
    "chinaGlobalNetwork": {
      "bankName": "Industrial and Commercial Bank of China",
      "accountNumber": "6222021234567890123",
      "swiftCode": "ICBKCNBJ",
      "currency": "cny"
    }
  }'
Additional Fields Required:
  • dateOfBirth - Account holder’s date of birth
  • idNumber - Chinese national ID number
  • nationality - Must be CHN
  • swiftCode - Bank’s SWIFT code
curl -X POST "https://sandbox.hifibridge.com/v2/users/usr_abc123/accounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rail": "offramp",
    "type": "hongKongGlobalNetwork",
    "accountHolder": {
      "type": "individual",
      "name": "John Doe",
      "dateOfBirth": "1990-01-01",
      "idNumber": "A123456(7)",
      "nationality": "HKG",
      "address": {
        "addressLine1": "123 Main Street",
        "city": "Hong Kong",
        "stateProvinceRegion": "HK",
        "postalCode": "000000",
        "country": "HKG"
      }
    },
    "hongKongGlobalNetwork": {
      "bankName": "HSBC",
      "accountNumber": "123456789",
      "swiftCode": "HSBCHKHHHKH",
      "currency": "hkd"
    }
  }'
Additional Fields Required:
  • dateOfBirth - Account holder’s date of birth
  • idNumber - Hong Kong ID number
  • nationality - Must be HKG
  • swiftCode - Bank’s SWIFT code
curl -X POST "https://sandbox.hifibridge.com/v2/users/usr_abc123/accounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rail": "offramp",
    "type": "brazilGlobalNetwork",
    "accountHolder": {
      "type": "individual",
      "name": "John Doe",
      "dateOfBirth": "1990-01-01",
      "idNumber": "12345678901",
      "nationality": "BRA",
      "address": {
        "addressLine1": "Rua 123",
        "city": "São Paulo",
        "stateProvinceRegion": "SP",
        "postalCode": "01000-000",
        "country": "BRA"
      }
    },
    "brazilGlobalNetwork": {
      "pix": "[email protected]",
      "currency": "brl"
    }
  }'
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)
curl -X POST "https://sandbox.hifibridge.com/v2/users/usr_abc123/accounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rail": "offramp",
    "type": "mexicoGlobalNetwork",
    "accountHolder": {
      "type": "individual",
      "name": "John Doe",
      "dateOfBirth": "1990-01-01",
      "idNumber": "ABCD123456EFGH7890",
      "nationality": "MEX",
      "address": {
        "addressLine1": "Calle 123",
        "city": "Ciudad de México",
        "stateProvinceRegion": "CMX",
        "postalCode": "01000",
        "country": "MEX"
      }
    },
    "mexicoGlobalNetwork": {
      "speiClabe": "012345678901234567",
      "currency": "mxn"
    }
  }'
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
curl -X POST "https://sandbox.hifibridge.com/v2/users/usr_abc123/accounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rail": "offramp",
    "type": "nigeriaGlobalNetwork",
    "accountHolder": {
      "type": "individual",
      "name": "John Doe",
      "dateOfBirth": "1990-01-01",
      "idNumber": "12345678901",
      "nationality": "NGA",
      "address": {
        "addressLine1": "Street 123",
        "city": "Lagos",
        "stateProvinceRegion": "LA",
        "postalCode": "100001",
        "country": "NGA"
      }
    },
    "nigeriaGlobalNetwork": {
      "bankName": "Access Bank",
      "accountNumber": "1234567890",
      "currency": "ngn"
    }
  }'
Additional Fields Required:
  • dateOfBirth - Account holder’s date of birth
  • idNumber - Nigerian national ID or BVN
  • nationality - Must be NGA

​
Africa Rail Accounts

Africa Rail supports multiple countries with bank accounts and mobile money (momo) payments. 
curl -X POST "https://sandbox.hifibridge.com/v2/users/usr_abc123/accounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rail": "offramp",
    "type": "africa",
    "accountHolder": {
      "type": "individual",
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+256123456789",
      "address": {
        "addressLine1": "Street 123",
        "city": "Kampala",
        "stateProvinceRegion": "C",
        "postalCode": "256",
        "country": "UGA"
      }
    },
    "africa": {
      "financialInstitute": "MTN",
      "accountType": "momo",
      "accountNumber": "1234567890",
      "currency": "ugx",
      "country": "uga"
    }
  }'
Africa-Specific Fields:
​
africa.financialInstitute
string
required
Financial institution name (e.g., MTN, Vodafone, specific bank names)
​
africa.accountType
string
required
Account type: momo (mobile money) or bank
​
africa.accountNumber
string
required
Account or mobile money number
​
africa.currency
string
required
Currency code (e.g., ugx, kes, ugx)
​
africa.country
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: 
curl -X POST "https://sandbox.hifibridge.com/v2/offramps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "currency": "usdc",
      "chain": "POLYGON",
      "userId": "usr_abc123",
      "amount": 100
    },
    "destination": {
      "currency": "usd",
      "accountId": "acc_abc123",
      "userId": "usr_abc123"
    },
    "requestId": "b08e27be-c086-4b84-a321-307ed9f265e1"
  }'
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:
StatusDescription
ACTIVEAccount validated and ready to receive funds
PENDINGAccount being validated (typically resolves within minutes)
REJECTEDValidation failed - check invalidFields for specific issues

​
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
  • 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

curl -X POST "https://sandbox.hifibridge.com/v2/users/usr_abc123/accounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rail": "offramp",
    "type": "us",
    "accountHolder": {
      "type": "individual",
      "name": "John Doe",
      "phone": "+18573491112",
      "email": "[email protected]",
      "address": {
        "addressLine1": "123 Main St",
        "city": "New York",
        "stateProvinceRegion": "NY",
        "postalCode": "10010",
        "country": "USA"
      }
    },
    "us": {
      "transferType": "wire",
      "accountType": "checking",
      "accountNumber": "99485843",
      "routingNumber": "011002877",
      "bankName": "HIFI Bank",
      "currency": "usd"
    }
  }'
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.
{
  "status": "ACTIVE",
  "id": "acc_abc123"
}
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:
curl -X POST "https://sandbox.hifibridge.com/v2/offramps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "currency": "usdc",
      "chain": "POLYGON",
      "userId": "usr_abc123",
      "amount": 100
    },
    "destination": {
      "currency": "usd",
      "accountId": "acc_abc123",
      "userId": "usr_abc123"
    },
    "requestId": "b08e27be-c086-4b84-a321-307ed9f265e1"
  }'

​
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:
curl -X POST "https://sandbox.hifibridge.com/v2/users/usr_abc123/accounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rail": "offramp",
    "type": "us",
    "accountHolder": {
      "type": "individual",
      "name": "John Doe",
      "address": {
        "addressLine1": "123 Main St",
        "city": "New York",
        "stateProvinceRegion": "NY",
        "postalCode": "10010",
        "country": "USA"
      }
    },
    "us": {
      "transferType": "wire",
      "accountType": "Checking",
      "accountNumber": "99485843",
      "routingNumber": "011002877",
      "bankName": "HIFI Bank",
      "currency": "usd"
    }
  }'
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

  • 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