Initiate Off-Ramp (with Customer)

Create a new customer and initiate a crypto-to-fiat off-ramp transaction.

Creates a new customer record (or retrieves an existing one by email) and initiates a crypto-to-fiat off-ramp transaction. The user will send crypto and receive fiat in their bank account or mobile money wallet.

Endpoint

POST /v1/offramp

Authentication

This endpoint accepts any one of three credentials in the Authorization header:

Credential	Header value
Merchant API key	Authorization: <api_key>
Business-user JWT	Authorization: Bearer <jwt>
Customer JWT	Authorization: Bearer <jwt>

Request body

Field	Type	Required	Description
firstName	string	Yes	Customer's first name (min 1 character)
lastName	string	Yes	Customer's last name (min 1 character)
email	string	Yes	Customer's email address
phoneNumber	string	No	Customer's phone number (E.164 format)
accountNumber	string	Yes	Recipient bank account number or mobile money number
bankCode	string	No	Bank code for NGN bank payouts (use List Banks to get valid codes). Not required for mobile money payouts
fiatCurrency	string	Yes	Fiat currency for payout. See Supported Currencies
blockchain	string	Yes	Blockchain network. See Supported Blockchains
reference	string	Yes	Your unique reference for this transaction. Validated as a string only (UUID not required on this variant)
token	string	Yes	Cryptocurrency the user will send. See Supported Networks & Tokens
fiatAmount	number	No*	Fiat amount to be paid out
cryptoAmount	number	No*	Crypto amount to be sent
businessFeeInCrypto	number	No	Your business fee in crypto. Pair with cryptoAmount
businessFeeInFiat	number	No	Your business fee in fiat. Pair with fiatAmount
note	string	No	Transaction note

* Provide either fiatAmount + businessFeeInFiat OR cryptoAmount + businessFeeInCrypto. Mixing a fiat amount with a crypto fee (or vice versa) is rejected by validation.

Example request

Bank (NGN)

curl -X POST https://ramp-api.ivorypay.io/api/v1/offramp \
  -H "Authorization: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Chidi",
    "lastName": "Nwankwo",
    "email": "[e-mail]",
    "phoneNumber": "[phone]",
    "accountNumber": "0123456789",
    "bankCode": "058",
    "blockchain": "BSC_MAINNET",
    "reference": "660e8400-e29b-41d4-a716-446655440001",
    "token": "USDT",
    "fiatCurrency": "NGN",
    "fiatAmount": 100000
  }'

Mobile Money (UGX)

Node.js

Python

Go

Example response

Returns HTTP 201 Created.

{
  "success": true,
  "message": "Query successful",
  "data": {
    "firstName": "Chidi",
    "lastName": "Nwankwo",
    "email": "[e-mail]",
    "refCode": "xyz789abc0",
    "reference": "660e8400-e29b-41d4-a716-446655440001",
    "transferDetails": {
      "token": "USDT",
      "blockchain": "BSC_MAINNET",
      "amountPayable": 62.5,
      "businessFee": 0,
      "platformFee": 0.3,
      "walletAddress": "0xIvoryPayDepositAddress...",
      "createdAt": "2026-03-26T12:00:00.000Z",
      "fiatAmount": 100000,
      "expiresAt": "2026-03-26T13:00:00.000Z",
      "sessionId": "session_abc123",
      "duration": 3600,
      "status": "INITIATED"
    }
  }
}

Response fields

Field	Type	Description
refCode	string	IvoryPay's unique customer reference
reference	string	Your transaction reference
transferDetails.token	string	Crypto token the user must send
transferDetails.blockchain	string	Blockchain network
transferDetails.amountPayable	number	Exact crypto amount the user must send
transferDetails.walletAddress	string	IvoryPay deposit address — user sends crypto here
transferDetails.fiatAmount	number	Fiat amount the user will receive
transferDetails.expiresAt	string	ISO 8601 session expiry time
transferDetails.sessionId	string	Session identifier (used for refresh)
transferDetails.duration	number	Session duration in seconds
transferDetails.businessFee	number	Your business fee
transferDetails.platformFee	number	IvoryPay platform fee

Related webhooks

• offramp.cryptoPaymentReceived — Crypto deposit detected on-chain

• offramp.success — Fiat payout sent to bank or mobile money wallet

• offramp.failed — Transaction failed

• offramp.declined — Transaction declined

Error cases

Error code	Description
ONOFFRAMP0033	Invalid bank code
ONOFFRAMP0024	Token not enabled for your account — contact support to enable the token/blockchain pair

Sandbox behaviour

Off-ramp token access is provisioned per API key. If your sandbox key has not been enabled for a specific token/blockchain combination, you will receive ONOFFRAMP0024. Contact support with the token and network you need enabled.