HIFI Docs

⏱️ 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": "TERMS_OF_SERVICE_URL",
  "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": "ustestbusiness@gmail.com",
  "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": "ustestbusiness@gmail.com",
  "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:

string

required

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

string

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

string

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

string

URL to the supporting document if required by regulations.

string

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

object

required

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

Show properties

number

required

Amount of USDC to convert from Business A’s wallet

string

required

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

string

required

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

string

required

Business A’s user ID (the payer)

string

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

object

required

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

Show properties

string

required

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

string

required

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

string

required

Business B’s user ID (the recipient)

number

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

string

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

string

Message for wire transfers

array

Optional: Developer fees to collect on the transaction.

Show properties

array

Show properties

string

Fee type: PERCENTAGE or FLAT

string

Fee value (percentage or flat amount)

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": "ustestbusiness@gmail.com",
        "lastName": null,
        "firstName": null,
        "businessName": "US Test Business"
      }
    },
    "destination": {
      "userId": "e06caa8a-4c0f-58d7-95a5-baf676e1e39a",
      "amount": 75.63,
      "currency": "hkd",
      "user": {
        "email": "hkgtestbusiness@gmail.com",
        "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:

string

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

string

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

string

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

object

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

Show properties

string

Business A’s ID

string

Business A’s name

string

Blockchain network

string

Source cryptocurrency

number

Amount of crypto being converted

string

Business A’s wallet address

object

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

Show properties

string

Business B’s ID

string

Business B’s name

string

Business B’s bank account ID

string

Destination fiat currency

number

Amount of fiat Business B will receive (in HKD)

string

Payment reference that will appear on bank statement

object

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

Show properties

object

Show properties

string

Total USDC amount before fees

string

Currency code

object

Show properties

string

USDC amount after deducting fees

string

Currency code

object

Show properties

string

Tax fee amount

string

Fee currency

object

Show properties

string

Payment rail processing fee

string

Fee currency

object

Show properties

string

Total HKD amount before destination fees

string

Currency code

object

Show properties

string

Final HKD amount Business B will receive

string

Currency code

string

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

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": "ustestbusiness@gmail.com",
        "lastName": null,
        "firstName": null,
        "businessName": "US Test Business"
      }
    },
    "destination": {
      "userId": "e06caa8a-4c0f-58d7-95a5-baf676e1e39a",
      "amount": 75.63,
      "currency": "hkd",
      "user": {
        "email": "hkgtestbusiness@gmail.com",
        "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

​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