HIFI Developer Docs

Enable businesses to send money internationally through stablecoins with instant settlement. Leverage HIFI’s global network to reach recipients in multiple countries with low fees and transparent exchange rates. ⏱️ Time to complete: 35-45 minutes 🎯 What you’ll build: A complete cross-border payment flow where a US business pays a Hong Kong supplier, converting USD → USDC → HKD with instant settlement and competitive rates.

Use Case Overview

This recipe demonstrates an international B2B payment where:

✅ US business deposits USD from their bank account
✅ USD automatically converts to USDC stablecoin
✅ USDC transfers instantly across borders
✅ HKD is deposited to supplier’s Hong Kong bank account

This flow enables fast, cost-effective international business payments with transparent pricing and instant settlement.

What you’ll build

Here’s what we’ll accomplish in this recipe:

Generate API Keys - Set up authentication for HIFI API
Create Business A (Payer) - Onboard US business and complete KYB for USD rail
Add Virtual Account - Set up account for USD deposits that convert to USDC
Create Business B (Payee) - Onboard Hong Kong supplier (or use existing business)
Execute Payment - Send USDC from Business A → HKD to Business B’s bank account

Payment Flow:

USD → Business A Bank Account → USDC → Business A Wallet → HKD → Business B Bank Account

All examples in this guide use the sandbox environment. When you’re ready for production, simply replace the sandbox URL with the production endpoint and use your production API keys.

Generate API Keys

Access to the HIFI API requires authentication via API keys. Generate your keys from the HIFI Dashboard before making any API calls. Be sure to copy the key immediately as it’s only shown once. For a complete guide on API authentication, see our Authentication Documentation.

Using Your API Key

Include your API key in the Authorization header of all API requests:

--header 'authorization: Bearer YOUR_API_KEY'

Create Business A (US Payer)

The paying business needs a verified business account to access fiat rails and send international payments. Every business must accept HIFI’s Terms of Service and complete KYB (Know Your Business) verification before they can move money between fiat and crypto.

Complete Business Onboarding Guide: For a comprehensive walkthrough of business onboarding and KYB verification, see our Business User Guide.

Generate Terms of Service Link

Request:

curl --request POST \
  --url https://sandbox.hifibridge.com/v2/tos-link \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '
{
  "idempotencyKey": "96bc39ba-c6c6-412a-9452-e95a35d3f533"
}
'

Response:

{
  "url": "https://dashboard.hifibridge.com/accept-terms-of-service?sessionToken=a29d65a3...",
  "signedAgreementId": "96bc39ba-c6c6-412a-9452-e95a35d3f533"
}

What to do with this response:

Direct the business to the url - Send this link via email or embed in your application
Save the signedAgreementId - You’ll need this to create the business user
Wait for acceptance - The signedAgreementId becomes valid only after they click “Accept”

Create Business User

Request:

curl --request POST \
  --url https://sandbox.hifibridge.com/v2/users \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '
{
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "type": "business",
  "chains": ["POLYGON"],
  "email": "[email protected]",
  "dateOfBirth": "2023-12-25",
  "address": {
    "addressLine1": "4550 Market Street",
    "city": "Philadelphia",
    "stateProvinceRegion": "PA",
    "postalCode": "19104",
    "country": "USA"
  },
  "ipAddress": "127.0.0.1",
  "signedAgreementId": "96bc39ba-c6c6-412a-9452-e95a35d3f533",
  "businessName": "US Test Business",
  "ultimateBeneficialOwners": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "dateOfBirth": "1980-01-01",
      "hasControl": true,
      "isSigner": true
    }
  ]
}
'

Response:

{
  "id": "94dcd5c2-4508-593d-9302-fd7a5444eb20",
  "type": "business",
  "email": "[email protected]",
  "name": "US Test Business",
  "wallets": {
    "INDIVIDUAL": {
      "POLYGON": {
        "address": "0x0466DCD644Ae2Ee5d88CF0e1976c3ce237A0D760"
      },
      "ETHEREUM": {
        "address": "0x6e3D1de74422a9259578302Fd1e9eb203EACB2E8"
      }
    }
  }
}

Update KYB Information

Request:

