📋 Changelog

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:

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