Transactions

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

---

Endpoints

Method	Path	Auth	Description
GET	/v1/business/transactions/:reference/verify	API Key	Verify the current status of a transaction
GET	/v1/business/transactions/refresh/:reference	API Key	Refresh the payment session and recalculate amounts

---

GET /v1/business/transactions/:reference/verify

Returns the live status and settlement details of a transaction identified by its reference.

Use this endpoint to:

• Poll for payment confirmation while waiting for a webhook

• Display a payment result screen after your customer completes a payment

• Confirm a transaction was settled before fulfilling an order

Request

Headers

Authorization: <your-secret-api-key>

Path Parameters

Parameter	Type	Required	Description
reference	string	Yes	The unique transaction reference returned on creation

Example Request

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

---

Response

{
  "success": true,
  "message": "Verification successful",
  "data": {
    "id": "8d3a19c2-f013-4b67-8f2e-9c4e5a6b7d82",
    "reference": "ecb1d467-eaa4-4640-ac61-1a777c86f67a",
    "status": "SUCCESS",
    "type": "FIAT",
    "channel": "OFF_CHAIN",
    "crypto": "USDT",
    "settledAmountInCrypto": 0.9912,
    "expectedAmountInCrypto": 1.0,
    "receivedAmountInCrypto": 1.0,
    "amountInBaseFiat": 1000,
    "baseFiat": "NGN",
    "address": null,
    "chain": null,
    "expiresAt": null,
    "completedAt": "2026-02-19T10:14:32.000Z",
    "createdAt": "2026-02-19T10:04:02.000Z"
  }
}

---

Response Fields

Field	Type	Description
id	string (uuid)	Internal transaction ID
reference	string	Your supplied reference, used for reconciliation
status	string	Current transaction status. See status values
type	string	Payment channel type — CRYPTO or FIAT
channel	string	Settlement channel — ON_CHAIN or OFF_CHAIN
crypto	string	Token used for this transaction — e.g. USDT, USDC
settledAmountInCrypto	number	Net crypto amount credited to your wallet after fees
expectedAmountInCrypto	number	Exact amount the customer was asked to send
receivedAmountInCrypto	number	Actual amount received on-chain or via bank
amountInBaseFiat	number	Original fiat amount the transaction was created with
baseFiat	string	Fiat currency of amountInBaseFiat — e.g. NGN, USD
address	string | null	Blockchain address assigned (CRYPTO transactions only)
chain	string | null	Blockchain network — e.g. BSC_MAINNET, POLYGON (CRYPTO only)
expiresAt	string | null	ISO timestamp when the payment window closes (CRYPTO only)
completedAt	string | null	ISO timestamp when the transaction reached a terminal status
createdAt	string	ISO timestamp when the transaction was created

---

Transaction Status Values

Status	Terminal	Description
PENDING	No	Awaiting payment from the customer
SUCCESS	Yes	Payment confirmed and settled to your wallet
FAILED	Yes	Transaction failed during processing
EXPIRED	Yes	Payment window closed with no payment received
MISMATCH	Yes	Customer sent a different amount than expected

Terminal statuses will not change. Once a transaction reaches SUCCESS, FAILED, EXPIRED, or MISMATCH, no further updates occur. Stop polling at that point.

---

CRYPTO vs FIAT — Response Differences

Field	CRYPTO	FIAT
type	"CRYPTO"	"FIAT"
channel	"ON_CHAIN"	"OFF_CHAIN"
address	Blockchain wallet address	null
chain	Blockchain network (e.g. BSC_MAINNET)	null
expiresAt	ISO timestamp of the payment window expiry	null
receivedAmountInCrypto	Actual on-chain amount received	Amount received via bank transfer (in crypto equivalent)

---

Error Responses

Status	Message	Cause
401	Unauthorized	Missing or invalid API key
404	Transaction not found	No transaction matches the provided reference

---

Polling vs Webhooks

Webhooks are the recommended approach for detecting payment status changes — they are near real-time and reduce unnecessary load. Use verification polling only as a fallback.

Approach	When to use
Webhooks	Primary method. IvoryPay pushes status updates to your registered webhook URL
Polling	Fallback. Poll every 5–10 seconds until you reach a terminal status

See Webhooks for event types, signature verification, and setup.

---

Integration Flow

1. Create transaction  →  POST /v1/transactions
2. Show payment instructions to customer
3. Customer completes payment
4. IvoryPay fires webhook  →  handle cryptoCollection.success or fiatCollection.success
5. (Fallback) Poll GET /v1/business/transactions/:reference/verify until status is terminal
6. status === "SUCCESS"  →  fulfill the order

---

Code Examples

Node.js

const axios = require('axios');

const BASE_URL = 'https://api.ivorypay.io/api/v1';
const reference = 'ecb1d467-eaa4-4640-ac61-1a777c86f67a';

const { data } = await axios.get(
  `${BASE_URL}/business/transactions/${reference}/verify`,
  {
    headers: { Authorization: process.env.IVORYPAY_SECRET_KEY },
  },
);

const { status, settledAmountInCrypto, crypto, completedAt } = data.data;

if (status === 'SUCCESS') {
  console.log(
    `Payment settled: ${settledAmountInCrypto} ${crypto} at ${completedAt}`,
  );
} else if (['EXPIRED', 'FAILED', 'MISMATCH'].includes(status)) {
  console.log(`Payment did not complete. Status: ${status}`);
} else {
  console.log(`Payment still in progress. Status: ${status}`);
}

Node.js — Polling with backoff

const axios = require('axios');

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

const TERMINAL_STATUSES = ['SUCCESS', 'FAILED', 'EXPIRED', 'MISMATCH'];

