HIFI Docs

How Offramps Work

Offramps follow a quote-based flow:

Create offramp request

Specify the source wallet, destination account, and amount to convert.

Review quote

Examine the exchange rate, fees, and quote expiration time.

Accept quote

Accept the quote to execute the conversion. Stablecoins are converted to fiat and sent to the registered bank account.

Creating Offramps

Use the Create Offramp endpoint to get a quote. Request:

curl -X POST "https://sandbox.hifibridge.com/v2/offramps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "201ca31d-700f-4c76-ac4b-961623acbb79",
    "source": {
      "currency": "usdc",
      "chain": "POLYGON",
      "userId": "7d54a7a7-dac3-4313-8b09-27fa4b7fd1ee",
      "amount": 10
    },
    "destination": {
      "currency": "usd",
      "accountId": "12c1c496-8f57-41a1-8292-dbe6547791ce",
      "userId": "7d54a7a7-dac3-4313-8b09-27fa4b7fd1ee",
      "sameDayAch": false
    },
    "developerFee": {
      "fees": [
        {
          "type": "PERCENTAGE",
          "value": "0.0005",
          "walletAddress": "0x366B759bAA089Fa57a08edd3F2E028E86b97f8D7"
        }
      ]
    }
  }'

The response contains the offramp quote information:

Response

{
  "transferType": "OFFRAMP",
  "transferDetails": {
    "id": "173c1e89-7bbd-4352-9e5d-73807681510d",
    "requestId": "201ca31d-700f-4c76-ac4b-961623acbb79",
    "createdAt": "2025-02-03T16:12:04.331652+00:00",
    "updatedAt": "2025-02-03T16:12:08.732+00:00",
    "status": "OPEN_QUOTE",
    "failedReason": null,
    "source": {
      "userId": "7d54a7a7-dac3-4313-8b09-27fa4b7fd1ee",
      "chain": "POLYGON",
      "currency": "usdc",
      "amount": 10,
      "walletAddress": "0x366B759bAA089Fa57a08edd3F2E028E86b97f8D6",
      "user": {
        "email": "john.doe@hifibridge.com",
        "firstName": "John",
        "lastName": "Doe",
        "businessName": null
      }
    },
    "destination": {
      "userId": "7d54a7a7-dac3-4313-8b09-27fa4b7fd1ee",
      "amount": 0,
      "currency": "usd",
      "user": {
        "email": "john.doe@hifibridge.com",
        "firstName": "John",
        "lastName": "Doe",
        "businessName": null
      },
      "accountId": "12c1c496-8f57-41a1-8292-dbe6547791ce",
      "sameDayAch": false
    },
    "receipt": {
      "transactionHash": null,
      "paymentTracking": null
    },
    "developerFee": {
      "id": "1c3d24c1-6136-574c-a647-e7eb6a9fb6ed",
      "transactionHash": null,
      "fees": [
        {
          "type": "PERCENTAGE",
          "value": "0.0005",
          "amount": "0.000515",
          "walletAddress": "0x366B759bAA089Fa57a08edd3F2E028E86b97f8D7"
        },
        {
          "type": "FLAT",
          "value": "0.01",
          "amount": "0.010000",
          "walletAddress": "0x366B759bAA089Fa57a08edd3F2E028E86b97f8D7"
        }
      ]
    },
    "quoteInformation": {
      "sendGross": {
        "amount": "10",
        "currency": "usdc"
      },
      "sendNet": {
        "amount": "10",
        "currency": "usdc"
      },
      "receiveGross": {
        "amount": "10",
        "currency": "usd"
      },
      "receiveNet": {
        "amount": "10",
        "currency": "usd"
      },
      "rate": "1",
      "expiresAt": "2025-02-03T16:22:08.668Z"
    },
    "depositInformation": []
  }
}

string

Unique offramp ID. Use this to track the transaction and accept the quote.

string

Offramp status. OPEN_QUOTE means the quote is ready for review. See Transaction Status for details.

object

Conversion quote details including exchange rate, amounts, and expiration time.

Show properties

object

Total stablecoins being converted.

object

Net stablecoin amount after fees.

object

Total fiat amount before fees.

object

Actual fiat amount you’ll receive. Verify this matches your expectations before accepting.

string

Exchange rate (stablecoin to fiat).

string

Quote expiration timestamp. Quotes expire 10 minutes after creation.

object

Developer fee details if included in the request.

object

Source wallet details including user information and stablecoin amount.

object

Destination bank account details including account ID and user information.

object

Transaction receipt. Contains transactionHash once the stablecoin conversion is confirmed on-chain, and paymentTracking once fiat processing begins.

For detailed field documentation, see the Create Offramp API reference.

Accepting Quotes

After reviewing the quote, accept it to execute the conversion using the Accept Quote endpoint. Request:

curl -X POST "https://sandbox.hifibridge.com/v2/offramps/173c1e89-7bbd-4352-9e5d-73807681510d/quote/accept" \
  -H "Authorization: Bearer YOUR_API_KEY"

When the quote is accepted, the response shows the updated status:

Response

