curl --request POST \
  --url https://api.prod.finverse.net/link/token \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "client_id": "{{client_id}}",
  "user_id": "customer_user1",
  "redirect_uri": "{{REDIRECT_URI}}",
  "state": "{{customer_app_id}}_stateparameter",
  "grant_type": "client_credentials",
  "response_mode": "form_post",
  "response_type": "code",
  "automatic_data_refresh": "",
  "countries": [],
  "institution_id": "",
  "institution_status": "alpha beta supported",
  "language": "en",
  "link_mode": "",
  "products_requested": [],
  "products_supported": [],
  "ui_mode": "",
  "user_configs": {},
  "user_type": []
}
'

{
  "access_token": "{link_token}",
  "expires_in": 300,
  "issued_at": "2022-08-01T01:01:00.000Z",
  "link_url": "https://link.sandbox.finverse.net/onboarding?token={link_token}",
  "token_type": "Bearer"
}

Link

Generate link_url

Generate a short-lived Finverse Link access_token (referred to as link_token) and URL (link_url) to open Finverse Link UI in a browser window. The link_token is associated with a specific Customer App (client_id) and End-User (user_id), and expires after 5 minutes (resend request to renew).

Note:redirect_uri must be valid and associated with the client_id.

Authorization: customer_token.

Required parameters

Optional parameters

You can use the following optional parameters to customize the behaviour of Finverse Link’s UI to fit your implementation requirements.

Automatic data refresh

Parameter: automatic_data_refresh

Description: Configures the “Automatic data refresh” checkbox in Finverse Link’s “Enter your credentials” input screen.

Recommended value: "" (none). This defaults to OFF (i.e. checkbox unchecked, user editable).

Accepted values:

Countries

Parameter: countries

Description: Filters the “Select Institution” screen in the Finverse Link UI to only list institutions from the specified countries. If left empty, all institutions are listed.

Recommended value: [ ]

Accepted values: JSON-array of 3-letter ISO-3166-1 Alpha-3 codes (e.g. ["SGP", "VNM"])

History Date Limit

Parameter: history_date_limit

Description: sets a specific start date limit for the transaction history retrieved by Finverse from the institution. This is useful when you only need Finverse to fetch recent transactions and want to speed up data retrieval. If omitted, Finverse will fetch the full available transaction history (3-24 months depending on the institution).

Recommended Value: omit the parameter

Accepted values: ISO 8601 date string (“YYYY-MM-DD”)

Institution ID

Parameter: institution_id

Description: Instructs Finverse Link UI to skip the institution selection screen (after the consent screen), and instead go straight to the login screen of the specified institution.

Recommended Value: ""

Accepted values: A single institution’s institution_id (see GET /institutions).

Institution status

Parameter: institution_status

Description: Specifies which institutions to list in the Finverse Link UI based on their reliability status (e.g. “beta” status).

Recommended value: ""

Accepted values: space-separated list

beta : show only institutions that are in “beta” status
supported : show only institutions that are in “supported” status (default for Customer Apps in live mode)
beta supported : show both “beta” and “supported” institutions (default for Customer Apps in test mode)

Language

Parameter: language

Description: Specifies the desired language selection for Finverse Link.

Recommended value: "" or any valid language code (based on desired UI). If empty or if an unsupported language is specified, Finverse Link will display the default language (en).

Accepted values: 2-letter ISO 639-1 alpha-2 code. Supported languages:

(note: inputs are case-sensitive)

Link mode

Parameter: link_mode

Description: Specifies whether to display specific sets of institutions (e.g. test institutions) in the Finverse Link UI. This can be helpful for testing purposes, for example to force-display test institutions when testing in the Finverse Prod environment.

Recommended value: "" for live apps; “test” or “real test” for test apps.

Accepted values: space-separated list

real : show only real banks (default)
test : show only test banks
real test shows both real banks & test banks

Products requested

Parameter: products_requested

Description: Instructs Finverse to only fetch the products specified in this field. If left empty, Finverse will fetch all data products.

Recommended value: [ ]

Accepted values: JSON-array of strings of Finverse products (e.g. ["ACCOUNTS", "TRANSACTIONS"])

Products supported

Parameter: products_supported

Description: Filters the “Select Institution” screen in the Finverse Link UI to only list institutions which support the specified products. If left empty, all institutions are listed.

Recommended value: [ ]

Accepted values: JSON-array of strings of Finverse products (e.g. ["ACCOUNT_NUMBERS", "IDENTITY", "STATEMENTS"])

UI mode

Parameter: ui_mode

Description: Specifies the behaviour of the Finverse Link UI upon completion of the linking flow (in both success or error cases). If left empty, Finverse Link will default to iframe behaviour for the Data institution linking UI.

Recommended values: any (based on desired UI)

Accepted values:

"": defaults to iframe behaviour for the Data institution linking UI.
iframe: for use when the Finverse Link UI is launched as an iframe/webview embedded within the customer’s application. On success/error, the callback to the customer’s redirect_uri is triggered in the background, and the response is silently discarded. Finverse will display an Exit (“X”) button on each screen and a “Continue” button on final success/error screens, allowing the user to close the iframe/webview and return to the customer’s application (requires customer’s application to handle iframe/webview messages).
redirect: for use when the Finverse Link UI is launched in a new window/webview. On success/error, the callback isn’t triggered immediately, but is bound to the “Continue” and “Exit” buttons. When the user clicks either button, the UI will navigate to the customer’s redirect_uri.
auto_redirect: similar to redirect mode, for use when the Finverse Link UI is launched in a new window/webview. On success/error, the callback is automatically triggered after 1 second, and the UI navigates to the customer’s redirect_uri.
standalone: for use when the Finverse Link UI is launched in a new window/webview without the need to navigate back to the customer’s application. On success/error, the callback to the customer’s redirect_uri is triggered in the background, and the response is silently discarded. Finverse will display a “You may close this window now” message on final success/error screens, guiding the user to manually close the window/webview.

