Banking API conventions

Every Banking API operation shares the same response shape, the same pagination rules and the same date format. This page describes what the spec declares across all endpoints.

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 raw spec and /docs the service's documentation UI. In this portal the same spec is available at openapi.json and openapi.yaml.