{
  "transferType": "OFFRAMP",
  "transferDetails": {
    "id": "off_abc123",
    "status": "CRYPTO_INITIATED",
    "quoteInformation": {
      "expiresAt": "2025-02-03T16:22:08.668Z"
    }
  }
}

string

Updated offramp status. CRYPTO_INITIATED means the conversion has started. See Transaction Status for progression.

Once accepted, the offramp progresses through crypto and fiat processing phases until completion.

Transaction Status

Offramps progress through several phases:

System Statuses

Status	Description
CREATED	Offramp request created successfully
NOT_INITIATED	Request not submitted due to validation error
OPEN_QUOTE	Quote generated and awaiting acceptance
IN_REVIEW	Transaction under review by monitoring systems
QUOTE_FAILED	Quote expired before acceptance
AWAITING_FUNDS	Awaiting for crypto deposit

Crypto Processing Phase

Status	Description
CRYPTO_INITIATED	Converting stablecoins, blockchain transaction started
CRYPTO_PENDING	Blockchain transaction awaiting confirmation
CRYPTO_PROCESSED	Stablecoins successfully converted
CRYPTO_FAILED	Blockchain transaction failed
CRYPTO_RETURNED	Crypto returned on chain to the sender’s wallet

Fiat Processing Phase

Status	Description
FIAT_INITIATED	Fiat payout process started
FIAT_PENDING	Fiat transaction awaiting settlement
FIAT_FAILED	Fiat transaction failed
FIAT_RETURNED	Fiat leg reversed, crypto return not yet delivered
COMPLETED	Fiat successfully delivered to bank account

Failed Payouts and Returns

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

CRYPTO_FAILED: Transfer was rejected before the fiat leg started. When the offramp is funded from a HIFI wallet, nothing left the wallet. When it is funded from an external wallet, crypto is returned to the sender and offramp continues on to CRYPTO_RETURNED.
FIAT_FAILED: Fiat payout failed after the crypto had already left the source wallet. Crypto is returned to the sender, and the offramp progresses to CRYPTO_RETURNED once that on-chain delivery confirms. Depending on the rail, it may report an intermediate FIAT_RETURNED first.

Returns are available on USD offramps and global network offramps. To test them in sandbox, see Offramp magic values.

Tracking Offramps

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

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

curl -X GET "https://sandbox.hifibridge.com/v2/offramps/173c1e89-7bbd-4352-9e5d-73807681510d" \
  -H "Authorization: Bearer YOUR_API_KEY"

Quote Validity

Quotes expire 10 minutes after creation to ensure current market rates. This prevents:

Stale pricing during volatile markets
Long-pending transactions
Rate arbitrage

If your quote expires (status becomes QUOTE_FAILED):

Create a new offramp request
Review the updated quote
Accept the new quote within 10 minutes

Time Sensitive: Always check quoteInformation.expiresAt before accepting. Attempting to accept an expired quote will fail.

Purpose of Payment Code

Payment Purpose Codes (PPCs), also known as payment reason codes, are standardized identifiers that provide the reason for a crossborder or international payment. PPCs enable payers to categorize the payment, whether for goods, services, investments, or other purposes. In crossborder payments, PPCs add an additional layer of transparency by ensuring funds are used for legitimate purposes and are considered mandatory or required fields by the Central Banking authority in certain jurisdictions, i.e. India, Malaysia, and the United Arab Emirates.

United Arab Emirates (ARE)

