Collections

Use these endpoints to retrieve your business's incoming payment history. Only collection transactions (FIAT_COLLECTION and CRYPTO_COLLECTION) are returned — payouts, swaps, and settlements are excluded.

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

---

Endpoints

Method	Path	Auth	Description
GET	/v1/business/transactions	API Key	List all collection transactions (paginated)
GET	/v1/business/transactions/:reference	API Key	Get full details of a collection by reference

---

GET /v1/business/transactions

Returns a paginated list of all incoming payment transactions for the authenticated business and environment.

Query Parameters

Parameter	Type	Required	Description
page	number	No	Page number. Defaults to 1.
limit	number	No	Results per page. Defaults to 10, max 100.
status	string	No	Filter by transaction status. See status values.
reference	string	No	Filter by exact transaction reference.
customer	string	No	Filter by customer UUID.
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

Request

GET /v1/business/transactions?page=1&limit=20&status=SUCCESS
Authorization: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Response

{
  "success": true,
  "message": "Transactions retrieved successfully",
  "data": {
    "records": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "reference": "ecb1d467-eaa4-4640-ac61-1a777c86f67a",
        "status": "SUCCESS",
        "type": "FIAT",
        "source": "FIAT_COLLECTION",
        "origin": "API",
        "environment": "LIVE",
        "amount": 10000,
        "currency": "NGN",
        "collectionMethod": "BANK_TRANSFER",
        "customer": {
          "id": "cust-uuid-here",
          "email": "[e-mail]",
          "firstName": "John",
          "lastName": "Doe"
        },
        "createdAt": "2026-01-15T10:00:00.000Z",
        "completedAt": "2026-01-15T10:05:00.000Z"
      },
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "reference": "550e8400-e29b-41d4-a716-446655440000",
        "status": "SUCCESS",
        "type": "CRYPTO",
        "source": "CRYPTO_COLLECTION",
        "origin": "API",
        "environment": "LIVE",
        "amount": 10.5,
        "currency": "USDT",
        "collectionMethod": "CRYPTO_PAYMENT",
        "customer": {
          "id": "cust-uuid-here-2",
          "email": "[e-mail]",
          "firstName": "Jane",
          "lastName": "Smith"
        },
        "createdAt": "2026-01-15T09:00:00.000Z",
        "completedAt": "2026-01-15T09:08:00.000Z"
      }
    ],
    "count": 42
  }
}

Response Fields

Field	Type	Description
records	array	Array of collection transaction summaries
count	number	Total number of records matching the query (across all pages)
records[].id	string	Transaction UUID
records[].reference	string	Your supplied reference
records[].status	string	Transaction status. See status values
records[].type	string	FIAT or CRYPTO
records[].source	string	FIAT_COLLECTION or CRYPTO_COLLECTION
records[].origin	string	How the transaction was initiated (e.g. API, PAYMENT LINK)
records[].environment	string	LIVE or TEST
records[].amount	number	Collection amount in the transaction's currency
records[].currency	string	Fiat currency (e.g. NGN) or crypto token (e.g. USDT)
records[].settledAmountInCrypto	number	Amount settled to your wallet in crypto
records[].settlementToken	string	Crypto token the settlement was paid in (e.g. USDT)
records[].collectionMethod	string	Payment method used (e.g. BANK_TRANSFER, CRYPTO_PAYMENT)
records[].customer	object	Customer who made the payment, or null if anonymous
records[].createdAt	string	ISO 8601 timestamp when the transaction was created
records[].completedAt	string	ISO 8601 timestamp when the transaction completed, or null

---

GET /v1/business/transactions/:reference

Returns full details of a single collection transaction by its reference. Only transactions belonging to the authenticated business and environment are accessible.

Path Parameters

Parameter	Type	Required	Description
reference	string	Yes	The transaction reference string

Request

GET /v1/business/transactions/ecb1d467-eaa4-4640-ac61-1a777c86f67a
Authorization: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Response — FIAT collection

{
  "success": true,
  "message": "Transaction retrieved successfully",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "reference": "ecb1d467-eaa4-4640-ac61-1a777c86f67a",
    "status": "SUCCESS",
    "type": "FIAT",
    "source": "FIAT_COLLECTION",
    "origin": "API",
    "environment": "LIVE",
    "failureReason": null,
    "metadata": null,
    "chain": null,
    "address": null,
    "cryptoTransactionHash": null,
    "paymentMethod": "BANK_TRANSFER",
    "customer": {
      "id": "cust-uuid-here",
      "email": "[e-mail]",
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": null
    },
    "collection": {
      "amount": 10000,
      "currency": "NGN",
      "settledAmount": 9990,
      "feeInFiat": 10,
      "receivedAmount": 10000,
      "collectionMethod": "BANK_TRANSFER",
      "recipient": {}
    },
    "createdAt": "2026-01-15T10:00:00.000Z",
    "completedAt": "2026-01-15T10:05:00.000Z"
  }
}