User configs

Beta (subject to change).

Parameter: user_configs

Description: Object to configure additional user-level inputs for the User’s authentication & data retrieval session.

Recommended value:

Accepted values: see below

User type

Parameter: user_type

Description: Filters the “Select Institution” screen in the Finverse Link UI to only list institutions which support the specified user type (e.g. individual vs. business accounts). If left empty, all institutions are listed.

Recommended value: [ ]

Accepted values: JSON-array of strings of Finverse user types (e.g. ["BUSINESS", "INDIVIDUAL"])

Token handling

Usage

link_token is intended for use by front-end clients to call Finverse API. It is the only Finverse API token that is considered non-sensitive.

Renewal

link_token expires after 5 minutes.

Repeat this request for token renewal.

POST

link

token

curl --request POST \
  --url https://api.prod.finverse.net/link/token \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "client_id": "{{client_id}}",
  "user_id": "customer_user1",
  "redirect_uri": "{{REDIRECT_URI}}",
  "state": "{{customer_app_id}}_stateparameter",
  "grant_type": "client_credentials",
  "response_mode": "form_post",
  "response_type": "code",
  "automatic_data_refresh": "",
  "countries": [],
  "institution_id": "",
  "institution_status": "alpha beta supported",
  "language": "en",
  "link_mode": "",
  "products_requested": [],
  "products_supported": [],
  "ui_mode": "",
  "user_configs": {},
  "user_type": []
}
'

{
  "access_token": "{link_token}",
  "expires_in": 300,
  "issued_at": "2022-08-01T01:01:00.000Z",
  "link_url": "https://link.sandbox.finverse.net/onboarding?token={link_token}",
  "token_type": "Bearer"
}

Authorizations

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

token request

client_id

string

required

Assigned by Finverse when setting up API credentials in Finverse's customer dashboard (dashboard.finverse.com)

Required string length: 4 - 100

Example:

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

grant_type

string

required

Always equal to: client_credentials

Maximum string length: 100

redirect_uri

string

required

Finverse Link UI will redirect to this uri after either success or failure

Required string length: 4 - 500

Example:

"https://example.com/callback"

response_mode

string

required

Always equal to: form_post

Maximum string length: 100

Example:

"form_post"

response_type

string

required

Always equal to: code

Maximum string length: 100

Example:

"code"

automatic_data_refresh

enum<string>

Controls the behavior of the automatic data refresh checkbox

Available options:

ON,

OFF,

FORCED_ON

Maximum string length: 100

code_challenge

string

Maximum string length: 100

Example:

"code-challenge"

code_challenge_method

string

Maximum string length: 100

Example:

"code-challenge-method"

countries

string[]

institution's country filter

Maximum string length: 3

Example:

["HKG", "SGP"]

customization_id

string

The customization id if the customer wishes to embed it into link token for spawning link with their choice of stuffs

Maximum string length: 100

Example:

"AULIDGOESHERE"

history_date_limit

string<date>

Limit historical data retrieval to this date. ISO format (YYYY-MM-DD)

Example:

"2024-01-31"

institution_id

string

Institution to preselect

Maximum string length: 100

Example:

"hsbc-hk"

institution_status

string

institution's status filter

Maximum string length: 100

Example:

"alpha beta supported"

language

enum<string>

ISO639-1 language code. Language to display when user open the link, default to English (en) if not specified

Available options:

en,

vi,

zh,

ko

Maximum string length: 3

Example:

"en"

link_mode

string

Space separated list of the tags of the institutions to view.

Maximum string length: 100

Example:

"real"

use this to update a specific login identity

Maximum string length: 100

Example:

"uhdasidasodaso"

payment_instruction_id

string

The identifier returned after creating payment instruction

Maximum string length: 100

Example:

"payment_instruction_id"

products_requested

string[]

products that is requested

Maximum string length: 100

Example:

["ACCOUNTS", "TRANSACTIONS", "PAYMENTS"]

products_supported

string[]

institution's supported product filter

Maximum string length: 100

Example:

["ACCOUNTS", "TRANSACTIONS"]

scope

string

Maximum string length: 500

Example:

"comma,separated,scopes"

state

string

Customer-supplied state (treated as an opaque value), used by customer to uniquely identify the linking session

Maximum string length: 100

Example:

"user-state-passed"

ui_mode

enum<string>

The UI mode link is intended to be used in - "iframe", "auto_redirect", "redirect" or "standalone"

Available options:

iframe,

redirect,

auto_redirect,

standalone

Example:

"redirect"

user_configs

object

Show child attributes

user_id

string

Customer-supplied ID, used by customer to uniquely identify the user

Required string length: 4 - 100

Example:

"01BX5ZZKBKACTAV9WEVGEMMVRY"

user_type

string[]

institution's supported user_type filter

Maximum string length: 100

Example:

["PERSONAL"]

Response

Success

access_token

string

required

Link session token (referred to as link_token)

expires_in

integer<int64>

required

Token validity length (in seconds)

issued_at

string<date-time>

required

Token issue time

link_url

string

required

URL to launch the Finverse Link UI flow associated with this link_token, for the end-user to provide required consent and linking inputs.

Example:

"https://link.dev.finverse.net/onboarding?token=dasdsa8erhiu7rey78r"

token_type

string

required

Possible values: Bearer