Code	Description
ACM	Agency Commission
AES	Advance payment against EOS
AFA	Receipts or payments from personal residents bank account or deposits abroad
AFL	Receipts or payments from personal non-resident bank account in the UAE
ALW	Allowances
ATS	Air transport
BON	Bonus
CCP	Corporate Card Payment
CEA	Equity and investment fund shares for the establishment of new company from residents abroad, equity of merger or acquisition of companies abroad from residents and participation to capital increase of related companies abroad
CEL	Equity and investment fund shares for the establishment of new company in the UAE from non-residents, equity of merger or acquisition of companies in the UAE from non-residents and participation to capital increase of related companies from non-residents in the UAE
CHC	Charitable Contributions
CIN	Commercial Investments
COM	Commission
COP	Compensation
CRP	Credit Card Payments
DCP	Pre-Paid Reloadable & Personalized Debit Card Payments
DIV	Dividend Payouts
DLA	Purchases and sales of foreign debt securities in not related companies – More than a year
DLF	Debt instruments intragroup loans, deposits foreign
DLL	Purchases and sales of securities issued by residents in not related companies – More than a year
DOE	Dividends on equity not intra group
DSA	Purchases and sales of foreign debt securities in not related companies – Less than a year
DSF	Debt instruments intragroup foreign securities
DSL	Purchases and sales of securities issued by residents in not related companies – Less than a year
EDU	Educational Support
EMI	Equated Monthly Instalments
EOS	End of Service
FAM	Family Support
FDA	Financial derivatives foreign
FDL	Financial derivatives in the UAE
FIA	Investment fund shares foreign
FIL	Investment fund shares in the UAE
FIS	Financial services
FSA	Equity other than investment fund shares in not related companies abroad
FSL	Equity other than investment fund shares in not related companies in the UAE
GDE	Goods Sold
GDI	Goods bought
GMS	Processing repair and maintenance services on goods
GOS	Government goods and services embassies etc
GRI	Government related income taxes tariffs capital transfers etc
IFS	Information services
IGD	Intra group dividends
IGT	Inter group transfer
IID	Intra group interest on debt
INS	Insurance services
IOD	Income on deposits
IOL	Income on loans
IPC	Charges for the use of intellectual property royalties
IPO	IPO subscriptions
IRP	Interest rate swap payments
IRW	Interest rate unwind payments
ISH	Income on investment funds share
ISL	Interest on securities more than a year
ISS	Interest on securities less than a year
ITS	Computer services
LAS	Leave salary
LDL	Debt instruments intragroup loans, deposits in the UAE
LDS	Debt instruments intragroup securities in the UAE
LEA	Leasing abroad
LEL	Leasing in the UAE
LIP	Loan interest payments
LLA	Loans – Drawings or Repayments on loans extended to nonresidents – Long-term
LLL	Loans – Drawings or Repayments on foreign loans extended to residents – Long-term
LNC	Loan charges
LND	Loan disbursements
MCR	Monetary Claim Reimbursements Medical Insurance or Auto Insurance etc.
MWI	Mobile wallet cash in
MWO	Mobile wallet cash out
MWP	Mobile wallet payments
OAT	Own account transfer
OTS	Other modes of transport
OVT	Overtime
PEN	Pension
PIN	Personal Investments
PIP	Profits on Islamic products
PMS	Professional and management consulting services
POR	Refunds or Reversals on IPO subscriptions
POS	POS Merchant Settlement
PPA	Purchase of real estate abroad from residents
PPL	Purchase of real estate in the UAE from non-residents
PRP	Profit rate swap payments
PRR	Profits or rents on real estate
PRS	Personal cultural audio visual and recreational services
PRW	Profit rate unwind payments
RDS	Research and development services
RFS	Repos on foreign securities
RLS	Repos on securities issued by residents
RNT	Rent payments
SAA	Salary advance
SAL	Salary
SCO	Construction
SLA	Loans – Drawings or Repayments on loans extended to nonresidents – Short-term
SLL	Loans – Drawings or Repayments on foreign loans extended to residents – Short-term
STR	Travel
STS	Sea transport
SVI	Stored value card cash-in
SVO	Stored value card cash-out
SVP	Stored value card payments
TCP	Trade credits and advances payable
TCR	Trade credits and advances receivable
TCS	Telecommunication services
TKT	Tickets
TOF	Transfer of funds between persons Normal and Juridical
TTS	Technical trade-related and other business services
UTL	Utility Bill Payments

Key Concepts

Quote Information

The quote provides complete pricing transparency:

sendGross: Total stablecoins being converted
sendNet: Net amount after fees
receiveGross: Total fiat before fees
receiveNet: Actual fiat you’ll receive
rate: Exchange rate (stablecoin to fiat)
expiresAt: Quote expiration timestamp

Always verify receiveNet matches your expectations before accepting.

Developer Fees

Monetize offramp transactions by adding a developer fee when creating the offramp:FIX: Fixed amount regardless of transaction size

{
  "fee": {
    "type": "FIX",
    "value": 0.5
  }
}

PERCENT: Percentage of transaction amount

{
  "fee": {
    "type": "PERCENT",
    "value": 0.01
  }
}

Developer fees are paid in stablecoins from the source wallet before conversion.

USDT Fee

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

Account Requirements

Before creating offramps, ensure:

User has completed KYC for the destination currency’s rail
Offramp account is created and active (status: ACTIVE)
Sufficient stablecoin balance in the source wallet

Getting Help

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

Quickstart Guide - Complete offramp tutorial
Offramp Accounts - Set up bank accounts for receiving fiat
Users - KYC requirements for offramping
Webhooks - Real-time offramp status notifications
API Reference - Complete endpoint documentation

Introduction

Core concepts

Features

Compliance

Payments

References

Offramps

How Offramps Work

Creating Offramps

Accepting Quotes

Transaction Status

System Statuses

Crypto Processing Phase

Fiat Processing Phase

Failed Payouts and Returns

Tracking Offramps

Quote Validity

Purpose of Payment Code

United Arab Emirates (ARE)

Key Concepts

Getting Help

​How Offramps Work

​Creating Offramps

​Accepting Quotes

​Transaction Status

​System Statuses

​Crypto Processing Phase

​Fiat Processing Phase

​Failed Payouts and Returns

​Tracking Offramps

​Quote Validity

​Purpose of Payment Code

​United Arab Emirates (ARE)

​Key Concepts

​Getting Help

​Related Resources

How Offramps Work

Creating Offramps

Accepting Quotes

Transaction Status

System Statuses

Crypto Processing Phase

Fiat Processing Phase

Failed Payouts and Returns

Tracking Offramps

Quote Validity

Purpose of Payment Code

United Arab Emirates (ARE)

Key Concepts

Getting Help

Related Resources