HIFI Docs

Onramp Methods

HIFI supports two onramp methods:

Method	Description	Best For
Virtual Account	Reusable bank account for USD deposits	Recurring USD deposits, simplified flows
Onramp API	One-time virtual account per transaction	USD and Africa currencies via API (Africa Rail beta)

Virtual Accounts for USD: For recurring USD deposits, use reusable Virtual Accounts which provide permanent bank account numbers. The Onramp API generates one-time virtual accounts per transaction and currently supports USD and Africa currencies (Africa Rail beta).

When you create an onramp, HIFI generates a one-time account (unique deposit details) for that transaction. For Africa (Africa Rail beta) you must register an onramp account first and pass source.accountId; for USD you typically omit it and use the one-time deposit instructions in the response. See Onramp Accounts for details.

Using the Onramp API

The Onramp API generates a one-time virtual account for a specific transaction. This method currently supports USD and Africa currencies (Africa Rail beta). The flow is similar to regular virtual accounts, but the bank account details are valid only for this single transaction.

Request Quote

Create an onramp to get a conversion quote using the Create Onramp endpoint. Request:

curl -X POST "https://sandbox.hifibridge.com/v2/onramps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "userId": "usr_abc123",
      "currency": "usd",
      "amount": 100,
      "transferType": "ach"
    },
    "destination": {
      "userId": "usr_abc123",
      "currency": "usdc",
      "chain": "POLYGON"
    },
    "requestId": "e1047def-6942-4fd7-be04-e62eb41813b6"
  }'

The response contains the onramp quote and deposit information:

Response

{
  "transferType": "ONRAMP",
  "transferDetails": {
    "id": "onr_abc123",
    "requestId": "e1047def-6942-4fd7-be04-e62eb41813b6",
    "createdAt": "2025-02-03T17:15:31.927121+00:00",
    "updatedAt": "2025-02-03T17:15:35.882+00:00",
    "status": "AWAITING_FUNDS",
    "source": {
      "userId": "usr_abc123",
      "currency": "usd",
      "amount": 100,
      "transferType": "ach"
    },
    "destination": {
      "userId": "usr_abc123",
      "currency": "usdc",
      "chain": "POLYGON",
      "walletAddress": "0x848732f6c834E05b17C56fa01E83EE095f72C3c3"
    },
    "quoteInformation": {
      "sendGross": {
        "amount": "100.00",
        "currency": "usd"
      },
      "receiveNet": {
        "amount": "100.00",
        "currency": "usdc"
      },
      "rate": "1.0000",
      "expiresAt": "2025-02-04T17:15:31.927Z"
    },
    "depositInfo": {
      "bankName": "Cross River Bank",
      "bankAddress": "885 Teaneck Road, Teaneck, NJ 07666",
      "accountNumber": "11223344556677",
      "routingNumber": "021214891",
      "beneficiary": {
        "name": "HIFI Bridge",
        "address": "123 Main St, New York, NY 10010"
      },
      "referenceId": "BRGWX4J5BB7MP693BT8Z",
      "amount": "100.0",
      "currency": "usd",
      "instruction": "Please deposit the exact amount to the bank account provided. Use the reference ID as the deposit reference."
    },
    "receipt": {
      "transactionHash": null
    }
  }
}

string

Unique onramp ID. Save this for tracking the transaction status.

string

Current status. AWAITING_FUNDS means the quote is ready and waiting for your deposit.

object

Conversion details including rates and amounts.

Show properties

object

Total fiat amount to send

object

Stablecoin amount you’ll receive

string

Exchange rate between fiat and stablecoin

string

Quote expiration timestamp. Deposit must arrive before this time.

object

Most Important: Bank account details for sending your fiat deposit.

Show properties

string

Critical: Include this reference ID with your bank transfer. Without it, your deposit cannot be matched to this onramp.

string

Bank account number for deposit

string

Bank routing number

string

Exact amount to deposit (must match exactly)

string

Deposit instructions and requirements

Send Payment

After receiving the quote, send the exact amount specified in depositInfo to the provided bank account. Critical requirements:

Use the reference ID - Include the referenceId in your bank transfer memo/reference field
Send exact amount - The amount must match depositInfo.amount exactly
Send before expiration - Deposit must arrive before quoteInformation.expiresAt

Reference ID Required: Always include the reference ID with your deposit. Deposits without the correct reference ID cannot be matched to your onramp and may be lost or delayed.

Processing

Once HIFI detects your deposit:

Fiat validation - Confirms amount and reference ID match
Conversion - Exchanges fiat for stablecoins at the quoted rate
Delivery - Sends stablecoins to the destination wallet
Completion - Transaction hash becomes available in receipt.transactionHash

Processing times vary by payment method:

ACH: 1-3 business days
Wire: Same day
RTP: Instant
International transfers: 1-5 business days depending on country

Transaction Status

Onramps progress through several phases:

System Statuses

Status	Description
CREATED	Onramp request created successfully
NOT_INITIATED	Request not submitted due to validation error
OPEN_QUOTE	Quote generated and awaiting deposit
IN_REVIEW	Transaction under review by monitoring systems
QUOTE_FAILED	Quote expired before deposit was received
AWAITING_FUNDS	Waiting for fiat deposit with reference ID

