> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hifi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Onramps

> Onramps convert fiat currency into stablecoins and deliver them to wallets. Users can onramp through virtual accounts (reusable) or the Onramp API (one-time virtual accounts).

## 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) |

<Info>
  **Virtual Accounts for USD:** For recurring USD deposits, use reusable [Virtual Accounts](/docs/accounts/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).
</Info>

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](/docs/accounts/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](https://docs.hifi.com/api-reference/onramp/create-an-onramp) endpoint.

**Request:**

```bash theme={null}
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:

<Accordion title="Response">
  ```json theme={null}
  {
    "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
      }
    }
  }
  ```
</Accordion>

<ResponseField name="transferDetails.id" type="string">
  Unique onramp ID. **Save this** for tracking the transaction status.
</ResponseField>

<ResponseField name="transferDetails.status" type="string">
  Current status. `AWAITING_FUNDS` means the quote is ready and waiting for your deposit.
</ResponseField>

<ResponseField name="transferDetails.quoteInformation" type="object">
  Conversion details including rates and amounts.

  <Expandable title="properties">
    <ResponseField name="sendGross" type="object">
      Total fiat amount to send
    </ResponseField>

    <ResponseField name="receiveNet" type="object">
      Stablecoin amount you'll receive
    </ResponseField>

    <ResponseField name="rate" type="string">
      Exchange rate between fiat and stablecoin
    </ResponseField>

    <ResponseField name="expiresAt" type="string">
      Quote expiration timestamp. Deposit must arrive before this time.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="transferDetails.depositInfo" type="object">
  **Most Important:** Bank account details for sending your fiat deposit.

  <Expandable title="properties">
    <ResponseField name="referenceId" type="string">
      **Critical:** Include this reference ID with your bank transfer. Without it, your deposit cannot be matched to this onramp.
    </ResponseField>

    <ResponseField name="accountNumber" type="string">
      Bank account number for deposit
    </ResponseField>

    <ResponseField name="routingNumber" type="string">
      Bank routing number
    </ResponseField>

    <ResponseField name="amount" type="string">
      Exact amount to deposit (must match exactly)
    </ResponseField>

    <ResponseField name="instruction" type="string">
      Deposit instructions and requirements
    </ResponseField>
  </Expandable>
</ResponseField>

### 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`

<Warning>
  **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.
</Warning>

### Processing

Once HIFI detects your deposit:

1. **Fiat validation** - Confirms amount and reference ID match
2. **Conversion** - Exchanges fiat for stablecoins at the quoted rate
3. **Delivery** - Sends stablecoins to the destination wallet
4. **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 |

## Tracking Onramps

<Note>
  **Status Updates:** Subscribe to `ONRAMP` webhook events to receive real-time status notifications. See [Webhooks](/webhooks/onramp-events) for setup instructions.
</Note>

Monitor onramp status using the [Retrieve Onramp](https://docs.hifi.com/api-reference/onramp/retrieve-an-onramp) endpoint. The response structure matches the create endpoint shown above.

**Request:**

```bash theme={null}
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`):

1. Create a new onramp request
2. Get updated pricing
3. Complete the deposit with the new reference ID

<Info>
  **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.
</Info>

## Key Concepts

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  {" "}

  <Accordion title="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.
  </Accordion>

  {" "}

  <Accordion title="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
  </Accordion>

  {" "}

  <Accordion title="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.
  </Accordion>

  <Accordion title="External Wallets">
    By default, stablecoins go to the user's HIFI wallet. To send to an external wallet instead, include `externalWalletId` in the destination.
  </Accordion>
</AccordionGroup>

## Getting Help

* 📧 **Email:** [support@hifi.com](mailto:support@hifi.com)
* 💬 **Slack:** Message us in our shared Slack channel

## Related Resources

* [Quickstart Guide](/docs/quickstart) - Complete onramp tutorial
* [Virtual Accounts](/docs/accounts/virtual-accounts) - Automatic onramp solution (recommended)
* [Onramp Accounts](/docs/accounts/onramp-accounts) - One-time generated accounts per transaction; registered accounts for Africa (Africa Rail beta)
* [Users](/docs/users) - KYC requirements for onramping
* [Webhooks](/docs/webhooks) - Real-time onramp status notifications
* [API Reference](https://docs.hifi.com/api-reference/onramp/create-an-onramp) - Complete endpoint documentation