Settlements

Use this endpoint to retrieve the history of settlements processed for your business. Both fiat (bank transfer) and crypto (on-chain withdrawal) settlements are returned in a single unified list, sorted by most recent first.

Base path: /v1/business/settlements Authentication: Secret key (Authorization: sk_...)

---

Endpoints

Method	Path	Auth	Description
GET	/v1/business/settlements	API Key	List all settlements (paginated)

---

GET /v1/business/settlements

Returns a paginated, date-filtered list of all fiat and crypto settlements for the authenticated business and environment.

Query Parameters

Parameter	Type	Required	Description
type	string	No	Filter by settlement type — FIAT or CRYPTO. Returns both if omitted.
from	string	No	Start of date range (ISO 8601). e.g. 2026-01-01T00:00:00.000Z
to	string	No	End of date range (ISO 8601). e.g. 2026-01-31T23:59:59.999Z
page	number	No	Page number. Defaults to 1.
limit	number	No	Results per page. Defaults to 10, max 100.

Request

GET /v1/business/settlements?type=FIAT&from=2026-01-01T00:00:00.000Z&to=2026-01-31T23:59:59.999Z&page=1&limit=20
Authorization: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Response

{
  "success": true,
  "message": "Settlements retrieved successfully",
  "data": {
    "records": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "reference": "settlement-ref-001",
        "type": "FIAT",
        "status": "SUCCESS",
        "amount": 50000,
        "settledAmount": 49500,
        "fee": 500,
        "currency": "NGN",
        "chain": null,
        "withdrawalTxHash": null,
        "environment": "LIVE",
        "paymentMethod": {
          "type": "FIAT",
          "payoutMethod": "BANK_TRANSFER",
          "accountNumber": "0123456789",
          "accountName": "Acme Store Ltd",
          "bankName": "GTBank"
        },
        "createdAt": "2026-01-15T10:00:00.000Z",
        "updatedAt": "2026-01-15T10:05:00.000Z"
      },
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "reference": "settlement-ref-002",
        "type": "CRYPTO",
        "status": "SUCCESS",
        "amount": 25.0,
        "settledAmount": 24.5,
        "fee": 0.5,
        "currency": "USDT",
        "chain": "BSC_MAINNET",
        "withdrawalTxHash": "0xabc123def456...",
        "environment": "LIVE",
        "paymentMethod": {
          "type": "CRYPTO",
          "payoutMethod": "CRYPTO_PAYMENT",
          "address": "0x5020D82d223ffC7Ae770af32eD91d7Af9Fd1adEd",
          "network": "BSC_MAINNET"
        },
        "createdAt": "2026-01-14T08:30:00.000Z",
        "updatedAt": "2026-01-14T08:35:00.000Z"
      }
    ],
    "count": 38
  }
}

Response Fields

Field	Type	Description
records	array	Array of settlement records sorted by most recent first
count	number	Total number of records matching the query (across all pages)
records[].id	string	Settlement UUID
records[].reference	string	Settlement reference
records[].type	string	FIAT or CRYPTO
records[].status	string	Settlement status. See status values
records[].amount	number	Original settlement amount before fees
records[].settledAmount	number	Amount actually settled after fees, or null if not yet settled
records[].fee	number	Fee deducted from the settlement amount
records[].currency	string	Fiat currency (e.g. NGN) for FIAT settlements, crypto token (e.g. USDT) for CRYPTO
records[].chain	string	Blockchain network for CRYPTO settlements (e.g. BSC_MAINNET), null for FIAT
records[].withdrawalTxHash	string	On-chain transaction hash for CRYPTO settlements, null for FIAT or if pending
records[].environment	string	LIVE or TEST
records[].paymentMethod	object	Destination account or wallet used for this settlement
records[].createdAt	string	ISO 8601 timestamp when the settlement was initiated
records[].updatedAt	string	ISO 8601 timestamp of the last status update

Payment Method Fields

FIAT settlement:

Field	Type	Description
paymentMethod.type	string	"FIAT"
paymentMethod.payoutMethod	string	e.g. BANK_TRANSFER
paymentMethod.accountNumber	string	Destination bank account number
paymentMethod.accountName	string	Account holder name
paymentMethod.bankName	string	Name of the destination bank

CRYPTO settlement:

Field	Type	Description
paymentMethod.type	string	"CRYPTO"
paymentMethod.payoutMethod	string	e.g. CRYPTO_PAYMENT
paymentMethod.address	string	Destination wallet address
paymentMethod.network	string	Blockchain network (e.g. BSC_MAINNET)

---

Settlement Status Values

Status	Description
PENDING	Settlement initiated, awaiting processing
PROCESSING	Settlement is being processed
SUCCESS	Settlement completed and funds dispatched
FAILED	Settlement failed

---

Error Responses

Status	Message	Cause
401	Unauthorized	Missing or invalid API key

---

Code Examples

Node.js

const axios = require('axios');

const { data } = await axios.get(
  'https://api.ivorypay.io/api/v1/business/settlements',
  {
    params: {
      from: '2026-01-01T00:00:00.000Z',
      to: '2026-01-31T23:59:59.999Z',
      page: 1,
      limit: 20,
    },
    headers: { Authorization: process.env.IVORYPAY_SECRET_KEY },
  },
);

const { records, count } = data.data;
console.log(`Showing ${records.length} of ${count} settlements`);

records.forEach((s) => {
  if (s.type === 'FIAT') {
    console.log(`FIAT — ${s.amount} ${s.currency} → ${s.paymentMethod?.bankName} ${s.paymentMethod?.accountNumber} [${s.status}]`);
  } else {
    console.log(`CRYPTO — ${s.amount} ${s.currency} → ${s.paymentMethod?.address} [${s.status}]`);
  }
});

cURL

curl "https://api.ivorypay.io/api/v1/business/settlements?from=2026-01-01T00:00:00.000Z&to=2026-01-31T23:59:59.999Z&page=1&limit=20" \
  -H "Authorization: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

---

Notes

• Results are scoped to the authenticated business and environment — use your live key for live settlements and your test key for test data.

• count reflects the total matching records, not just the current page.

• Both FIAT and CRYPTO settlements appear in the same list, ordered by createdAt descending.

• settledAmount may differ from amount due to the processing fee (fee).