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

Header	Value
x-api-key	Your API key

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
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
note	string	No	Transaction note

* Provide either fiatAmount or cryptoAmount, not both.

Example request

Bank (NGN)

curl -X POST https://ramp-api.ivorypay.io/api/v1/offramp \
  -H "x-api-key: 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

{
  "statusCode": 200,
  "success": true,
  "message": "Off-ramp initiated successfully",
  "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