Use Case Overview
This recipe demonstrates a cross-border remittance payment where:- ✅ User A deposits USD from their US bank account
- ✅ USD automatically converts to USDC stablecoin
- ✅ USDC is sent and converted to MXN pesos
- ✅ MXN is deposited to User B’s Mexican bank account
Prerequisites
Before you start, make sure you have:- API keys from the Dashboard (Get API keys)
- A tool for making API calls (cURL, Postman, or similar)
- Basic understanding of REST APIs
- Your sandbox endpoint:
https://sandbox.hifibridge.com
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.
What you’ll build
Here’s what we’ll accomplish in this recipe:- Generate API Keys - Set up authentication for HIFI API
- Create User A - Onboard the sender and complete KYC for USD rail
- Add Virtual Account - Set up account for USD deposits that convert to USDC
- Create User B - Onboard the recipient (or use existing user)
- Execute Remittance - Send USDC from User A → MXN to User B’s bank account
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.Get Your API Keys
Get Your API Keys
Steps:
- Navigate to dashboard.hifibridge.com
- Log in to your account
- Go to Developer → API Keys
- Click Generate New Key
- Select your environment: Sandbox (for testing) or Production (for live transactions)
- Copy the key immediately - it’s only shown once
- Store your API key securely (environment variables, secrets manager, etc.)
- Never commit API keys to version control
- Your key authenticates all HIFI API requests
- If compromised, immediately revoke in the Dashboard and generate a new one
Authorization header of all API requests:Create User A (Sender)
The sender needs a verified user account to access fiat rails and send remittances. Every user must accept HIFI’s Terms of Service and complete KYC verification before they can move money between fiat and crypto.Complete Onboarding Guide: For a comprehensive walkthrough of user
onboarding and KYC verification, see our User Guide.
User Creation Flow
Creating a user involves four steps:- Generate Terms of Service Link - Get acceptance link for your customer
- Create User - Create the user account after TOS acceptance
- Update KYC Information - Provide required personal details
- Submit KYC - Submit for verification to unlock USD rail
Generate Terms of Service Link
Generate Terms of Service Link
Before creating a user, they must accept HIFI’s Terms of Service. Generate a unique acceptance link using the Generate Terms of Service Link endpoint.Request:Request Fields:Response:Response Fields:What to do with this response:
A unique UUID that becomes your
signedAgreementId after the user accepts the
terms. Generate this using any UUID
generator.The unique link where your user will review and accept HIFI’s Terms of
Service.
The agreement ID (same as your
idempotencyKey). Save this - you’ll need
it to create the user in the next step.- Direct your user to the
url- Present this link to your end user (via email, in your app, etc.) - Save the
signedAgreementId- You’ll need this to create the user in the next step - Wait for acceptance - The
signedAgreementIdbecomes valid only after the user clicks “Accept”
Real-time Notifications: HIFI triggers the
TOS_LINK.UPDATE webhook event
when the user accepts the terms, allowing you to proceed with user creation
immediately. Learn about webhooks →Create User
Create User
Once your user has accepted the Terms of Service, create the user account with the Create User endpoint.Request:Request Fields:Response:✅ User created successfully!Response Fields:What you get:
User type. Use
individual for personal accounts or business for business
accounts.User’s first name.
User’s last name.
User’s email address.
User’s date of birth in YYYY-MM-DD format.
User’s residential address.
The
signedAgreementId from the Terms of Service acceptance.Unique identifier (UUID) for this request to ensure idempotency.
The unique user ID. Save this - you’ll use it for all future operations
with this user.
Automatically provisioned wallet addresses on supported blockchain networks.
- User ID (
3b77cec8-1bb9-5ea0-91a1-e8c1411dd429) - Save this for all future operations - Wallet addresses - Pre-provisioned on multiple blockchains, ready to use immediately
Automatic Wallet Provisioning: Every user automatically receives wallet
addresses on supported blockchain networks (Polygon, Ethereum, etc.). These
wallets are fully functional immediately - no additional setup required.
Update KYC Information
Update KYC Information
Provide the required personal information for KYC verification using the Update KYC endpoint.Request:Request Fields:Response:✅ Personal information updated!
User’s first name (can be used to update if needed).
User’s phone number with country code (E.164 format).
Tax identification number (e.g., SSN for US users).
User’s nationality (ISO 3166-1 alpha-3 country code).
Document Upload: For a complete KYC submission in production, you’ll also
need to upload identity documents (passport, driver’s license, etc.). See the
Quickstart Guide for detailed document upload
instructions.
Submit KYC for USD Rail
Submit KYC for USD Rail
Submit the KYC application to unlock the USD rail using the Submit KYC endpoint.Request:Request Fields:Response:✅ KYC approved! USD rail is now active.Response Fields:
The currency rail to unlock. Use
USD for US Dollar operations.Overall KYC status.
ACTIVE means the USD rail is unlocked and the user can
now onramp and offramp USD.High-level review outcome.
Detailed review results broken down by category.
Sandbox Auto-Approval: In sandbox, KYC applications are typically
automatically approved within minutes. In production, review typically takes
1-3 business days.
Add Virtual Account (User A)
Now that User A has passed KYC, create a Virtual Account for onramping. This is a bank account number automatically created by HIFI that User A 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
Create Virtual Account
A Virtual Account enables User A to deposit USD from their bank, which automatically converts to USDC on Polygon.Request:Request Fields:Response:✅ Virtual account created!Response Fields:
Fiat currency to deposit. Use
usd for US Dollars.Stablecoin to receive after conversion. Use
usdc for USD Coin.Blockchain network for the stablecoin. Options:
POLYGON, ETHEREUMThe unique virtual account ID. Save this for monitoring deposits.
Account status.
activated means it’s ready to receive deposits.Source configuration for fiat deposits.
Destination configuration for crypto conversion.
Most Important: Bank account details User A needs to send money to.
How to Use: Provide these deposit instructions to User A through your
app/website. When they send money to this account via their bank, HIFI
automatically detects the deposit, converts it to USDC, and sends it to their
wallet. For monitoring deposits, subscribe to
ONRAMP.CREATE webhook events.Create User B (Recipient)
The recipient (User B) needs a user account with amexicoGlobalNetwork account to receive the remittance. Follow the same user creation flow as User A, but complete KYC for the GLOBAL_NETWORK rail instead of USD.
Using an Existing User: If User B already exists in your system, you can
skip user creation and just ensure they have an active
mexicoGlobalNetwork
account. You’ll need their userId and accountId for the remittance
transaction.Required Information for User B
To complete this recipe, you’ll need:- User B’s
userId- From creating their user account - User B’s MXN
accountId- From adding their Mexican bank account
- Submit KYC for the
GLOBAL_NETWORKrail instead of USD - Add a
mexicoGlobalNetworkaccount (Mexican bank account) instead of a Virtual Account
Execute Transaction
Now you can send the remittance from User A to User B. Create an offramp transaction that converts USDC to MXN and sends it to User B’s Mexican bank account. This is a two-step process:- Create offramp request - Get a quote for the conversion
- Accept the quote - Execute the remittance
Complete Offramp Guide: For more details on offramps and cross-border
transfers, see our Offramp Transfer Guide.
Create Offramp Request
Create Offramp Request
Create an offramp request to get a quote for converting 11 USDC to MXN using the Create an offramp endpoint.Request:Request Fields:Response:✅ Offramp quote created!Response Fields:Understanding the Quote:In this example:
Unique identifier (UUID) for this offramp request to ensure idempotency.
Purpose of the payment for compliance. Common values:
payment_for_services,
family_support, gift, salary, etc.Type of supporting document if required. Options:
billing_document,
invoice, contract, etc.URL to the supporting document if required by the destination country’s
regulations.
Optional description of the payment.
Source of the offramp (crypto side - User A).
Destination of the offramp (fiat side - User B).
Optional: Developer fees to collect on the transaction.
Unique offramp transaction ID. Save this - you’ll need it to accept the
quote and monitor status.
Transfer type. Always
OFFRAMP for remittance transactions.Current status.
OPEN_QUOTE means you have an active quote waiting to be
accepted.Source details showing User A’s wallet and amount being sent.
Destination details showing User B’s bank account and amount they’ll receive.
Critical: Detailed breakdown of the conversion including exchange rate,
fees, and amounts.
- User A sends 11 USDC
- After fees (tax: 0.187 USDC, rail: 0.110 USDC), 10.71 USDC is converted
- At a rate of 18.30 MXN per USDC
- User B receives 201.26 MXN in their bank account
Accept Quote and Execute Remittance
Accept Quote and Execute Remittance
After reviewing the quote and fees, accept it to execute the remittance using the Accept Quote endpoint.Request:Response:✅ Quote accepted! Remittance is processing.The status has changed from
OPEN_QUOTE to CRYPTO_INITIATED, meaning the transaction is now being executed.Remittance Status Progression:OPEN_QUOTE- Quote generated, waiting for acceptanceCRYPTO_INITIATED- Processing crypto conversionCRYPTO_PENDING- Waiting for blockchain confirmationFIAT_PENDING- Converting to MXN and initiating bank transferCOMPLETED- MXN deposited to User B’s bank account
- Polling: Call Retrieve an offramp with the transaction ID (
e1821e0a-ba62-4022-83b8-aab9866ee0a1) - Webhooks: Subscribe to
OFFRAMP.UPDATEevents for real-time status notifications
- Sandbox: Instant simulation for testing
- Production: Typically 1-3 business days depending on the destination country and payment rail
User Notifications: Consider implementing webhook handlers to send
notifications to both User A (sender) and User B (recipient) as the remittance
progresses through each status. This provides transparency and builds trust in
your remittance product.
🎉 Congratulations!
You’ve successfully completed a cross-border remittance transaction! By following this recipe, you can now:- ✅ Generate API keys and authenticate with HIFI
- ✅ Onboard users and complete KYC for multiple currency rails
- ✅ Create virtual accounts for fiat-to-crypto conversion
- ✅ Execute cross-border remittances with competitive exchange rates
- ✅ Provide transparent fee structures and quote expiration
Next Steps
Ready to build a full remittance product? Here’s what to explore next:- Webhooks - Set up real-time notifications for transaction status updates and user engagement
- Offramp Guide - Deep dive into offramp transactions and compliance requirements
- Error Handling - Implement robust error handling for failed transactions and expired quotes
- API Reference - Explore all available endpoints and parameters for advanced features