curl --request POST \
  --url https://sandbox.hifibridge.com/v2/users/94dcd5c2-4508-593d-9302-fd7a5444eb20/kyc \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '
{
  "firstName": "US Test Business",
  "nationality": "USA",
  "taxIdentificationNumber": "678898765"
}
'

Response:The response includes comprehensive business information including UBO details, business structure, compliance questionnaires, and uploaded documents.

Submit KYB for USD Rail

Request:

curl --request POST \
  --url https://sandbox.hifibridge.com/v2/users/94dcd5c2-4508-593d-9302-fd7a5444eb20/kyc/submissions \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '
{
  "rails": "USD"
}
'

Response:

{
  "USD": {
    "status": "CREATED",
    "message": "Your KYC application has been successfully created. We will review it shortly."
  }
}

Add Virtual Account (Business A)

Now that Business A has passed KYB, create a Virtual Account for onramping. This is a bank account number automatically created by HIFI that the business can deposit USD into. When fiat arrives, it’s automatically converted to USDC and sent to their wallet.

Complete Virtual Account Guide: For more details on virtual accounts and onramping, see our Virtual Accounts Guide.

Create Virtual Account

Request:

curl --request POST \
  --url https://sandbox.hifibridge.com/v2/users/94dcd5c2-4508-593d-9302-fd7a5444eb20/virtual-accounts \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '
{
  "sourceCurrency": "usd",
  "destinationCurrency": "usdc",
  "destinationChain": "POLYGON"
}
'

Response:

{
  "message": "Virtual account created successfully",
  "accountInfo": {
    "id": "c3d1b830-a57c-54d8-a103-df4e0713ff82",
    "createdAt": "2025-11-13T20:15:03.187Z",
    "updatedAt": "2025-11-13T20:15:03.187Z",
    "provider": "CROSS_RIVER",
    "userId": "94dcd5c2-4508-593d-9302-fd7a5444eb20",
    "source": {
      "paymentRail": ["ach", "wire", "rtp"],
      "currency": "usd"
    },
    "destination": {
      "chain": "POLYGON",
      "currency": "usdc",
      "walletAddress": "0x0466DCD644Ae2Ee5d88CF0e1976c3ce237A0D760",
      "externalWalletId": null
    },
    "status": "activated",
    "microDeposits": {
      "count": 0,
      "data": []
    },
    "depositInstructions": {
      "bankName": "Cross River Bank",
      "bankAddress": "885 Teaneck Road, Teaneck, NJ 07666",
      "beneficiary": {
        "name": "US Test Business",
        "address": "1234 Walnut Street, Suite 1200, Philadelphia, PA, 19107, US"
      },
      "ach": {
        "routingNumber": "021214891",
        "accountNumber": "388125286772"
      },
      "wire": {
        "routingNumber": "021214891",
        "accountNumber": "388125286772"
      },
      "rtp": {
        "routingNumber": null,
        "accountNumber": null
      },
      "reference": null,
      "depositBy": null,
      "instruction": "Please deposit usd to the bank account provided. Please ensure that the beneficiary name matches the account holder name provided, or the payment may be rejected."
    },
    "settlementRuleId": null
  }
}

Create Business B (HK Payee)

The recipient business (Business B in Hong Kong) needs a business account with an HKD bank account to receive the payment. Follow the same business creation flow as Business A, but complete KYB for the appropriate Hong Kong rail.

Using an Existing Business: If Business B already exists in your system, you can skip business creation and just ensure they have an active Hong Kong bank account. You’ll need their userId and accountId for the payment transaction.

Required Information

To complete this recipe, you’ll need:

Business B’s userId - From creating their business account
Business B’s HKD accountId - From adding their Hong Kong bank account

For the complete flow of creating Business B and adding their HKD bank account, follow the same steps as Business A but:

Use Hong Kong business information and address details
Submit KYB for the Hong Kong rail
Add an Offramp Account (Hong Kong bank account) instead of a Virtual Account

For detailed instructions on adding offramp accounts for international recipients, see our Offramp Guide.

Execute Payment

Now you can send the international payment from Business A (US) to Business B (Hong Kong). Create an offramp transaction that converts USDC to HKD and sends it to Business B’s Hong Kong bank account. This is a two-step process:

Create offramp request - Get a quote for the conversion
Accept the quote - Execute the payment