Fiat Processing Phase

Status	Description
FIAT_INITIATED	Deposit detected, fiat processing started
FIAT_PENDING	Fiat clearing and validation in progress
FIAT_PROCESSED	Fiat successfully received and validated
FIAT_FAILED	Fiat processing failed (e.g., invalid amount, missing reference)
FIAT_RETURNED	Fiat returned to sender after failure

Crypto Processing Phase

Status	Description
CRYPTO_INITIATED	Converting fiat to stablecoins
CRYPTO_PENDING	Sending stablecoins on blockchain
CRYPTO_FAILED	Blockchain transaction failed
COMPLETED	Stablecoins delivered to wallet, transaction complete

Failed Deposits and Returns

An onramp can fail on either leg, and what happens to the funds depends on which leg failed:

FIAT_FAILED: Deposit was rejected during review, before any crypto was delivered.
CRYPTO_FAILED: Fiat was accepted but the crypto delivery leg failed. Fiat stays held rather than being returned automatically, and can be returned to the sender’s bank account, moving the onramp to FIAT_RETURNED. Unlike an offramp return, FIAT_RETURNED is terminal.

Returns are available on USD onramps, regardless of which rail funded the deposit. To test them in sandbox, see Onramp magic values.

Tracking Onramps

Status Updates: Subscribe to ONRAMP webhook events to receive real-time status notifications. See Webhooks for setup instructions.

Monitor onramp status using the Retrieve Onramp endpoint. The response structure matches the create endpoint shown above. Request:

curl -X GET "https://sandbox.hifibridge.com/v2/onramps/onr_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Use the transactionHash in the response to view the stablecoin delivery on a blockchain explorer.

Quote Validity

Quote expiration times vary by currency. This ensures:

Current market rates
Prevention of stale pricing
Timely transaction processing

If your quote expires (status becomes QUOTE_FAILED):

Create a new onramp request
Get updated pricing
Complete the deposit with the new reference ID

Quote Expiration: The expiresAt timestamp in quoteInformation shows exactly when the quote expires for your specific currency. Always check this timestamp and plan to send your deposit with enough time for bank processing before this deadline.

Key Concepts

Virtual Account vs Onramp API

Both methods use virtual accounts, but with different characteristics:Virtual Accounts (reusable):

Permanent bank account number
Can be used for multiple deposits
USD currency only
Created via Virtual Accounts API

Onramp API (one-time):

One-time virtual account per transaction
Generated per transaction via Onramps API
Currently supports USD and Africa currencies (Africa Rail beta)
Bank details valid only for that transaction

Reference ID Requirements

The Onramp API works like one-time virtual accounts. The reference ID functions similarly to how deposits are matched to virtual accounts: - Each onramp generates a unique reference ID - Include it in your bank transfer memo/reference field - HIFI uses it to match your deposit to the correct transaction - Missing reference IDs cause delays or lost funds Where to include it: Most banks have a “memo,” “reference,” or “description” field for transfers. Put the reference ID there.

Exact Amount Matching

The deposit amount must match exactly: - Send the exact amount shown in depositInfo.amount - Include all decimal places (e.g.,

100.00, not

100) - Don’t round or adjust for fees - Mismatched amounts may be rejected or require manual intervention

USDT Fee

USDT onramps incur an additional 0.1% exchange fee beyond standard rates. This fee appears on your monthly invoice, not deducted from the transaction amount.

External Wallets

By default, stablecoins go to the user’s HIFI wallet. To send to an external wallet instead, include externalWalletId in the destination.

Getting Help

📧 Email: support@hifi.com
💬 Slack: Message us in our shared Slack channel

Quickstart Guide - Complete onramp tutorial
Virtual Accounts - Automatic onramp solution (recommended)
Onramp Accounts - One-time generated accounts per transaction; registered accounts for Africa (Africa Rail beta)
Users - KYC requirements for onramping
Webhooks - Real-time onramp status notifications
API Reference - Complete endpoint documentation

Introduction

Core concepts

Features

Compliance

Payments

References

Onramps

Onramp Methods

Using the Onramp API

Request Quote

Send Payment

Processing

Transaction Status

System Statuses

Fiat Processing Phase

Crypto Processing Phase

Failed Deposits and Returns

Tracking Onramps

Quote Validity

Key Concepts

Getting Help

​Onramp Methods

​Using the Onramp API

​Request Quote

​Send Payment

​Processing

​Transaction Status

​System Statuses

​Fiat Processing Phase

​Crypto Processing Phase

​Failed Deposits and Returns

​Tracking Onramps

​Quote Validity

​Key Concepts

​Getting Help

​Related Resources

Onramp Methods

Using the Onramp API

Request Quote

Send Payment

Processing

Transaction Status

System Statuses

Fiat Processing Phase

Crypto Processing Phase

Failed Deposits and Returns

Tracking Onramps

Quote Validity

Key Concepts

Getting Help

Related Resources