Csob

Scoped accessor that resolves the credentials for the current request and lazily builds a single (bound to the request's mutual-TLS client) shared by all services handling that request.

Thin HTTP wrapper around the ČSOB PSD2 resource API for a single request. It attaches the mandatory COBS headers (Authorization, APIKEY, TPP-Name, X-Request-ID, Date, User-Involved), sends the call over the per-request mutual-TLS client and returns the response JSON verbatim () so no field is lost in translation. Non-success responses become a .

Web defaults (camelCase) match the COBS JSON contract; null properties are omitted on write.

Best-effort parse of the COBS error shape { "errors": [ { "error": "CODE" } ] }.

Raised when the ČSOB PSD2 API returns a non-success HTTP status. Carries the upstream status and the raw error body so the middleware can surface it without leaking credentials.

Machine-readable error codes parsed from the ČSOB errors[].error array (best effort).

Raw response body (already credential-free — it is the upstream's own error payload).

Central registry of ČSOB PSD2 resource path templates (relative to CSOB_API_BASE_URL). Paths follow the Czech Open Banking Standard (COBS) as implemented by ČSOB. The account-scoped AISP paths and the PISP /my/payments/.../sign/{signId} authorization flow are confirmed against the ČSOB developer portal; the remaining COBS resources use the same /my/ prefix. Keep every path here so a portal-specific correction is a single-file change.

Provides instances configured for mutual TLS with a per-request eIDAS client certificate. ČSOB requires the client certificate at the transport layer, so a single shared client cannot be used across tenants. Clients are cached by certificate thumbprint and reused for connection pooling. In practice the certificate identifies the TPP application (not the PSU), so the number of distinct certificates is small and bounded by the set of calling tenants. Certificates and clients live in memory only and never touch disk.

Returns a (cached) mutual-TLS presenting . A fresh certificate instance is built per request; if an equivalent one (same thumbprint) is already cached, the redundant instance is disposed so it does not leak.

Service configuration resolved from environment variables. This service is a stateless, multi-tenant proxy in front of the ČSOB PSD2 (Open Banking) API. Unlike the sibling iDoklad service, it holds no per-client secrets: the eIDAS client certificate, OAuth client id/secret, access token, API key and TPP name are all supplied per request as HTTP headers by the calling client service (see ). Only non-secret infrastructure configuration (API/OAuth base URLs, app metadata, reverse-proxy prefix, timeout) lives here.

Public reverse-proxy prefix (e.g. /apps/csob) injected by AppFactory.

Base URL of the ČSOB PSD2 resource API. Production default; override for any other environment. All AISP/PISP/consent path templates are appended to this base.

OAuth2 authorization endpoint (Authorization Code flow, PSU redirect). Production default; verify against the current ČSOB developer portal as the host may change.

OAuth2 token endpoint (code->token and refresh). Production default; verify against the current ČSOB developer portal.

Upstream HTTP request timeout in seconds.

AISP – account information. All endpoints require the ČSOB credential headers (eIDAS certificate, access token, API key, TPP name). See the Swagger description for details.

List the PSU's payment accounts (paged).

Get the balance(s) of an account.

List booked transactions of an account (paged, optional date range).

List awaiting (pending) transactions of an account.

List the account's existing standing orders.

Get a standing-order detail for the account.

List the account's direct-debit mandates.

Common – PSU consent lifecycle. Requires the ČSOB credential headers. The consent body is forwarded to ČSOB as raw JSON (COBS consent shape).

Create a consent.

Get a consent detail.

Revoke a consent.

PISP – direct-debit mandate initiation and its authorization (sign) flow. Requires the ČSOB credential headers. The mandate body is forwarded to ČSOB as raw JSON (COBS direct-debit shape).

Initiate a direct-debit mandate.

Get the direct-debit mandate detail.

Get the direct-debit instruction status.

Revoke a direct-debit mandate.

Start the authorization (SCA) of a direct-debit mandate. Returns the PSU redirect details.

Get the current state of an authorization (sign) transaction.

Finalize an authorization (sign) transaction.

Service metadata endpoints. These do not require ČSOB credentials.

Liveness probe.

Service name, version and the configured upstream endpoints (no secrets).

Reports the non-secret configuration. This service is stateless and multi-tenant: it holds no credentials, so there is nothing per-client to report — every secret is supplied per request via headers.

OAuth2 Authorization Code helper for the ČSOB PSD2 PSU consent flow. Build the authorization URL, redirect the PSU to it, then exchange the returned code for tokens. The token/refresh calls run over mutual TLS, so they require the X-CSOB-Certificate header; client id/secret are also supplied per request (this service is multi-tenant).

Build the ČSOB authorization URL to which the PSU must be redirected.

Exchange an authorization code for an access/refresh token (mutual TLS).

Refresh an access token using a refresh token (mutual TLS).

PISP – single payment initiation and its authorization (sign) flow. Requires the ČSOB credential headers. After POST /payments the response carries signInfo.signId; use it with the sign endpoints to drive Strong Customer Authentication (SCA).

Initiate a domestic (DMCT) or SEPA (ESCT) payment.

Get the full payment detail.

Get the payment instruction status.

Cancel a not-yet-authorized payment.

Start the authorization (SCA) of a payment. Returns the PSU redirect details.

Get the current state of an authorization (sign) transaction.

Finalize an authorization (sign) transaction.

PISP – standing-order initiation and its authorization (sign) flow. Requires the ČSOB credential headers.

Initiate a standing order.

Get the standing-order detail.

Get the standing-order instruction status.

Cancel a standing order.

Start the authorization (SCA) of a standing order. Returns the PSU redirect details.

Get the current state of an authorization (sign) transaction.

Finalize an authorization (sign) transaction.

Names of the HTTP headers that carry per-request ČSOB credentials and context. This service is multi-tenant: it stores no credentials itself. Every sensitive value is supplied per request in a header (never the query string or body) and is forwarded to ČSOB. Headers must therefore only be sent over TLS. Nothing here is logged or persisted.

eIDAS client certificate (QWAC) as a Base64-encoded PKCS#12 / PFX bundle, including the private key and the full chain. Used to establish the mutual-TLS connection to ČSOB. Analogous to Node's https.Agent({ pfx, passphrase }).

Optional passphrase protecting the PFX in .

OAuth2 Bearer access token obtained for the PSU; forwarded as Authorization: Bearer.

ČSOB application API key; forwarded as the APIKEY header.

TPP (third-party provider) organisation name; forwarded as the TPP-Name header.

OAuth2 client id of the registered TPP application (used by the OAuth helper endpoints).

OAuth2 client secret of the registered TPP application (used by the OAuth helper endpoints).

Whether the PSU is online/involved in the request; forwarded as User-Involved (default false).

PSU IP address; forwarded as User-IP-Address.

Fully resolved set of per-request credentials and PSU context used to call the ČSOB PSD2 API. Built from request headers by ; never logged.

OAuth2 Bearer access token (forwarded as Authorization: Bearer).

ČSOB application API key (forwarded as APIKEY).

TPP organisation name (forwarded as TPP-Name).

eIDAS client certificate (with private key) for mutual TLS. Optional at the type level so metadata endpoints can resolve context, but required for any real upstream call.

Whether the PSU is online for this request (User-Involved); defaults to false.

Optional PSU IP address (User-IP-Address).

Raised when a request does not provide the credential headers required to call ČSOB. Translated to HTTP 401 by the exception-handling middleware.

Resolves the ČSOB credentials and PSU context for the current request, exclusively from HTTP headers (this service stores no secrets). Missing required headers produce a 401; a malformed certificate or wrong passphrase produces a 400 (via ).

Reads a single request header, returning null when absent or blank.

Builds the eIDAS client certificate from the Base64 PFX header (+ optional passphrase). Returns null when no certificate header is present.

The header is not valid Base64 or the PFX/passphrase is invalid.

Resolves the full credential set required for an AISP/PISP/consent call. Throws if any required header is absent.

Documents the per-request credential headers in Swagger. Metadata endpoints need none; the OAuth helper needs the certificate + client id/secret; every other (AISP/PISP/consent) endpoint needs the certificate + access token + API key + TPP name. Headers are marked optional at the schema level (the service validates them at runtime) but the descriptions state what is required.

Translates domain exceptions into JSON responses. Credentials are never logged — only upstream status codes and error codes (the upstream's own payload). Errors are always logged (no silent failures).

Monetary amount with ISO 4217 currency.

Wrapper matching the amount object whose instructedAmount holds the value/currency.

Account number identification. For domestic/SEPA writes only iban is required.

Account reference with optional currency (debtorAccount/creditorAccount).

Payment scheme: DMCT (domestic), ESCT (SEPA), XBCT (cross-border), EXCT, NXCT.

NORM (default), HIGH (express) or INST (instant).

A party (debtor/creditor/ultimate*). Identification is variable, so kept as raw JSON.

Remittance information. unstructured is free text (Czech symbols may be encoded as /VS/.../SS/.../KS/...); structured varies (its reference may be a string or an array) so it is passed through as raw JSON.

Body for POST /oauth/token (Authorization Code grant). Secrets travel in headers.

Authorization code returned to the redirect URI after PSU consent.

Redirect URI registered for the TPP app; must match the one used to obtain the code.

Body for POST /oauth/refresh (Refresh Token grant).

Response of GET /oauth/authorization-url.

Fully-built ČSOB authorization URL to which the PSU must be redirected.

The opaque state value echoed back on the redirect (CSRF protection).

Unique instruction id assigned by the TPP (idempotency key). Max 35 chars.

Payment initiation request (POST /my/payments). Covers domestic (DMCT) and SEPA (ESCT) payments — SEPA-only fields (creditor address, agent, ultimate parties, purpose) are optional. Any additional COBS field not modelled here is preserved via .

Any COBS fields not explicitly modelled are forwarded to ČSOB unchanged.

DAILY, WEEKLY, MONTHLY, BI_MONTHLY, QUARTERLY, HALFYEARLY, YEARLY, SINGLE, IRREGULAR.

Day within the interval (e.g. day-of-month "25").

e.g. MAX_AMOUNT_EXCEEDED, UNTIL_CANCELLATION.

Optional exceptions block (stoppages/breaks); shape varies, kept as raw JSON.

Optional validity block (lastExecutionDate/maxAmount); kept as raw JSON.

Standing-order initiation request (POST /my/standingorders).

AISP – account information (accounts, balance, transactions, standing orders, direct debits).

Optional filters for the transactions listing (forwarded as query parameters).

ISO date (YYYY-MM-DD) lower bound.

ISO date (YYYY-MM-DD) upper bound.

Common – PSU consent lifecycle (create / detail / revoke). The consent request body varies across COBS profiles, so it is accepted and forwarded as raw JSON.

PISP – direct-debit mandate initiation, detail/status, revocation and the sign (SCA) flow. The mandate creation body varies across COBS profiles, so it is accepted and forwarded as raw JSON.

OAuth2 Authorization Code helper for the ČSOB PSD2 flow. Builds the PSU authorization URL and exchanges/refreshes tokens against the ČSOB token endpoint. The token endpoint is behind mutual TLS, so the client certificate header is required for the token/refresh calls. Client id/secret are taken from per-request headers (this service is multi-tenant and stores no app credentials).

Builds the authorization URL to which the PSU must be redirected.

PISP – single payment initiation, status/detail, cancellation and the sign (SCA) flow.

Starts transaction authorization (SCA). Returns the redirect details for the PSU.

Gets the current state of an authorization (sign) transaction.

Finalizes an authorization (sign) transaction.

PISP – standing-order initiation, detail/status, cancellation and the sign (SCA) flow.