Overview

FinqLink is a set of APIs for account-to-account payments/transfers (FinqLink Pay) and account information services (FinqLink Data) 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.

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

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/consents/redirect	Handle SCA callback redirect (direct_sca flow)
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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "payment_methods": [{
    "remitter_type": "retail"
  }]
}

v2 Response:

{
  "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:

{
  "links": [...]
}

v2 Response:

{
  "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	-

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.

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

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

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 documentation for more details.

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:

{
  "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)

Retrieve account information including accounts, transactions, and balances

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

Status	Description
job_started	Job created and queued for processing
accounts_ready	Accounts fetched and stored
balances_ready	Balances fetched and stored
transactions_fetching	Transactions fetching in progress (skipped for accounts/balances scope)
job_partially_completed	Some data fetched successfully
job_completed	All data fetched successfully
job_failed	Job failed due to an error

Webhooks

Provide a callback_url when creating a job to receive notifications on status changes.

Webhook Payload:

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

Field	Type	Description
type	string	Always job_status_update
consent_id	uuid	The consent associated with this job
job_id	uuid	The job that was updated
status	string	New job status (see statuses above)

Initiates a background job to refresh AIS data (accounts, balances, transactions) from the banking provider.

Consent status: The consent must be active. Otherwise, this endpoint returns 400 with code consent_not_active.

Cooldown Period

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

Callback URL

You can optionally provide a callback URL to receive a notification when the job completes.

Gets the current status and details of a data refresh job.

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

Job Statuses

• job_started: Job created
• accounts_ready: Accounts fetched and stored in the database
• balances_ready: Balances fetched and stored in the database
• transactions_fetching: Transactions fetching has started
• job_partially_completed: Job completed partially (some data was fetched and stored)
• job_completed: Job completed successfully
• job_failed: Job failed (no data was fetched and stored)