Consent and account information

Consent is personal and non-transferable. It belongs to a specific user, organization, and bank. It authorizes account information and payment initiation; it does not approve a payment.

A new consent is normally valid for 180 days, but the user, bank, or another valid state change can invalidate or revoke it earlier. Replace an expired, revoked, or rejected consent by creating a new consent and completing SCA again.

Select the bank and branch

1. Query GET /api/v2/banks/{countryCode}/supported.
2. Verify the bank declares the product your flow needs.
3. If the bank returns branches, let the user select the applicable branch and send that value as bankBranch.
4. Apply the returned constraints rather than assuming all banks behave alike.

The response remains authoritative if this guide and the current environment differ.

Create and complete consent

1. Create consent with POST /api/v2/consents, truthful PSU headers, the user ID, organization number, BIC, callback URL, and branch when required.
2. Store the returned consent ID.
3. Present the returned SCA method. redirect sends the browser to the returned URL. qr presents the bank-app QR data or image. The bank can choose a different method than the preference.
4. Treat the browser return as a signal to resume, not proof of authorization.
5. Poll GET /api/v2/consents with the contract query parameters.
6. Revoke with DELETE /api/v2/consents when the user disconnects the bank.

Consent status	Meaning
AWAITING_AUTHORIZATION	The user still needs to complete SCA.
VALID	The consent can be used for enabled AIS and PIS operations.
REJECTED	Creation or authentication failed; create a replacement when appropriate.
EXPIRED	The validity period ended; create and authorize a replacement.
REVOKED	The user or bank revoked access; create and authorize a replacement if access is still wanted.

Fetch and store accounts promptly

Call GET /api/v2/accounts as soon as consent becomes VALID, and store every returned account ID with the display metadata needed by your product.

An account ID:

• is provided by the bank for subsequent account operations;
• can differ for the same account under two consents;
• can change when consent is replaced; and
• must not be reconstructed from BBAN or IBAN.

Use the ID returned by the current consent for balance, entries, and entry-detail requests.

Balances and entries

Balance responses distinguish:

• booked: transactions posted to the account; and
• available: funds currently available according to the bank.

Do not treat them as interchangeable. For entries, the amount is represented as a positive value; interpret direction together with the entry’s Debit or Credit type. Pending and Booked describe posting status.

The supported-bank response declares the bank’s maximum entry date range. Respect aisMaxDateRangeMonths and any note instead of choosing one global window. Entry-detail support and returned fields vary by bank, so design the UI for missing optional data.

PSU Presence and limits

When the user is actively present, include the PSU headers PSU-IP-Address and PSU-User-Agent in the request. These headers must contain the current values from the user’s session. When included, requests are subject to fair-use limits.

When the user is not present, e.g. when making requests from a background job—these PSU headers must not be included. When the headers are absent, requests are limited to 4 calls per 24 hours, per resource and action. For example, if a consent covers 2 accounts, you can fetch balances and entries up to 4 times each, for both accounts, within a 24-hour period.

See PSU headers and Errors, retries, and reconciliation.