Banking API conventions

Every Banking API operation shares the same response shape, the same pagination rules and the same date format. Here we explain those shared rules.

Response envelope#

Every response, successful or not, travels in the same envelope:

{
  "success": true,
  "http_status_code": 200,
  "response_code": "OK",
  "message": "The request was processed successfully.",
  "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": {}
}

Error responses also carry errors, a detail object that may include arbitrary fields such as code, message or detail.

Branch your logic on response_code, never on the message text.

Correlation#

Send X-Correlation-Id on the request to propagate your own identifier; the value comes back as correlation_id in the envelope. Keep it in your logs: it is what support uses to trace a specific call.

Safe retries#

Two operations accept the Idempotency-Key header:

POST /api/public/v1/transactions/payments
POST /api/public/v1/accounts/statements

Resending the same key with the same body returns the original result instead of creating a second record, so a network timeout can be retried without duplicating. If you reuse a key with a different body, the response is 409 with response_code: IDEMPOTENCY_CONFLICT.

Generate one key per business intent (for example a UUID per order), not one per retry. Every other operation is a read and can be repeated with no additional effects.

Pagination#

The API uses two schemes depending on the resource.

Cursor, on the payment list. GET /api/public/v1/transactions/payments accepts limit (default 20, maximum 100) and cursor. The response carries pagination.next_cursor: pass it as cursor on the next request. When it is empty or omitted, there are no more pages.

Offset, on accounts. GET /api/public/v1/accounts and GET /api/public/v1/accounts/balances accept limit (1 to 100) and offset (from 0), and return pagination with limit, offset and total.

Dates and amounts#

Date parameters and fields use RFC 3339, for example 2026-09-02T15:04:05Z. The date_from and date_to filters on the payment list follow that same format.

Host health and documentation#

The host itself exposes three service routes:

GET /api/public/v1/healthz
GET /openapi.yaml
GET /docs

healthz is for availability checks, openapi.yaml returns the OpenAPI definition and /docs the interactive documentation. We also publish it in this portal at openapi.json and openapi.yaml.