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`


🚀 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):

| Endpoint | Description |
|----------|-------------|
| `POST /ais/consents/create` | Create a new AIS consent for data access |
| `POST /ais/consents/get` | Retrieve consent details and current status |
| `POST /ais/consents/revoke` | Revoke an active consent |
| `POST /ais/transactions/list` | List transactions with filtering and keyset pagination |
| `POST /ais/accounts/list` | List accounts with balance information |
| `POST /ais/balances/list` | List balance history with pagination |
| `POST /ais/jobs/create` | Trigger an on-demand data refresh job |
| `POST /ais/jobs/get` | Get data refresh job status |

##### Consent Lifecycle

AIS consents follow this lifecycle:

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

**Terminal states:** `expired`, `revoked`, `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..."
  }
}
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `pagination.limit` | integer | Maximum records per page (1-250, default: 50) |
| `pagination.after` | string | Keyset cursor from previous response for next page |

**Response includes:**

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

##### New Filter Options

Filter payment links by multiple criteria:

| Filter | Type | Description |
|--------|------|-------------|
| `filter.status` | string | Filter by payment status (`created`, `completed`, `failed`, etc.) |
| `filter.inserted_at_from` | datetime | Links created after this timestamp |
| `filter.inserted_at_to` | datetime | Links created before this timestamp |

**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):

| Status | Description |
|--------|-------------|
| `funds_received` | Funds confirmed received by creditor bank (via webhook) |
| `funds_rejected` | Funds rejected by creditor bank (via webhook) |

---

#### Enhanced: Providers API

##### AIS Methods Support

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

**New options:**

| Option | Type | Description |
|--------|------|-------------|
| `options.show_ais_methods` | boolean | Include AIS method details in response |
| `options.ais_methods_filter.account_owner_type` | array | Filter by account owner type (`retail`, `corporate`) |
| `options.ais_methods_filter.interface_type` | string | Filter by interface type |
| `options.ais_methods_filter.interface_env` | string | Filter by environment (`sandbox`, `stage`, `prod`) |

**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:

| Version | Format | Example |
|---------|--------|---------|
| **v1** | String | `"retail"` or `"corporate"` |
| **v2** | Array | `["retail"]`, `["corporate"]`, or `["retail", "corporate"]` |

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

| Template | Description |
|----------|-------------|
| `default` | Standard/legacy FinqLink layout |
| `classic` | Traditional banking interface |
| `compact` | Minimal, space-efficient layout |
| `cards` | Card-based provider selection |
| `glass` | Glassmorphism design with blur effects |
| `sheet` | Bottom sheet mobile-first design |

##### 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

| Version | Status | End of Life |
|---------|--------|-------------|
| v1 | Supported | TBD |
| v2 | Current | - |


📋 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

Revoke Consent

Data

List Accounts

List Balances

List Transactions

Jobs

Create Data Refresh Job

Get Data Refresh Job

Links

Create Link

Get Link

Handle Redirect

List Links

Providers

Get Provider

List Providers

mTLS

OAuth2

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:

| Scope | Description |
|-------|-------------|
| `["accounts", "balances", "transactions"]` | Full access (default) - includes transaction history |
| `["accounts", "balances"]` | Accounts and balances only - faster job completion |

**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
| Status | Description |
|--------|-------------|
| `created` | Consent created, not yet accessed |
| `started` | User accessed consent link |
| `sca_url_retrieved` | Bank SCA URL obtained |
| `awaiting_authz` | Waiting for user authorization |
| `authorized` | User authorized, processing |
| `active` | Consent active, data accessible |
| `expired` | Authorization link timed out (user can no longer access WebUI) |
| `revoked` | Data access withdrawn (manually or after consent validity ended) |
| `failed` | Authorization failed |
| `suspended` | Consent temporarily suspended |

### Understanding Expiration vs Revocation

There are two different time-based concepts for consents:

| Concept | Field | Description |
|---------|-------|-------------|
| **Link Expiration** | `expires_at` (from `expires_in`) | When the authorization link/URL becomes inaccessible. After this time, users cannot access the WebUI to complete bank authorization. Max 45 days. |
| **Consent Validity** | `authorized_until` (from `consent_validity_days`) | When the data access consent expires and is automatically revoked. After this time, data retrieval is no longer possible. Max 180 days. |

- **Expired**: The authorization link has timed out - only affects the ability to complete the SCA flow
- **Revoked**: The data access consent has been terminated - no more access to banking data (either manually via API or automatically when `authorized_until` is reached)

### 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"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `type` | string | Always `consent_status_update` |
| `consent_id` | uuid | The consent that was updated |
| `status` | string | New consent status (see statuses above) |


Sections

Consents

Overview

Consent Scope

Consent Lifecycle

Consent Statuses

Understanding Expiration vs Revocation

Webhooks

What made this section unhelpful for you?

Endpoints

What made this section unhelpful for you?

Scope	Description
`["accounts", "balances", "transactions"]`	Full access (default) - includes transaction history
`["accounts", "balances"]`	Accounts and balances only - faster job completion

Status	Description
`created`	Consent created, not yet accessed
`started`	User accessed consent link
`sca_url_retrieved`	Bank SCA URL obtained
`awaiting_authz`	Waiting for user authorization
`authorized`	User authorized, processing
`active`	Consent active, data accessible
`expired`	Authorization link timed out (user can no longer access WebUI)
`revoked`	Data access withdrawn (manually or after consent validity ended)
`failed`	Authorization failed
`suspended`	Consent temporarily suspended

Concept	Field	Description
Link Expiration	`expires_at` (from `expires_in`)	When the authorization link/URL becomes inaccessible. After this time, users cannot access the WebUI to complete bank authorization. Max 45 days.
Consent Validity	`authorized_until` (from `consent_validity_days`)	When the data access consent expires and is automatically revoked. After this time, data retrieval is no longer possible. Max 180 days.

Field	Type	Description
`type`	string	Always `consent_status_update`
`consent_id`	uuid	The consent that was updated
`status`	string	New consent status (see statuses above)

Sections

Consents

Overview

Consent Scope

Consent Lifecycle

Consent Statuses

Understanding Expiration vs Revocation

Webhooks

What made this section unhelpful for you?

Endpoints

What made this section unhelpful for you?

Ask an AI

Code with AI