Initiate Off-Ramp

Initiate an off-ramp transaction for an existing customer.

Initiates a crypto-to-fiat off-ramp transaction for a customer that already exists in your IvoryPay account.

Endpoint

POST /v1/offramp/initiate

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
email	string	Yes	Existing 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
blockchain	string	Yes	Blockchain network
reference	string	Yes	Your unique reference (must be a UUID)
token	string	Yes	Cryptocurrency the user will send
fiatCurrency	string	Yes	Fiat currency for payout
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. The reference must be a valid UUID on this endpoint.

Example request

Bank (NGN)

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

Mobile Money (UGX)

curl -X POST https://ramp-api.ivorypay.io/api/v1/offramp/initiate \
  -H "Authorization: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "phoneNumber": "[phone]",
    "accountNumber": "256772882926",
    "blockchain": "STARKNET_MAINNET",
    "reference": "660e8410-f23c-41c4-a628-838625530891",
    "token": "USDT",
    "fiatCurrency": "UGX",
    "cryptoAmount": 1.5,
    "businessFeeInCrypto": 0.001
  }'

Node.js

const response = await fetch("https://ramp-api.ivorypay.io/api/v1/offramp/initiate", {
  method: "POST",
  headers: {
    "Authorization": "your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "[e-mail]",
    accountNumber: "0123456789",
    bankCode: "058",
    blockchain: "BSC_MAINNET",
    reference: "660e8400-e29b-41d4-a716-446655440001",
    token: "USDT",
    fiatCurrency: "NGN",
    fiatAmount: 100000,
  }),
});

const data = await response.json();
console.log(data);

Python

import requests

response = requests.post(
    "https://ramp-api.ivorypay.io/api/v1/offramp/initiate",
    headers={
        "Authorization": "your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "email": "[e-mail]",
        "accountNumber": "0123456789",
        "bankCode": "058",
        "blockchain": "BSC_MAINNET",
        "reference": "660e8400-e29b-41d4-a716-446655440001",
        "token": "USDT",
        "fiatCurrency": "NGN",
        "fiatAmount": 100000,
    },
)

print(response.json())

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	body, _ := json.Marshal(map[string]interface{}{
		"email":         "[e-mail]",
		"accountNumber": "0123456789",
		"bankCode":      "058",
		"blockchain":    "BSC_MAINNET",
		"reference":     "660e8400-e29b-41d4-a716-446655440001",
		"token":         "USDT",
		"fiatCurrency":  "NGN",
		"fiatAmount":    100000,
	})

	req, _ := http.NewRequest("POST", "https://ramp-api.ivorypay.io/api/v1/offramp/initiate", bytes.NewBuffer(body))
	req.Header.Set("Authorization", "your_api_key")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	respBody, _ := io.ReadAll(resp.Body)
	fmt.Println(string(respBody))
}

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_xyz789",
      "duration": 3600
    }
  }
}

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 — "You do not have access to this token, please contact support"

Contact support to request that specific tokens and networks be enabled for your sandbox key. See Supported Networks & Tokens for the full list of available sandbox combinations.

Error cases

Error code	Description
ONOFFRAMP0053	Customer not found — use the with-customer endpoint
ONOFFRAMP0033	Invalid bank code
ONOFFRAMP0024	Token not enabled for your account — contact support to enable the token/blockchain pair