Complete Offramp Guide: For more details on offramps and cross-border transfers, see our Offramp Guide.

Create Offramp Request

Create an offramp request to get a quote for converting 10 USDC to HKD using the Create an offramp endpoint.Request:

curl --request POST \
  --url https://sandbox.hifibridge.com/v2/offramps \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '
{
  "requestId": "e6c2e4fc-83d2-4e3b-9836-7ff57f2709be",
  "purposeOfPayment": "payment_for_services",
  "supportingDocumentType": "billing_document",
  "description": "Payment for supplier services",
  "source": {
    "amount": 10,
    "currency": "usdc",
    "chain": "POLYGON",
    "userId": "94dcd5c2-4508-593d-9302-fd7a5444eb20"
  },
  "destination": {
    "currency": "hkd",
    "accountId": "556d4f54-2514-4d10-ac93-c2aff03d2de5",
    "userId": "e06caa8a-4c0f-58d7-95a5-baf676e1e39a",
    "paymentReference": "Invoice #12345"
  }
}
'

Request Fields:

requestId

string

required

Unique identifier (UUID) for this offramp request to ensure idempotency.

purposeOfPayment

string

Purpose of the payment for compliance. Common values for B2B: payment_for_services, payment_for_goods, invoice_payment, contract_payment, etc.

supportingDocumentType

string

Type of supporting document if required. Options: billing_document, invoice, contract, purchase_order, etc.

supportingDocumentUrl

string

URL to the supporting document if required by regulations.

description

string

Description of the payment (e.g., invoice number, contract reference).

source

object

required

Source of the offramp (crypto side - Business A).

Show properties

amount

number

required

Amount of USDC to convert from Business A’s wallet

currency

string

required

Source cryptocurrency (e.g., usdc, usdt)

chain

string

required

Blockchain network (e.g., POLYGON, ETHEREUM)

userId

string

required

Business A’s user ID (the payer)

externalWalletId

string

Optional external wallet ID if using a wallet outside HIFI’s custody

destination

object

required

Destination of the offramp (fiat side - Business B).

Show properties

currency

string

required

Destination fiat currency (e.g., hkd for Hong Kong Dollars)

accountId

string

required

Business B’s bank account ID where HKD will be deposited

userId

string

required

Business B’s user ID (the recipient)

amount

number

Optional: Specify destination amount if you want to send an exact fiat amount

paymentReference

string

Payment reference text (e.g., invoice number, order ID) that will appear on the recipient’s bank statement

wireMessage

string

Message for wire transfers

developerFee

array

Optional: Developer fees to collect on the transaction.

Show properties

fees

array

Show properties

type

string

Fee type: PERCENTAGE or FLAT

value

string

Fee value (percentage or flat amount)

walletAddress

string

Wallet address to receive the fee

Response:

{
  "transferType": "OFFRAMP",
  "transferDetails": {
    "id": "63b7f9de-31e9-4726-bf5c-b4f21a6af796",
    "requestId": "e6c2e4fc-83d2-4e3b-9836-7ff57f2709be",
    "createdAt": "2025-11-17T14:36:15.277Z",
    "updatedAt": "2025-11-17T14:36:16.377Z",
    "status": "OPEN_QUOTE",
    "failedReason": null,
    "error": null,
    "errorDetails": null,
    "source": {
      "userId": "94dcd5c2-4508-593d-9302-fd7a5444eb20",
      "chain": "POLYGON",
      "currency": "usdc",
      "amount": 10,
      "walletAddress": "0x0466DCD644Ae2Ee5d88CF0e1976c3ce237A0D760",
      "user": {
        "email": "[email protected]",
        "lastName": null,
        "firstName": null,
        "businessName": "US Test Business"
      }
    },
    "destination": {
      "userId": "e06caa8a-4c0f-58d7-95a5-baf676e1e39a",
      "amount": 75.63,
      "currency": "hkd",
      "user": {
        "email": "[email protected]",
        "lastName": null,
        "firstName": null,
        "businessName": "HKG Test Business"
      },
      "accountId": "556d4f54-2514-4d10-ac93-c2aff03d2de5",
      "paymentReference": "Invoice #12345"
    },
    "receipt": {},
    "quoteInformation": {
      "sendGross": {
        "amount": "10.000000",
        "currency": "usdc"
      },
      "sendNet": {
        "amount": "9.730000",
        "currency": "usdc"
      },
      "taxFee": {
        "amount": "0.170000",
        "currency": "usdc"
      },
      "railFee": {
        "amount": "0.100000",
        "currency": "usdc"
      },
      "receiveGross": {
        "amount": "75.63",
        "currency": "hkd"
      },
      "receiveNet": {
        "amount": "75.63",
        "currency": "hkd"
      },
      "rate": "7.563000",
      "expiresAt": "2025-11-17T14:37:14.946+00:00"
    },
    "depositInformation": []
  }
}

