Requests & responses

Base URL

https://api.catholicpay.example/api/v1

Every endpoint is under /merchant/…, over HTTPS only. Test and live use the same addresses: your key decides the mode.

Requests

• Send JSON with Content-Type: application/json.
• Requests that create something or move money need an Idempotency-Key header.
• Dates are YYYY-MM-DD; times are RFC 3339 in UTC, such as 2026-11-10T09:00:00Z.

Money

Amounts are naira as a string with two decimals, in requests and responses:

{ "amount": "45000.00" }

Send amounts as strings: a JSON number is refused, so no amount is ever rounded as a floating-point number. Fees are shown alongside the amount they apply to (for example fee and charged_amount on a checkout).

Responses

A success wraps the result in data:

{
  "data": {
    "reference": "INV-1001",
    "status": "ACTIVE"
  }
}

A list adds meta.pagination (Pagination):

{
  "data": [ … ],
  "meta": { "pagination": { "limit": 50, "has_more": true, "next_cursor": "eyJ…" } }
}

An error has a code to act on and a message to show (Errors):

{
  "code": "VALIDATION_ERROR",
  "message": "Some fields are missing or invalid.",
  "details": { "amount": "must be more than 0" },
  "request_id": "01JC…"
}

Status codes

Status	Meaning
200	OK. Also the answer to a repeated request: the same reference or idempotency key returns the first result
201	Created
202	Accepted: the work continues in the background (a bulk transfer)
204	Done, nothing to return (a deleted customer)
4xx	Your request cannot be done as sent: see code
5xx	Something failed on our side or at the bank: retry with the same Idempotency-Key

Request IDs

Every response has an X-Request-ID header, and errors repeat it as request_id. Quote it when you contact support.