Fiat Transfer

Send fiat currency from your IvoryPay crypto wallet balance to a recipient's bank account. IvoryPay converts your specified crypto token to the target fiat currency and delivers funds via local bank transfer.

Base path: /v1/fiat-transfer Authentication: API Key (Authorization: <secret-key>)

---

Endpoints

Method	Path	Description
POST	/v1/fiat-transfer	Initiate a fiat bank transfer
GET	/v1/fiat-transfer/banks	List available banks
POST	/v1/fiat-transfer/account-resolution	Verify a bank account name

---

POST /v1/fiat-transfer

Initiates a fiat payout. Funds are deducted from your crypto wallet, converted, and sent to the recipient's bank account.

Request

Headers

Authorization: <your-secret-api-key>
Content-Type: application/json

Body

{
  "amount": 50000,
  "token": "USDT",
  "fiatCurrency": "NGN",
  "payoutMethod": "BANK_TRANSFER",
  "accountNumber": "0123456789",
  "bankCode": "044",
  "reference": "payout-ref-001"
}

Field	Type	Required	Description
amount	number	Yes	Amount in the specified fiatCurrency. Must be a positive number.
token	string	Yes	Crypto token to debit from your wallet (e.g. USDT, USDC).
fiatCurrency	string	Yes	Target fiat currency for the recipient. See supported values.
payoutMethod	string	Yes	Payment rail. See payout methods.
accountNumber	string	Yes	Recipient's bank account number.
bankCode	string	Yes	Bank identifier code. Use GET /v1/fiat-transfer/banks to get valid codes.
reference	string	Yes	Your unique reference for this transfer. Used for idempotency.

Response

{
  "status": true,
  "message": "Fiat payout initiated successfully",
  "data": {
    "id": "uuid",
    "reference": "payout-ref-001",
    "amount": 50000,
    "token": "USDT",
    "fiatCurrency": "NGN",
    "accountNumber": "0123456789",
    "bankCode": "044",
    "status": "PENDING",
    "businessId": "uuid",
    "createdAt": "2026-02-19T10:00:00.000Z"
  }
}

Error Responses

Status	Message	Cause
400	Insufficient balance	Not enough crypto in your wallet
400	Invalid account number	Account number format invalid
400	bankCode must be longer than 3 characters	Bank code too short
401	Unauthorized	Missing or invalid API key

---

GET /v1/fiat-transfer/banks

Returns a list of banks available for payout in your current environment. The list is filtered by your account's active fiat currencies.

Request

Headers

Authorization: <your-secret-api-key>

Response

{
  "status": true,
  "message": "Query successful",
  "data": [
    {
      "id": "uuid",
      "name": "Access Bank",
      "code": "044",
      "country": "NG",
      "currency": "NGN"
    },
    {
      "id": "uuid",
      "name": "Equity Bank Kenya",
      "code": "68",
      "country": "KE",
      "currency": "KES"
    }
  ]
}

---

POST /v1/fiat-transfer/account-resolution

Verifies a bank account and returns the registered account name before initiating a transfer. Always resolve the account before sending to prevent misdirected transfers.

Request

Headers

Authorization: <your-secret-api-key>
Content-Type: application/json

Body

{
  "accountNumber": "0123456789",
  "bankCode": "044",
  "currency": "NGN"
}

Field	Type	Required	Description
accountNumber	string	Yes	Bank account number. Must be numeric.
bankCode	string	Yes	Bank identifier code. Minimum 3 characters.
currency	string	Yes	Fiat currency of the account. See supported values.

Response

{
  "status": true,
  "message": "Query successful",
  "data": {
    "accountName": "John Doe",
    "accountNumber": "0123456789",
    "bankCode": "044"
  }
}

Error Responses

Status	Message	Cause
400	Invalid account number	Non-numeric account number
400	Account not found	Account does not exist at the bank
401	Unauthorized	Missing or invalid API key

---

Supported Values

fiatCurrency / currency

Value	Currency
NGN	Nigerian Naira
KES	Kenyan Shilling
GHS	Ghanaian Cedi
ZAR	South African Rand
USD	US Dollar

token

Value	Name
USDT	Tether USD
USDC	USD Coin

Payout Methods

Value	Description
BANK_TRANSFER	Direct bank transfer
MOBILE_MONEY	Mobile money wallet

---

Transfer Lifecycle

PENDING → PROCESSING → SUCCESS
                    ↘ FAILED

Status	Description
PENDING	Transfer queued, conversion in progress
PROCESSING	Sent to payment rail, awaiting bank confirmation
SUCCESS	Bank confirmed receipt, crypto wallet debited
FAILED	Transfer failed — no funds deducted

Subscribe to webhook events to receive real-time status updates.

---

Best Practices

1. Always resolve the account first using POST /v1/fiat-transfer/account-resolution to confirm the account name before sending.

2. Use a unique reference per transfer. This prevents duplicate transfers if you retry a failed request.

3. Check your balance before initiating. Use the wallet balance endpoint to ensure sufficient funds.

---

Code Examples

Node.js

const axios = require('axios');

const BASE_URL = 'https://api.ivorypay.io/api/v1';

// Step 1: Resolve account
const resolution = await axios.post(
  `${BASE_URL}/fiat-transfer/account-resolution`,
  { accountNumber: '0123456789', bankCode: '044', currency: 'NGN' },
  { headers: { Authorization: process.env.IVORYPAY_SECRET_KEY } }
);

console.log('Account name:', resolution.data.data.accountName);

// Step 2: Initiate transfer
const payout = await axios.post(
  `${BASE_URL}/fiat-transfer`,
  {
    amount: 50000,
    token: 'USDT',
    fiatCurrency: 'NGN',
    payoutMethod: 'BANK_TRANSFER',
    accountNumber: '0123456789',
    bankCode: '044',
    reference: 'payout-' + Date.now(),
  },
  { headers: { Authorization: process.env.IVORYPAY_SECRET_KEY } }
);

console.log(payout.data);

cURL

BASE_URL="https://api.ivorypay.io/api/v1"

# Step 1: Resolve account
curl -X POST $BASE_URL/fiat-transfer/account-resolution \
  -H "Authorization: live_sk_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"accountNumber":"0123456789","bankCode":"044","currency":"NGN"}'

# Step 2: Initiate transfer
curl -X POST $BASE_URL/fiat-transfer \
  -H "Authorization: live_sk_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "token": "USDT",
    "fiatCurrency": "NGN",
    "payoutMethod": "BANK_TRANSFER",
    "accountNumber": "0123456789",
    "bankCode": "044",
    "reference": "payout-001"
  }'

Python

import requests

BASE_URL = 'https://api.ivorypay.io/api/v1'
HEADERS = {
    'Authorization': 'live_sk_xxxxxxxxxxxx',
    'Content-Type': 'application/json',
}

# Step 1: Resolve account
resolution = requests.post(
    f'{BASE_URL}/v1/fiat-transfer/account-resolution',
    json={'accountNumber': '0123456789', 'bankCode': '044', 'currency': 'NGN'},
    headers=HEADERS,
)
print('Account:', resolution.json()['data']['accountName'])

# Step 2: Initiate transfer
payout = requests.post(
    f'{BASE_URL}/v1/fiat-transfer',
    json={
        'amount': 50000,
        'token': 'USDT',
        'fiatCurrency': 'NGN',
        'payoutMethod': 'BANK_TRANSFER',
        'accountNumber': '0123456789',
        'bankCode': '044',
        'reference': 'payout-001',
    },
    headers=HEADERS,
)
print(payout.json())