✅ Offramp quote created!Response Fields:

transferDetails.id

string

Unique offramp transaction ID. Save this - you’ll need it to accept the quote and monitor status.

transferDetails.type

string

Transfer type. Always OFFRAMP for cross-border payment transactions.

transferDetails.status

string

Current status. OPEN_QUOTE means you have an active quote waiting to be accepted.

transferDetails.source

object

Source details showing Business A’s wallet and amount being sent.

Show properties

userId

string

Business A’s ID

businessName

string

Business A’s name

chain

string

Blockchain network

currency

string

Source cryptocurrency

amount

number

Amount of crypto being converted

walletAddress

string

Business A’s wallet address

transferDetails.destination

object

Destination details showing Business B’s bank account and amount they’ll receive.

Show properties

userId

string

Business B’s ID

businessName

string

Business B’s name

accountId

string

Business B’s bank account ID

currency

string

Destination fiat currency

amount

number

Amount of fiat Business B will receive (in HKD)

paymentReference

string

Payment reference that will appear on bank statement

transferDetails.quoteInformation

object

Critical: Detailed breakdown of the conversion including exchange rate, fees, and amounts.

Show properties

sendGross

object

Show properties

amount

string

Total USDC amount before fees

currency

string

Currency code

sendNet

object

Show properties

amount

string

USDC amount after deducting fees

currency

string

Currency code

taxFee

object

Show properties

amount

string

Tax fee amount

currency

string

Fee currency

railFee

object

Show properties

amount

string

Payment rail processing fee

currency

string

Fee currency

receiveGross

object

Show properties

amount

string

Total HKD amount before destination fees

currency

string

Currency code

receiveNet

object

Show properties

amount

string

Final HKD amount Business B will receive

currency

string

Currency code

rate

string

Exchange rate (USDC to HKD). In this example: 1 USDC ≈ 7.56 HKD

expiresAt

string

Quote expiration timestamp (ISO 8601 format)

Understanding the Quote:In this example:

Business A sends 10 USDC
After fees (tax: 0.170 USDC, rail: 0.100 USDC), 9.73 USDC is converted
At a rate of 7.56 HKD per USDC
Business B receives 75.63 HKD in their Hong Kong bank account

Quote Expiration: Quotes typically expire after 15-30 minutes to protect against exchange rate volatility. If your quote expires before acceptance, create a new offramp request for a fresh quote with updated rates.

Accept Quote and Execute Payment

After reviewing the quote, exchange rate, and fees, accept it to execute the cross-border payment using the Accept Quote endpoint.Request:

curl --request POST \
  --url https://sandbox.hifibridge.com/v2/offramps/63b7f9de-31e9-4726-bf5c-b4f21a6af796/quote/accept \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR_API_KEY'

Response:

