Finqware

Introduction

### Overview

FinqLink is a set of APIs for account-to-account payments/transfers ([FinqLink Pay](https://developers.finqware.com/api-reference/pay-apis)) and account information services ([FinqLink Data](https://developers.finqware.com/api-reference/data-apis)) through open-banking and other local/custom integrations.

### How to test

1. Get a set of API test credentials (contact Finqware)
2. Use the /test/providers/list endpoint to query for the available/supported providers.
  - to visualize the providers list (and more) check our public [dashboard](https://pay.finqware.com/web/v2/providers).
3. Create finq-links using the `/test` path:
  - payment links using the `/test/links/create` endpoint
  - consent links for account data using the `/test/consents/create` endpoint.
4. Send the link to someone in order to authorize the payment or to authorize access to account data.

### Sandbox testing

- `rzb_ro` - debtor IBAN: `RO03RZBR0000069999999999`, creditor IBAN: `RO10RZBR0000069999999970`, PSU ID: `9999999998`
- `bt_ro` - username: `testbt`, password: `testbt`, pin: `1234567`
- `cec_ro` - username: `testcecapi`, password: `testcecapi`, IBAN: `RO42CECEAG0202RON0007466`
- `granit_hu` - username: `testuser`, password: `testuser`, SMS code: `SMS`
- `mbh_hu` - username: `testuser`, password: `testuser`, SMS code: `SMS`


🚀 Quick Start

### Version 2.0 Changelog

This document outlines all changes between FinqLink API v1 and v2, including new features, enhancements, and breaking changes.

---

#### Overview

FinqLink v2 is a major release that introduces:

- **FinqLink Data (Beta)** - Account Information Services (AIS) for accessing bank account data
- **Enhanced Pay APIs** - Pagination, filtering, and new link statuses
- **Custom WebUI Templates** - 7 customizable UI themes for payment and consent flows
- **Providers API Enhancements** - AIS methods support and improved response formats

---

#### New: Account Information Services (AIS) - FinqLink Data

The most significant addition in v2 is the complete **Account Information Services (AIS)** functionality, branded as **FinqLink Data**. This enables bank account data access alongside existing payment initiation capabilities.

> **Note:** FinqLink Data is currently in **Beta**. Contact Finqware to enable AIS access for your API client.

##### New API Endpoints

All AIS endpoints are available on `/v2` API paths only (not available in v1):

<Table style="width:100%;min-width:100%" colSizes='["initial", "initial"]' isHeaderAdded='true' tableHeader='[{"id": "5c7ce57a-9a66-465e-a960-03789fd59e2b", "title": "Endpoint"}, {"id": "686b5b9c-6317-44ab-8168-656e59e2f000", "title": "Description"}]'>
  <table-row>
    <table-cell>POST /ais/consents/create</table-cell>
    <table-cell>Create a new AIS consent for data access</table-cell>
  </table-row>
  <table-row>
    <table-cell>POST /ais/consents/get</table-cell>
    <table-cell>Retrieve consent details and current status</table-cell>
  </table-row>
  <table-row>
    <table-cell>POST /ais/consents/revoke</table-cell>
    <table-cell>Revoke an active consent</table-cell>
  </table-row>
  <table-row>
    <table-cell>POST /ais/consents/redirect</table-cell>
    <table-cell>Handle SCA callback redirect (direct_sca flow)</table-cell>
  </table-row>
  <table-row>
    <table-cell>POST /ais/transactions/list</table-cell>
    <table-cell>List transactions with filtering and keyset pagination</table-cell>
  </table-row>
  <table-row>
    <table-cell>POST /ais/accounts/list</table-cell>
    <table-cell>List accounts with balance information</table-cell>
  </table-row>
  <table-row>
    <table-cell>POST /ais/balances/list</table-cell>
    <table-cell>List balance history with pagination</table-cell>
  </table-row>
  <table-row>
    <table-cell>POST /ais/jobs/create</table-cell>
    <table-cell>Trigger an on-demand data refresh job</table-cell>
  </table-row>
  <table-row>
    <table-cell>POST /ais/jobs/get</table-cell>
    <table-cell>Get data refresh job status</table-cell>
  </table-row>
</Table>

##### Consent Lifecycle

AIS consents follow this lifecycle:

```
created → started → requested → sca_url_retrieved → awaiting_authz → authorized → active
```

**Terminal states:** `expired`, `revoked`, `deactivated`, `failed`, `suspended`

##### Scope Configuration

Control what data is accessible through consent scope:

- **Full scope:** `["accounts", "balances", "transactions"]` - Access to all account data
- **Limited scope:** `["accounts", "balances"]` - Faster job completion, no transaction history

##### AIS Webhooks

Configure webhooks in consent creation to receive real-time updates:

- **`consent_status_update`** - Triggered when consent status changes (e.g., `awaiting_authz` → `active`)
- **`job_status_update`** - Triggered when data refresh job completes or fails

---

#### Enhanced: Links API

##### Pagination for `/links/list`

The `/links/list` endpoint now supports **keyset-based pagination** for efficient traversal of large result sets.

**Request parameters:**

```json
{
  "pagination": {
    "limit": 50,
    "after": "eyJpbnNlcnRlZF9hdCI6..."
  }
}
```

<Table style="width:100%;min-width:100%" colSizes='["initial", "initial", "initial"]' isHeaderAdded='true' tableHeader='[{"id": "66cfaa92-25a7-4d71-9aae-6f07f4421d59", "title": "Parameter"}, {"id": "def6ff38-7d19-4732-ae74-f46a4298fbac", "title": "Type"}, {"id": "b6177084-88b6-4fcb-b468-1d60f8969af1", "title": "Description"}]'>
  <table-row>
    <table-cell>pagination.limit</table-cell>
    <table-cell>integer</table-cell>
    <table-cell>Maximum records per page (1-250, default: 50)</table-cell>
  </table-row>
  <table-row>
    <table-cell>pagination.after</table-cell>
    <table-cell>string</table-cell>
    <table-cell>Keyset cursor from previous response for next page</table-cell>
  </table-row>
</Table>

**Response includes:**

```json
{
  "pagination": {
    "count": 50,
    "more?": true,
    "after": "eyJpbnNlcnRlZF9hdCI6Li4u"
  },
  "links": [...]
}
```

##### New Filter Options

Filter payment links by multiple criteria:

<Table style="width:100%;min-width:100%" colSizes='["initial", "initial", "initial"]' isHeaderAdded='true' tableHeader='[{"id": "ab1dbd40-c4fc-4732-8f0f-016c8c92182c", "title": "Filter"}, {"id": "0a9dc2e5-ee0b-4466-905b-f5bacdf02f2e", "title": "Type"}, {"id": "5562f6c8-c754-4d70-b7f4-4f797d1704f9", "title": "Description"}]'>
  <table-row>
    <table-cell>filter.status</table-cell>
    <table-cell>string</table-cell>
    <table-cell>Filter by payment status (created, completed, failed, etc.)</table-cell>
  </table-row>
  <table-row>
    <table-cell>filter.inserted_at_from</table-cell>
    <table-cell>datetime</table-cell>
    <table-cell>Links created after this timestamp</table-cell>
  </table-row>
  <table-row>
    <table-cell>filter.inserted_at_to</table-cell>
    <table-cell>datetime</table-cell>
    <table-cell>Links created before this timestamp</table-cell>
  </table-row>
</Table>

**Example:**

```json
{
  "filter": {
    "status": "completed",
    "inserted_at_from": "2024-01-01T00:00:00Z"
  },
  "pagination": {
    "limit": 100
  }
}
```

##### New Payment Link Statuses

Additional statuses for enhanced payment tracking (available for libra_ro, work-in-progress for other providers):

<Table style="width:100%;min-width:100%" colSizes='["initial", "initial"]' isHeaderAdded='true' tableHeader='[{"id": "a5030bbc-a9e2-4a32-9ede-06a382a8d46a", "title": "Status"}, {"id": "79c546f6-7e6e-4cfe-bc3c-11ff1c57735b", "title": "Description"}]'>
  <table-row>
    <table-cell>funds_received</table-cell>
    <table-cell>Funds confirmed received by creditor bank (via webhook)</table-cell>
  </table-row>
  <table-row>
    <table-cell>funds_rejected</table-cell>
    <table-cell>Funds rejected by creditor bank (via webhook)</table-cell>
  </table-row>
</Table>

---

#### Enhanced: Providers API

##### AIS Methods Support

The `/providers/list` and `/providers/get` endpoints now support AIS method discovery:

**New options:**

<Table style="width:100%;min-width:100%" colSizes='["initial", "initial", "initial"]' isHeaderAdded='true' tableHeader='[{"id": "9823cd86-260c-4dea-abfd-3244127d9d8c", "title": "Option"}, {"id": "dc5031b0-e5dd-4954-9095-b50d9b042094", "title": "Type"}, {"id": "99ff1fda-8a1e-4492-837d-4889a6478a0a", "title": "Description"}]'>
  <table-row>
    <table-cell>options.show_ais_methods</table-cell>
    <table-cell>boolean</table-cell>
    <table-cell>Include AIS method details in response</table-cell>
  </table-row>
  <table-row>
    <table-cell>options.ais_methods_filter.account_owner_type</table-cell>
    <table-cell>array</table-cell>
    <table-cell>Filter by account owner type (retail, corporate)</table-cell>
  </table-row>
  <table-row>
    <table-cell>options.ais_methods_filter.interface_type</table-cell>
    <table-cell>string</table-cell>
    <table-cell>Filter by interface type</table-cell>
  </table-row>
  <table-row>
    <table-cell>options.ais_methods_filter.interface_env</table-cell>
    <table-cell>string</table-cell>
    <table-cell>Filter by environment (sandbox, stage, prod)</table-cell>
  </table-row>
</Table>

**Example:**

```json
{
  "options": {
    "show_ais_methods": true,
    "ais_methods_filter": {
      "account_owner_type": ["retail"],
      "interface_env": "prod"
    }
  }
}
```

##### Response Format Change: `remitter_type`

The `remitter_type` field format has changed between v1 and v2:

<Table style="width:100%;min-width:100%" colSizes='["initial", "initial", "initial"]' isHeaderAdded='true' tableHeader='[{"id": "6b667f89-56bf-442f-87da-fb99e619b58d", "title": "Version"}, {"id": "6ac04005-bec5-4101-b7e7-3e7793a62c7d", "title": "Format"}, {"id": "f4eaccae-6048-4499-be7b-5830ee3a9dc9", "title": "Example"}]'>
  <table-row>
    <table-cell>v1</table-cell>
    <table-cell>String</table-cell>
    <table-cell>"retail" or "corporate"</table-cell>
  </table-row>
  <table-row>
    <table-cell>v2</table-cell>
    <table-cell>Array</table-cell>
    <table-cell>["retail"], ["corporate"], or ["retail", "corporate"]</table-cell>
  </table-row>
</Table>

This change enables payment methods to support multiple remitter types simultaneously.

---

#### New: WebUI Custom Templates

Customize the payment and consent authorization UI with pre-built templates.

##### Available Templates

<Table style="width:100%;min-width:100%" colSizes='["initial", "initial"]' isHeaderAdded='true' tableHeader='[{"id": "c02228da-0e2c-4fe1-94f3-a2dda9ccc73f", "title": "Template"}, {"id": "0c5b6fba-278a-4c18-9be6-4d8f2d0d9f55", "title": "Description"}]'>
  <table-row>
    <table-cell>default</table-cell>
    <table-cell>Standard/legacy FinqLink layout</table-cell>
  </table-row>
  <table-row>
    <table-cell>classic</table-cell>
    <table-cell>Traditional banking interface</table-cell>
  </table-row>
  <table-row>
    <table-cell>compact</table-cell>
    <table-cell>Minimal, space-efficient layout</table-cell>
  </table-row>
  <table-row>
    <table-cell>cards</table-cell>
    <table-cell>Card-based provider selection</table-cell>
  </table-row>
  <table-row>
    <table-cell>glass</table-cell>
    <table-cell>Glassmorphism design with blur effects</table-cell>
  </table-row>
  <table-row>
    <table-cell>sheet</table-cell>
    <table-cell>Bottom sheet mobile-first design</table-cell>
  </table-row>
</Table>

##### Usage

Specify the template in `/links/create` or `/ais/consents/create`:

```json
{
  "options": {
    "ux_template": "glass"
  }
}
```

> **Note:** The `ux_template` option overrides the default template configured for your API client.

---

#### Breaking Changes

##### 1. `remitter_type` Response Format

**Affected endpoints:** `/providers/list`, `/providers/get`

The `remitter_type` field in payment method responses has changed from a string to an array:

**v1 Response:**
```json
{
  "payment_methods": [{
    "remitter_type": "retail"
  }]
}
```

**v2 Response:**
```json
{
  "payment_methods": [{
    "remitter_type": ["retail"]
  }]
}
```

**Migration:** Update your code to handle `remitter_type` as an array.

##### 2. AIS Endpoints Availability

AIS endpoints (`/ais/*`) are **only available on /v2 paths**. Requests to `/v1/ais/*` will return a 404 error.

##### 3. Pagination Response Structure

The `/links/list` endpoint now returns pagination metadata in a structured format:

**v1 Response:**
```json
{
  "links": [...]
}
```

**v2 Response:**
```json
{
  "pagination": {
    "count": 50,
    "more?": true,
    "after": "cursor_token"
  },
  "links": [...]
}
```

**Migration:** Update your code to extract links from the `links` array and handle pagination metadata.

---

#### Migration Guide

##### Upgrading from v1 to v2

1. **Update API path:** Change from `/v1/` to `/v2/`
2. **Handle array `remitter_type`:** Update providers response parsing to treat `remitter_type` as an array
3. **Optional**: If using `/links/list`, handle the new pagination response structure
4. **Optional - Enable AIS:** Contact Finqware to enable FinqLink Data access for your API client
5. **Optional - Customize UI:** Explore the new `ux_template` options for branded payment experiences

##### API Version Support

<Table style="width:100%;min-width:100%" colSizes='["initial", "initial", "initial"]' isHeaderAdded='true' tableHeader='[{"id": "bbbacb07-d4e4-449f-b8a1-b7f6ce1480d4", "title": "Version"}, {"id": "3ebb2654-3a35-42f7-9c68-9be52259f218", "title": "Status"}, {"id": "67126568-22e2-486d-9c85-1c8e7f03aafe", "title": "End of Life"}]'>
  <table-row>
    <table-cell>v1</table-cell>
    <table-cell>Supported</table-cell>
    <table-cell>TBD</table-cell>
  </table-row>
  <table-row>
    <table-cell>v2</table-cell>
    <table-cell>Current</table-cell>
    <table-cell>-</table-cell>
  </table-row>
</Table>


📋 Changelog

API Reference

The Link API is secured by OAuth2 (mandatory for production access) and mTLS (optional).

Mutual TLS (mTLS) and OAuth2 Client Credentials are two distinct security mechanisms that can complement each other to provide robust authentication and secure communication in API integrations.

> **Note:** For testing purposes we also support an internal authentication method that requires `client_id`/`client_secret` with each API call. The code examples in this document use this particular method.

### How mTLS and OAuth2 Client Credentials Complement Each Other

When used together, mTLS and OAuth2 Client Credentials Grant provide a powerful combination of strong client authentication and fine-grained authorization. Here's how they complement each other:

### Dual Authentication and Authorization

- mTLS provides a strong, cryptographic client authentication mechanism, ensuring that only authorized clients (those with valid client certificates) can establish a connection.
- OAuth2 Client Credentials provides a token-based mechanism for authorizing the client's access to specific APIs or resources. The access token contains information about the client's permissions and access scope.

### Layered Security

By using both mTLS and OAuth2, you establish multiple layers of security. Even if an access token is somehow obtained by an attacker, mTLS ensures that only clients with a valid certificate can connect. Conversely, even if a client possesses a valid certificate, it still needs a valid access token to access protected resources.

### Preventing Token Theft and Replay Attacks

With mTLS, the secure communication channel prevents token theft during transmission. Even if a token were somehow intercepted, it would be useless without the client's certificate to establish the connection.

### Enhanced Security for Sensitive Applications

For highly sensitive applications, combining mTLS with OAuth2 Client Credentials ensures that only authenticated clients (validated by their certificates) and authorized clients (validated by their tokens) can access resources. This is particularly important in zero-trust environments or for internal microservices communication.

### Compliance and Regulatory Requirements

Some industries require strong client authentication and end-to-end encryption. Combining mTLS with OAuth2 can help meet these regulatory requirements by ensuring secure communication and controlled access.

### Summary

By combining mTLS with OAuth2 Client Credentials Grant, you gain the benefits of both strong client authentication and fine-grained access control, enhancing the overall security posture of your application.


Security

Payment initiation and provider discovery endpoints.

### Overview

FinqLink Pay is a set of APIs for account-to-account payments/transfers through open-banking and other local/custom integrations (eg: RoPay in Romania).

The platform enables API clients to create payment links that allow end-users to complete payments through
their banking providers using Strong Customer Authentication (SCA).

Pay-by-link is a method that breaks the payment process in two distinct phases:

- the creation of a payment request, operated by the creditor (receiver of funds)
- the acceptance & authorization of the payment, operated by the debtor (the source of funds)

The payment request encapsulates metadata such as: amount, currency, the list of goods to be acquired etc. Once its created, the payment request is wrapped into a transportable object - aka the link- such as a URL or a QR code. The link is sent to a debtor who will only check/approve & authorize the payment.

### Payment providers

A payment-provider is a partner institution that operates payment services. FinqLink integrates with these providers over APIs such as open-banking payment initiation APIs.
Each provider has a unique code. Eg: `rzb_ro`, `cec_ro` etc.
A provider may have one or multiple payment-methods offering different capabilities (domestic-only transfers, corporate-only transfers etc)
we provide an API and a [dashboard](https://pay.finqware.com/web/v2/providers) for quering and visualising all the details regarding providers & methods.

### Payment Flow Types
The API supports multiple payment flow types:
- **link**: Default web-based payment experience via FinqLink WebUI
- **wrapped_sca**: SCA URLs wrapped in a transportable link operated via FinqLink WebUI
- **direct_sca**: Mobile app-to-app experience with direct bank redirect (requires a custom eIDAS certificates setup)
- **redirect_sca**: Mobile app-to-app experience with redirect via FinqLink WebUI

### The FinqLink Pay WebUI

The WebUI is a web application that facilitates the payment process by providing a user interface for the end-user to complete the payment.
It comes with a payment-method selection component, payment details and real-time status updates.

![FinqLink Pay WebUI](https://d24lr4zqs1tgqh.cloudfront.net/b0c679fe-4d42-41a1-8f3f-59bf8af00056-693c10b7ef5867a056b9d195.png)

### Webhooks
The API supports webhook notifications for payment status updates.
Configure webhook URLs when creating payment links. Webhook payloads include:
- `type`: Event type (e.g., "link_status_update")
- `link_id`: The payment link UUID
- `web_id`: The public web identifier
- `status`: New payment status

### Decimal Values
Monetary amounts are represented as strings to maintain precision (e.g., "100.50").
- No leading zeros allowed (except for values less than 1, e.g., "0.50")
- No comma separators allowed
- Decimal point is optional for whole amounts


Pay APIs

Account Information Services (AIS) endpoints for accessing banking data.

Note: This API is in public beta and may be slightly changed based on your feedback.

Webhooks are supported for:
- **Consent status updates**: Notified when consent status changes (e.g., `started` → `active`)
- **Job status updates**: Notified when data refresh jobs complete or change status

Banking data retrieval endpoints for accounts, balances, and transactions.

### Pagination
The transactions and balances list endpoints use keyset-based pagination.
Use the `keyset` value from the last record as the `after` parameter
in your next request to fetch the next page.

### Filtering
All data endpoints support filtering by various criteria:
- Accounts: currency, account type
- Balances: currency, type, account ID
- Transactions: amount range, date range, credit/debit indicator, status

### Balance Types
Check the [balance types](data-apis/data/list-balances) documentation for more details.


Data APIs

FinqLink APIs

Finqware Link API

Testing server (client_id/client_secret)

Testing server (OAuth2)

Production server (OAuth2)

Consents

Create Consent

Get Consent

Handle Redirect

Revoke Consent

Data

List Accounts

List Balances

List Transactions

Jobs

Create Data Refresh Job

Get Data Refresh Job

Links

Create Link

Get Link

List Links

Providers

Get Provider

List Providers

mTLS

OAuth2

Webhook signing and callbacks

Manage user consents for accessing account information.

AIS consent management endpoints for accessing banking account information.

### Overview
Account Information Services (AIS) allows authorized access to banking data including
accounts, balances, and transactions. Users must authorize access through their bank's
Strong Customer Authentication (SCA) flow.

### Consent Scope
When creating a consent, you can specify which types of data you want to access:

<Table style="width:100%;min-width:100%" colSizes='["initial", "initial"]' isHeaderAdded='true' tableHeader='[{"id": "38ab55bd-bd49-40e7-a173-e4b1880b8fb7", "title": "Scope"}, {"id": "dc30de67-0c54-457d-80c1-374f8eef1a62", "title": "Description"}]'>
  <table-row>
    <table-cell>["accounts", "balances", "transactions"]</table-cell>
    <table-cell>Full access (default) - includes transaction history</table-cell>
  </table-row>
  <table-row>
    <table-cell>["accounts", "balances"]</table-cell>
    <table-cell>Accounts and balances only - faster job completion</table-cell>
  </table-row>
</Table>

**Note:** Other scope combinations are not supported. If no scope is provided, full scope is assumed.

### Consent Lifecycle
1. Create consent with desired scope (accounts, balances, or full)
2. User authorizes via bank's SCA flow
3. Consent becomes active for data access
4. Use data endpoints to retrieve banking information
5. Refresh data as needed using background jobs

### Consent Statuses
<Table style="width:100%;min-width:100%" colSizes='["initial", "initial"]' isHeaderAdded='true' tableHeader='[{"id": "339b8246-34ab-4790-a0bf-c95ec1086ac4", "title": "Status"}, {"id": "9e1195d0-84dc-4cf3-b8c8-e83cb093361e", "title": "Description"}]'>
  <table-row>
    <table-cell>created</table-cell>
    <table-cell>Consent created, not yet accessed</table-cell>
  </table-row>
  <table-row>
    <table-cell>started</table-cell>
    <table-cell>User accessed consent link</table-cell>
  </table-row>
  <table-row>
    <table-cell>sca_url_retrieved</table-cell>
    <table-cell>Bank SCA URL obtained</table-cell>
  </table-row>
  <table-row>
    <table-cell>awaiting_authz</table-cell>
    <table-cell>Waiting for user authorization</table-cell>
  </table-row>
  <table-row>
    <table-cell>authorized</table-cell>
    <table-cell>User authorized, processing</table-cell>
  </table-row>
  <table-row>
    <table-cell>active</table-cell>
    <table-cell>Consent active, data accessible</table-cell>
  </table-row>
  <table-row>
    <table-cell>expired</table-cell>
    <table-cell>Authorization link timed out (user can no longer access WebUI)</table-cell>
  </table-row>
  <table-row>
    <table-cell>revoked</table-cell>
    <table-cell>Data access explicitly withdrawn via API (/ais/consents/revoke)</table-cell>
  </table-row>
  <table-row>
    <table-cell>deactivated</table-cell>
    <table-cell>Consent validity period ended (authorized_until reached) - automatic</table-cell>
  </table-row>
  <table-row>
    <table-cell>failed</table-cell>
    <table-cell>Authorization failed</table-cell>
  </table-row>
  <table-row>
    <table-cell>suspended</table-cell>
    <table-cell>Consent temporarily suspended</table-cell>
  </table-row>
</Table>

### Understanding Expiration vs Revocation

There are two different time-based concepts for consents:

<Table style="width:100%;min-width:100%" colSizes='["initial", "initial", "initial"]' isHeaderAdded='true' tableHeader='[{"id": "4c2342a7-7f85-4b23-b702-985b81a07446", "title": "Concept"}, {"id": "eb2bc54f-b041-4bea-81b9-8fa44ed0425f", "title": "Field"}, {"id": "b19f11c9-b44d-4c55-8b0d-a3437689a758", "title": "Description"}]'>
  <table-row>
    <table-cell>Link Expiration</table-cell>
    <table-cell>expires_at (from expires_in)</table-cell>
    <table-cell>When the authorization link/URL becomes inaccessible. After this time, users cannot access the WebUI to complete bank authorization. Max 45 days.</table-cell>
  </table-row>
  <table-row>
    <table-cell>Consent Validity</table-cell>
    <table-cell>authorized_until (from consent_validity_days)</table-cell>
    <table-cell>When the data access consent expires and is automatically deactivated. After this time, data retrieval is no longer possible. Max 180 days.</table-cell>
  </table-row>
</Table>

- **Expired**: The authorization link has timed out - only affects the ability to complete the SCA flow
- **Revoked**: The data access consent has been explicitly terminated via the `/ais/consents/revoke` API endpoint (manual/client-driven)
- **Deactivated**: The consent validity period has ended (`authorized_until` reached) - automatic/system-driven, no more access to banking data

### Webhooks
Configure `webhook_url` when creating consents to receive notifications on status changes.

**Webhook Payload:**
```json
{
  "type": "consent_status_update",
  "consent_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "active"
}
```

<Table style="width:100%;min-width:100%" colSizes='["initial", "initial", "initial"]' isHeaderAdded='true' tableHeader='[{"id": "e2977cbc-bd9e-4e48-b9f6-82a4c6960a7e", "title": "Field"}, {"id": "afdf849a-45ff-4ef3-add0-dc8432fe5f97", "title": "Type"}, {"id": "b65f8143-b046-479e-ab3d-3db93eda3456", "title": "Description"}]'>
  <table-row>
    <table-cell>type</table-cell>
    <table-cell>string</table-cell>
    <table-cell>Always consent_status_update</table-cell>
  </table-row>
  <table-row>
    <table-cell>consent_id</table-cell>
    <table-cell>uuid</table-cell>
    <table-cell>The consent that was updated</table-cell>
  </table-row>
  <table-row>
    <table-cell>status</table-cell>
    <table-cell>string</table-cell>
    <table-cell>New consent status (see statuses above)</table-cell>
  </table-row>
</Table>


Retrieve account information including accounts, transactions, and balances

Retrieves a list of bank accounts associated with a consent, with optional filtering.
Each account includes the latest balances from the most recent data refresh job.

**Consent status**: If the consent is `expired`, `revoked`, `deactivated`, `failed`, or `suspended`, this endpoint returns `400` with code `consent_not_active`.

### Filtering
Accounts can be filtered by:
- Currency
- Account type (e.g., "Personal current account")
- Account sub-type (e.g., "CurrentAccount")


Retrieves a list of bank transactions with optional filtering and keyset-based pagination.

**Consent status**: If the consent is `expired`, `revoked`, `deactivated`, `failed`, or `suspended`, this endpoint returns `400` with code `consent_not_active`.

### Pagination
Use the `keyset` value from the last transaction in the current page as the `after`
parameter in your next request to fetch the next page. The `pagination.more?` field
indicates if more records are available.

### Sort Order
Transactions are returned sorted by `booking_date_time` descending (most recent first),
then by `inserted_at` descending within the same booking date, then by `id` descending as
a tiebreaker for keyset pagination. Transactions without a booking date appear last.

### Filtering
Transactions can be filtered by:
- Amount range (min/max)
- Currency
- Booking date range
- Account ID
- Credit/debit indicator
- Transaction status


Retrieves a history of account balances associated with a consent, with optional filtering. For the most recent balance only, please check the [accounts/list](list-accounts) endpoint.

**Consent status**: If the consent is `expired`, `revoked`, `deactivated`, `failed`, or `suspended`, this endpoint returns `400` with code `consent_not_active`.

### Important Notes
- At least one normalized balance type (`available`) is always provided per account
- The `amount` field is always a **positive number** - use `credit_debit_indicator` to determine the actual sign
- For overdraft/negative balances, `credit_debit_indicator` will be `debit`

### Normalized Balance Types
These types are commonly available across banks:

<Table style="width:100%;min-width:100%" colSizes='["initial", "initial"]' isHeaderAdded='true' tableHeader='[{"id": "ccfd1516-f7c2-42cf-bb92-00d1a54aeff3", "title": "Type"}, {"id": "d4ecf870-bd4d-4eec-807e-700a33b4cfe7", "title": "Description"}]'>
  <table-row>
    <table-cell>available</table-cell>
    <table-cell>Available balance calculated in the course of the business day, at the time specified, subject to further changes. Calculated on booked credit/debit items.</table-cell>
  </table-row>
  <table-row>
    <table-cell>closing</table-cell>
    <table-cell>Closing balance of cleared amount. Only provided when bank explicitly provides ClosingCleared/Booked balance.</table-cell>
  </table-row>
</Table>

### Additional Bank-Specific Balance Types

<Table style="width:100%;min-width:100%" colSizes='["initial", "initial"]' isHeaderAdded='true' tableHeader='[{"id": "948b1f5c-c4f7-45b5-8dde-8dcf10dae028", "title": "Type"}, {"id": "8e4c4af4-1906-4e61-a2c9-bbfed0d4ba15", "title": "Description"}]'>
  <table-row>
    <table-cell>closing_available</table-cell>
    <table-cell>Closing balance at account owner's disposal on the date specified</table-cell>
  </table-row>
  <table-row>
    <table-cell>closing_booked</table-cell>
    <table-cell>Balance at end of pre-agreed account reporting period (sum of opening booked + all entries during period)</table-cell>
  </table-row>
  <table-row>
    <table-cell>closing_cleared</table-cell>
    <table-cell>Closing balance of cleared amount on date specified</table-cell>
  </table-row>
  <table-row>
    <table-cell>expected</table-cell>
    <table-cell>Balance of booked entries and pending items, projecting end-of-day balance if everything is booked</table-cell>
  </table-row>
  <table-row>
    <table-cell>forward_available</table-cell>
    <table-cell>Forward available balance at disposal on date specified</table-cell>
  </table-row>
  <table-row>
    <table-cell>information</table-cell>
    <table-cell>Balance for informational purposes</table-cell>
  </table-row>
  <table-row>
    <table-cell>interim_available</table-cell>
    <table-cell>Available balance in course of business day, subject to changes</table-cell>
  </table-row>
  <table-row>
    <table-cell>interim_booked</table-cell>
    <table-cell>Balance calculated in course of business day, subject to changes</table-cell>
  </table-row>
  <table-row>
    <table-cell>interim_cleared</table-cell>
    <table-cell>Cleared balance in course of business day, subject to changes</table-cell>
  </table-row>
  <table-row>
    <table-cell>opening_available</table-cell>
    <table-cell>Opening balance at account owner's disposal on date specified</table-cell>
  </table-row>
  <table-row>
    <table-cell>opening_booked</table-cell>
    <table-cell>Book balance at beginning of reporting period (equals previous closing book balance)</table-cell>
  </table-row>
  <table-row>
    <table-cell>opening_cleared</table-cell>
    <table-cell>Opening balance of cleared amount on date specified</table-cell>
  </table-row>
  <table-row>
    <table-cell>previously_closed_booked</table-cell>
    <table-cell>Balance at previously closed reporting period</table-cell>
  </table-row>
</Table>

### Balance Interpretation Guide

The meaning of a balance depends on the combination of `type`, `credit_limit_included`, and `credit_debit_indicator`:

###### Available Balance

<Table style="width:100%;min-width:100%" colSizes='["initial", "initial", "initial"]' isHeaderAdded='true' tableHeader='[{"id": "95bbd4fc-7235-4632-ab57-dd5bd9c848ee", "title": "credit_limit_included"}, {"id": "548d8dd7-9afd-4dca-820f-28ea48734055", "title": "credit_debit_indicator"}, {"id": "1f05d245-15e3-4bbb-97a4-1edbde12da8d", "title": "Meaning"}]'>
  <table-row>
    <table-cell>false</table-cell>
    <table-cell>credit</table-cell>
    <table-cell>Account balance representing the amount of money which can be spent</table-cell>
  </table-row>
  <table-row>
    <table-cell>false</table-cell>
    <table-cell>debit</table-cell>
    <table-cell>Borrowed funds from the account's associated overdraft</table-cell>
  </table-row>
  <table-row>
    <table-cell>true</table-cell>
    <table-cell>credit</table-cell>
    <table-cell>Total balance = account balance + overdraft value</table-cell>
  </table-row>
</Table>

###### Closing Balance

<Table style="width:100%;min-width:100%" colSizes='["initial", "initial", "initial"]' isHeaderAdded='true' tableHeader='[{"id": "6a0bd71c-08cd-4ed6-bba6-d4e59a1af86d", "title": "credit_limit_included"}, {"id": "2a072ff4-027c-4cf6-beed-e5408588a848", "title": "credit_debit_indicator"}, {"id": "58d9caed-782e-49d8-b63c-abb8e147d0ed", "title": "Meaning"}]'>
  <table-row>
    <table-cell>false</table-cell>
    <table-cell>credit</table-cell>
    <table-cell>Account balance at the official banking day closing</table-cell>
  </table-row>
  <table-row>
    <table-cell>false</table-cell>
    <table-cell>debit</table-cell>
    <table-cell>Borrowed funds from overdraft at banking day closing</table-cell>
  </table-row>
  <table-row>
    <table-cell>true</table-cell>
    <table-cell>credit</table-cell>
    <table-cell>Remaining unused overdraft amount at day closing</table-cell>
  </table-row>
</Table>


Schedule and monitor background data refresh operations.

Background data refresh job management for AIS.

### Purpose
After initial consent authorization, use jobs to refresh banking data on demand.
Jobs fetch the latest accounts, balances, and transactions from the banking provider.

### Scope-Based Job Behavior
Job execution varies based on the consent's scope:
- **Full scope** (`[accounts, balances, transactions]`): Job fetches all data types including transaction history
- **Accounts/balances only** (`[accounts, balances]`): Job completes faster by skipping transaction fetching

For consents with `[accounts, balances]` scope, jobs will transition directly from `balances_ready` to `job_completed`.

### Cooldown Period
A cooldown period is enforced between refresh requests to prevent excessive
API calls to banking providers. If you attempt to create a job during the
cooldown period, you'll receive a 400 error with code `cooldown_failed`.

### Job Statuses
<Table style="width:100%;min-width:100%" colSizes='["initial", "initial"]' isHeaderAdded='true' tableHeader='[{"id": "5844ee03-e814-4fc9-9d35-e8e895ea896e", "title": "Status"}, {"id": "ede0e293-15bb-45ea-aa9e-49b43a7aecc2", "title": "Description"}]'>
  <table-row>
    <table-cell>job_started</table-cell>
    <table-cell>Job created and queued for processing</table-cell>
  </table-row>
  <table-row>
    <table-cell>accounts_ready</table-cell>
    <table-cell>Accounts fetched and stored</table-cell>
  </table-row>
  <table-row>
    <table-cell>balances_ready</table-cell>
    <table-cell>Balances fetched and stored</table-cell>
  </table-row>
  <table-row>
    <table-cell>transactions_fetching</table-cell>
    <table-cell>Transactions fetching in progress (skipped for accounts/balances scope)</table-cell>
  </table-row>
  <table-row>
    <table-cell>job_partially_completed</table-cell>
    <table-cell>Some data fetched successfully</table-cell>
  </table-row>
  <table-row>
    <table-cell>job_completed</table-cell>
    <table-cell>All data fetched successfully</table-cell>
  </table-row>
  <table-row>
    <table-cell>job_failed</table-cell>
    <table-cell>Job failed due to an error</table-cell>
  </table-row>
</Table>

### Webhooks
Provide a `webhook_url` when creating a job to receive notifications on status changes.

**Webhook Payload:**
```json
{
  "type": "job_status_update",
  "consent_id": "123e4567-e89b-12d3-a456-426614174000",
  "job_id": "job-uuid-456",
  "status": "job_completed"
}
```

<Table style="width:100%;min-width:100%" colSizes='["initial", "initial", "initial"]' isHeaderAdded='true' tableHeader='[{"id": "c7fef563-9069-4e73-8845-0021a6d472bb", "title": "Field"}, {"id": "db8bc997-6e10-48ff-b626-865182843012", "title": "Type"}, {"id": "7e915d0b-cc40-4c3e-bce7-81c14167077d", "title": "Description"}]'>
  <table-row>
    <table-cell>type</table-cell>
    <table-cell>string</table-cell>
    <table-cell>Always job_status_update</table-cell>
  </table-row>
  <table-row>
    <table-cell>consent_id</table-cell>
    <table-cell>uuid</table-cell>
    <table-cell>The consent associated with this job</table-cell>
  </table-row>
  <table-row>
    <table-cell>job_id</table-cell>
    <table-cell>uuid</table-cell>
    <table-cell>The job that was updated</table-cell>
  </table-row>
  <table-row>
    <table-cell>status</table-cell>
    <table-cell>string</table-cell>
    <table-cell>New job status (see statuses above)</table-cell>
  </table-row>
</Table>


Sections

Data

What made this section helpful for you?

What made this section unhelpful for you?

Endpoints

What made this section helpful for you?

What made this section unhelpful for you?

Sections

Data

What made this section helpful for you?

What made this section unhelpful for you?

Endpoints

What made this section helpful for you?

What made this section unhelpful for you?

Ask an AI

Code with AI