Balance & history

Balance

curl https://api.catholicpay.example/api/v1/merchant/account \
  -H "Authorization: Bearer $CATHOLICPAY_SECRET_KEY"

{
  "data": {
    "number": "0123456789",
    "currency": "NGN",
    "status": "ACTIVE",
    "balance": { "ledger": "125000.00", "available": "120000.00", "held": "5000.00" },
    "wallets": [
      { "id": "…", "name": "Main", "is_default": true, "status": "ACTIVE", "visibility": "PUBLISHED",
        "balance": { "ledger": "100000.00", "available": "95000.00", "held": "5000.00" } }
    ]
  }
}

available is what you can spend; held is reserved for something in progress; ledger is both. A wallet’s visibility says whether payers can choose it (PUBLISHED) or not (PRIVATE).

GET /merchant/me gives your organisation’s name, type and account number, and your key’s mode.

History

curl "https://api.catholicpay.example/api/v1/merchant/account/history?from=2026-11-01&to=2026-11-30" \
  -H "Authorization: Bearer $CATHOLICPAY_SECRET_KEY"

Every credit and debit, newest first, each with its wallet_id, date, direction (CREDIT or DEBIT), amount, narration, reference and balance_after. Narrow it to one wallet with wallet_id. Pages hold up to 100 entries (Pagination).

Statements

GET /merchant/account/statement?from=2026-11-01&to=2026-11-30&format=pdf returns your statement as a file: pdf or csv. Statements need a live key.