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

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