async function pollVerification(
  reference,
  intervalMs = 5000,
  maxAttempts = 36,
) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const { data } = await axios.get(
      `${BASE_URL}/business/transactions/${reference}/verify`,
      {
        headers: { Authorization: process.env.IVORYPAY_SECRET_KEY },
      },
    );

    const { status } = data.data;
    console.log(`[${attempt + 1}] Status: ${status}`);

    if (TERMINAL_STATUSES.includes(status)) {
      return data.data;
    }

    await new Promise((resolve) => setTimeout(resolve, intervalMs));
  }

  throw new Error('Max polling attempts reached without a terminal status');
}

const result = await pollVerification('ecb1d467-eaa4-4640-ac61-1a777c86f67a');
console.log('Final transaction:', result);

cURL

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

Python

import requests
import time

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

TERMINAL_STATUSES = {"SUCCESS", "FAILED", "EXPIRED", "MISMATCH"}

def verify_transaction(reference: str) -> dict:
    response = requests.get(
        f"{BASE_URL}/business/transactions/{reference}/verify",
        headers={"Authorization": SECRET_KEY},
    )
    response.raise_for_status()
    return response.json()["data"]

def poll_until_terminal(reference: str, interval: int = 5, max_attempts: int = 36) -> dict:
    for attempt in range(max_attempts):
        txn = verify_transaction(reference)
        status = txn["status"]
        print(f"[{attempt + 1}] Status: {status}")

        if status in TERMINAL_STATUSES:
            return txn

        time.sleep(interval)

    raise TimeoutError("Max polling attempts reached")

result = poll_until_terminal("ecb1d467-eaa4-4640-ac61-1a777c86f67a")
print(result)

---

GET /v1/business/transactions/refresh/:reference

Refreshes an active payment session for a CRYPTO transaction. Use this when the original payment window has expired or when you want to recalculate the crypto amount at the current exchange rate before the customer pays.

On a successful refresh:

• A new session is created with a fresh 10-minute payment window

• The crypto amount is recalculated at the current market rate

• The same wallet address remains valid for the new session

This endpoint is only applicable to CRYPTO transactions. FIAT transactions do not have a refreshable session.

Request

Headers

Authorization: <your-secret-api-key>

Path Parameters

Parameter	Type	Required	Description
reference	string	Yes	The unique transaction reference returned on creation

Query Parameters

Parameter	Type	Required	Description
fiatCurrency	string	No	Fiat currency to use for amount recalculation. Defaults to NGN. See values.

Example Request

GET /v1/business/transactions/refresh/550e8400-e29b-41d4-a716-446655440000?fiatCurrency=NGN
Authorization: sk_xxxxxxxxxxxx

---

Response

{
  "success": true,
  "message": "Session refreshed successfully",
  "data": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "[e-mail]",
    "refCode": "REF-12345",
    "reference": "550e8400-e29b-41d4-a716-446655440000",
    "transferDetails": {
      "token": "USDT",
      "blockchain": "BSC_MAINNET",
      "amount": 1.032,
      "amountPayable": 1.032,
      "businessFee": 0,
      "platformFee": 0.032,
      "walletAddress": "0x5020D82d223ffC7Ae770af32eD91d7Af9Fd1adEd",
      "fiatAmount": 1400250.5,
      "expiresAt": "2026-02-27T10:32:00.000Z",
      "duration": 600,
      "sessionId": "sess_9f3a1b2c4d5e6f78",
      "createdAt": "2026-02-27T10:22:00.000Z"
    }
  }
}

---

Response Fields

Field	Type	Description
firstName	string	Customer's first name
lastName	string	Customer's last name
email	string	Customer's email address
refCode	string	Customer's reference code
reference	string	Transaction reference
transferDetails.token	string	Crypto token — e.g. USDT, USDC
transferDetails.blockchain	string	Blockchain network — e.g. BSC_MAINNET, POLYGON
transferDetails.amount	number	Recalculated crypto amount the customer must send
transferDetails.amountPayable	number	Same as amount — the exact payable amount
transferDetails.platformFee	number	IvoryPay's fee included in amount
transferDetails.businessFee	number	Your configured business fee included in amount
transferDetails.walletAddress	string	Blockchain address the customer sends funds to
transferDetails.fiatAmount	number	Fiat equivalent of amount in the requested fiatCurrency
transferDetails.expiresAt	string	ISO timestamp when the new session expires
transferDetails.duration	number	Session validity in seconds (600)
transferDetails.sessionId	string	New session identifier
transferDetails.createdAt	string	ISO timestamp when the session was created

---

Error Responses

Status	Message	Cause
400	Invalid transaction reference	No transaction matches the provided reference
400	Invalid fiat currency	The supplied fiatCurrency is not supported
401	Unauthorized	Missing or invalid API key

---

fiatCurrency Values

Value	Currency
NGN	Nigerian Naira
USD	US Dollar

---

Code Examples

Node.js

const axios = require('axios');

const BASE_URL = 'https://api.ivorypay.io/api/v1';
const reference = '550e8400-e29b-41d4-a716-446655440000';

const { data } = await axios.get(
  `${BASE_URL}/business/transactions/refresh/${reference}`,
  {
    params: { fiatCurrency: 'NGN' },
    headers: { Authorization: process.env.IVORYPAY_SECRET_KEY },
  },
);

const { transferDetails } = data.data;
console.log(`Send ${transferDetails.amount} ${transferDetails.token} to ${transferDetails.walletAddress}`);
console.log(`New session expires at: ${transferDetails.expiresAt}`);

cURL

curl "https://api.ivorypay.io/api/v1/business/transactions/refresh/550e8400-e29b-41d4-a716-446655440000?fiatCurrency=NGN" \
  -H "Authorization: sk_xxxxxxxxxxxx"