{
  "transferType": "OFFRAMP",
  "transferDetails": {
    "id": "63b7f9de-31e9-4726-bf5c-b4f21a6af796",
    "requestId": "e6c2e4fc-83d2-4e3b-9836-7ff57f2709be",
    "createdAt": "2025-11-17T14:36:15.277Z",
    "updatedAt": "2025-11-17T14:36:16.377Z",
    "status": "CRYPTO_INITIATED",
    "failedReason": null,
    "error": null,
    "errorDetails": null,
    "source": {
      "userId": "94dcd5c2-4508-593d-9302-fd7a5444eb20",
      "chain": "POLYGON",
      "currency": "usdc",
      "amount": 10,
      "walletAddress": "0x0466DCD644Ae2Ee5d88CF0e1976c3ce237A0D760",
      "user": {
        "email": "[email protected]",
        "lastName": null,
        "firstName": null,
        "businessName": "US Test Business"
      }
    },
    "destination": {
      "userId": "e06caa8a-4c0f-58d7-95a5-baf676e1e39a",
      "amount": 75.63,
      "currency": "hkd",
      "user": {
        "email": "[email protected]",
        "lastName": null,
        "firstName": null,
        "businessName": "HKG Test Business"
      },
      "accountId": "556d4f54-2514-4d10-ac93-c2aff03d2de5",
      "paymentReference": "Invoice #12345"
    },
    "receipt": {},
    "quoteInformation": {
      "sendGross": {
        "amount": "10.000000",
        "currency": "usdc"
      },
      "sendNet": {
        "amount": "9.730000",
        "currency": "usdc"
      },
      "taxFee": {
        "amount": "0.170000",
        "currency": "usdc"
      },
      "railFee": {
        "amount": "0.100000",
        "currency": "usdc"
      },
      "receiveGross": {
        "amount": "75.63",
        "currency": "hkd"
      },
      "receiveNet": {
        "amount": "75.63",
        "currency": "hkd"
      },
      "rate": "7.563000",
      "expiresAt": "2025-11-17T14:37:14.946+00:00"
    },
    "depositInformation": []
  }
}

✅ Quote accepted! Cross-border payment is processing.The status has changed from OPEN_QUOTE to CRYPTO_INITIATED, meaning the transaction is now being executed.Cross-Border Payment Status Progression:

OPEN_QUOTE - Quote generated, waiting for acceptance
CRYPTO_INITIATED - Processing crypto conversion
CRYPTO_PENDING - Waiting for blockchain confirmation
FIAT_PENDING - Converting to HKD and initiating bank transfer
COMPLETED - HKD deposited to Business B’s Hong Kong bank account

Monitoring Payment Status:Track the payment progress using:

Polling: Call Retrieve an offramp with the transaction ID (63b7f9de-31e9-4726-bf5c-b4f21a6af796)
Webhooks: Subscribe to OFFRAMP.UPDATE events for real-time status notifications

Settlement Times:

Sandbox: Instant simulation for testing
Production: Typically 1-3 business days depending on the destination country’s banking system and payment rail

Business Payment Notifications: Consider implementing webhook handlers to send notifications to both Business A (payer) and Business B (recipient) as the payment progresses. Include transaction details, exchange rates, and expected settlement times to provide transparency and improve cash flow management.

🎉 Congratulations!

You’ve successfully completed a cross-border business payment! By following this recipe, you can now:

✅ Generate API keys and authenticate with HIFI
✅ Onboard businesses and complete KYB for multiple currency rails
✅ Create virtual accounts for fiat-to-crypto conversion
✅ Execute international payments with instant settlement via stablecoins
✅ Provide transparent fee structures and competitive exchange rates

Next Steps

Ready to build a full cross-border payment platform? Here’s what to explore next:

Webhooks - Set up real-time notifications for payment status updates and settlement confirmations
Rails Overview - Explore additional currency corridors to expand your global payment coverage
Offramp Guide - Deep dive into offramp transactions, compliance requirements, and settlement rules
Business User Guide - Learn about KYB requirements, UBO verification, and business document management
Error Handling - Implement robust error handling for failed transactions, expired quotes, and compliance issues
API Reference - Explore all available endpoints and parameters for advanced features

Guides

Recipes

Global Transfers

Use Case Overview

What you’ll build

Generate API Keys

Create Business A (US Payer)

Add Virtual Account (Business A)

Create Business B (HK Payee)

Required Information

Execute Payment

🎉 Congratulations!

Next Steps

Guides

Recipes

​Use Case Overview

​What you’ll build

​Generate API Keys

​Create Business A (US Payer)

​Add Virtual Account (Business A)

​Create Business B (HK Payee)

​Required Information

​Execute Payment

​🎉 Congratulations!

​Next Steps

Use Case Overview

What you’ll build

Generate API Keys

Create Business A (US Payer)

Add Virtual Account (Business A)

Create Business B (HK Payee)

Required Information

Execute Payment

🎉 Congratulations!

Next Steps