Response — CRYPTO collection

{
  "success": true,
  "message": "Transaction retrieved successfully",
  "data": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "reference": "550e8400-e29b-41d4-a716-446655440000",
    "status": "SUCCESS",
    "type": "CRYPTO",
    "source": "CRYPTO_COLLECTION",
    "origin": "API",
    "environment": "LIVE",
    "failureReason": null,
    "metadata": null,
    "chain": "BSC_MAINNET",
    "address": "0x5020D82d223ffC7Ae770af32eD91d7Af9Fd1adEd",
    "cryptoTransactionHash": "0xabc123...",
    "paymentMethod": "CRYPTO_PAYMENT",
    "customer": {
      "id": "cust-uuid-here-2",
      "email": "[e-mail]",
      "firstName": "Jane",
      "lastName": "Smith",
      "phoneNumber": null
    },
    "collection": {
      "amount": 10.5,
      "currency": "USDT",
      "collectionMethod": "CRYPTO_PAYMENT"
    },
    "createdAt": "2026-01-15T09:00:00.000Z",
    "completedAt": "2026-01-15T09:08:00.000Z"
  }
}

Detail Response Fields

Field	Type	Description
id	string	Transaction UUID
reference	string	Your supplied reference
status	string	Transaction status
type	string	FIAT or CRYPTO
source	string	FIAT_COLLECTION or CRYPTO_COLLECTION
origin	string	How the transaction was initiated
environment	string	LIVE or TEST
settledAmountInCrypto	number	Amount settled to your wallet in crypto
settlementToken	string	Crypto token the settlement was paid in (e.g. USDT), or null
failureReason	string	Reason for failure if status is FAILED, otherwise null
metadata	any	JSON metadata you attached when creating the payment, or null
chain	string	Blockchain network for CRYPTO transactions, or null for FIAT
address	string	Blockchain address funds were sent to (CRYPTO only), or null
cryptoTransactionHash	string	On-chain transaction hash (CRYPTO only), or null
paymentMethod	string	Payment method used
customer	object	Customer who made the payment, or null
customer.phoneNumber	string	Customer phone number, or null
collection	object	Collection-specific details
collection.amount	number	Collected amount
collection.currency	string	Currency of the collected amount
collection.settledAmount	number	Amount settled after fees (FIAT only)
collection.feeInFiat	number	Fee deducted in fiat (FIAT only)
collection.receivedAmount	number	Amount actually received (FIAT only)
collection.collectionMethod	string	Method used for collection
collection.recipient	object	Recipient bank/account details for FIAT, if available
createdAt	string	ISO 8601 creation timestamp
completedAt	string	ISO 8601 completion timestamp, or null

---

Transaction Status Values

Status	Description
PENDING	Payment request created, waiting for customer payment
PROCESSING	Payment detected, being processed
SUCCESS	Payment confirmed and credited
FAILED	Transaction failed
ABANDONED	Payment window closed with no payment received
MISMATCH	Customer sent a different amount than expected
CANCELLED	Transaction was cancelled

---

Error Responses

Status	Message	Cause
401	Unauthorized	Missing or invalid API key
404	Transaction not found	Reference doesn't exist or belongs to another business

---

Code Examples

Node.js — List with filters

const axios = require('axios');

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

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

records.forEach((tx) => {
  console.log(`${tx.reference} — ${tx.status} — ${tx.amount} ${tx.currency}`);
});

Node.js — Get by reference

const axios = require('axios');

const reference = 'ecb1d467-eaa4-4640-ac61-1a777c86f67a';

const { data } = await axios.get(
  `https://api.ivorypay.io/api/v1/business/transactions/${reference}`,
  {
    headers: { Authorization: process.env.IVORYPAY_SECRET_KEY },
  },
);

const tx = data.data;
console.log(`Status: ${tx.status}`);
console.log(`Amount: ${tx.collection.amount} ${tx.collection.currency}`);
console.log(`Customer: ${tx.customer?.email}`);

cURL — List

curl "https://api.ivorypay.io/api/v1/business/transactions?page=1&limit=20&status=SUCCESS" \
  -H "Authorization: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

cURL — Get by reference

curl "https://api.ivorypay.io/api/v1/business/transactions/ecb1d467-eaa4-4640-ac61-1a777c86f67a" \
  -H "Authorization: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

---

Notes

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

• count reflects the total matching records, not just the current page — use it for pagination UI.

• Transactions initiated via CHECKOUT, Payment Links, or Invoices all appear here with the corresponding origin value.