Retrieve Institutions list

curl --request GET \
  --url https://api.prod.finverse.net/institutions \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.prod.finverse.net/institutions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.prod.finverse.net/institutions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prod.finverse.net/institutions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.prod.finverse.net/institutions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

[
  {
    "color": "#FFFFFF",
    "countries": [
      "HKG"
    ],
    "institution_id": "hsbc-hk",
    "institution_name": "HSBC (HK) - Personal",
    "institution_type": "BANK",
    "login_actions": [
      {
        "buttons": [
          {
            "name": "buttons_login",
            "type": "SUBMIT",
            "value": "Login"
          }
        ],
        "fields": [
          {
            "label": "One Time Password",
            "name": "otp",
            "options": [],
            "placeholder": "One Time Password",
            "type": "INPUT"
          }
        ],
        "messages": [
          {
            "name": "messages_otp_body",
            "type": "BODY",
            "value": "Enter the OTP (one time password) sent to your mobile phone"
          }
        ],
        "name": "MOBILE_OTP",
        "type": "ACTION"
      }
    ],
    "login_details": {
      "secretRequired": "true",
      "secret_required": true
    },
    "login_methods": [
      {
        "id": "PASSWORD",
        "is_default_method": true,
        "login_fields": [
          {
            "key": "username",
            "name": "Username",
            "type": "text"
          },
          {
            "key": "secret",
            "name": "Memorable answer",
            "type": "password"
          },
          {
            "key": "password",
            "name": "Password",
            "type": "password"
          }
        ],
        "name": "Password",
        "status": "SUPPORTED"
      },
      {
        "id": "TOKEN_OTP",
        "is_default_method": false,
        "login_fields": [
          {
            "key": "username",
            "name": "Username",
            "type": "text"
          },
          {
            "key": "secret",
            "name": "Memorable answer",
            "type": "text"
          },
          {
            "key": "otp",
            "name": "Security Code",
            "type": "text"
          }
        ],
        "name": "Security Code",
        "status": "ALPHA"
      }
    ],
    "login_url": "https://www.services.online-banking.hsbc.com.hk/",
    "parent_institution_name": "HSBC",
    "payment_info": {
      "currencies_supported": null,
      "other_info": {
        "bank_code": "004"
      },
      "payments_supported": [
        "MANDATE"
      ]
    },
    "portal_name": "HSBC Personal Account",
    "products_supported": [
      "ACCOUNTS",
      "TRANSACTIONS",
      "STATEMENTS",
      "ACCOUNT_NUMBERS",
      "HISTORICAL_TRANSACTIONS",
      "BALANCE_HISTORY",
      "IDENTITY",
      "PAYMENTS"
    ],
    "status": "SUPPORTED",
    "status_details": null,
    "tags": [
      "real"
    ],
    "updated_at": "2022-07-19T06:47:43.855Z",
    "user_type": [
      "PERSONAL",
      "INDIVIDUAL"
    ]
  },
  {
    "color": "#FFFFFF",
    "countries": [
      "HKG",
      "SGP",
      "PHL"
    ],
    "institution_id": "testbank",
    "institution_name": "TestBank HK",
    "institution_type": "BANK",
    "login_actions": [
      {
        "buttons": [
          {
            "name": "buttons_login",
            "type": "SUBMIT",
            "value": "Login"
          }
        ],
        "fields": [
          {
            "label": "One Time Password",
            "name": "otp",
            "options": [],
            "placeholder": "One Time Password",
            "type": "INPUT"
          }
        ],
        "messages": [
          {
            "name": "messages_otp_body_testbank",
            "type": "BODY",
            "value": "Please enter the OTP. Hint: otp_1234"
          }
        ],
        "name": "MOBILE_OTP",
        "type": "ACTION"
      },
      {
        "buttons": [
          {
            "name": "buttons_send_notification",
            "type": "SUBMIT",
            "value": "Send Notification"
          }
        ],
        "fields": [
          {
            "label": "Select a device",
            "name": "device",
            "options": [],
            "placeholder": "Select a device",
            "type": "SELECT"
          }
        ],
        "messages": [
          {
            "name": "messages_device_selection_approval_title",
            "type": "BODY",
            "value": "Please select the device to send login approval request to"
          }
        ],
        "name": "DEVICE_SELECTION",
        "type": "ACTION"
      },
      {
        "buttons": [],
        "fields": [],
        "messages": [
          {
            "name": "messages_sent_to_phone",
            "type": "TITLE",
            "value": "Please approve the login request sent to your phone"
          },
          {
            "name": "messages_approval_timeout_default",
            "type": "BODY",
            "value": "You will have up to 90 seconds to approve the login request"
          }
        ],
        "name": "PUSH_SENT",
        "type": "INFO"
      },
      {
        "buttons": [],
        "fields": [],
        "messages": [
          {
            "name": "messages_sent_to_phone",
            "type": "TITLE",
            "value": "Please approve the login request sent to your phone"
          },
          {
            "name": "messages_sent_to",
            "type": "BODY",
            "value": "Please approve the login request sent to your phone"
          },
          {
            "name": "messages_device",
            "type": "HIGHLIGHT",
            "value": "<device>"
          },
          {
            "name": "messages_approval_timeout_default",
            "type": "BODY",
            "value": "You will have up to 90 seconds to approve the login request"
          }
        ],
        "name": "PUSH_SENT",
        "type": "INFO"
      }
    ],
    "login_details": {
      "infoMessage": "Use credentials: User ID = usergood | Password = datagood",
      "info_message": "Use credentials: User ID = usergood | Password = datagood"
    },
    "login_methods": [
      {
        "id": "PASSWORD",
        "is_default_method": true,
        "login_fields": [
          {
            "key": "username",
            "name": "User ID",
            "type": "text"
          },
          {
            "key": "password",
            "name": "Password",
            "type": "password"
          }
        ],
        "name": "Password",
        "status": "SUPPORTED"
      },
      {
        "id": "SECRET",
        "is_default_method": false,
        "login_fields": [
          {
            "key": "username",
            "name": "User ID",
            "type": "text"
          },
          {
            "key": "password",
            "name": "Password",
            "type": "password"
          },
          {
            "key": "secret",
            "name": "Secret",
            "type": "text"
          }
        ],
        "name": "Password with secret",
        "status": "SUPPORTED"
      },
      {
        "id": "ORGANISATION_ID",
        "is_default_method": false,
        "login_fields": [
          {
            "key": "organisationId",
            "name": "Organisation ID",
            "type": "text"
          },
          {
            "key": "username",
            "name": "User ID",
            "type": "text"
          },
          {
            "key": "password",
            "name": "Password",
            "type": "password"
          }
        ],
        "name": "Organisation Id",
        "status": "SUPPORTED"
      }
    ],
    "login_url": "https://woauth.dev.finverse.net",
    "parent_institution_name": "TEST",
    "payment_info": {
      "currencies_supported": null,
      "other_info": {},
      "payments_supported": [
        "DEBIT_AUTHORIZATION",
        "MANDATE"
      ]
    },
    "portal_name": "Test Bank Personal Account",
    "products_supported": [
      "ACCOUNTS",
      "TRANSACTIONS",
      "STATEMENTS",
      "ACCOUNT_NUMBERS",
      "IDENTITY",
      "PAYMENTS"
    ],
    "status": "SUPPORTED",
    "status_details": null,
    "tags": [
      "test"
    ],
    "updated_at": "2022-07-19T06:47:43.829Z",
    "user_type": [
      "PERSONAL",
      "INDIVIDUAL"
    ]
  }
]

{
  "code": 401,
  "error": {
    "code": "NOT_AUTHORIZED",
    "details": "Invalid bearer token",
    "error_code": "NOT_AUTHORIZED",
    "message": "Authorization failed. Please review authorization requirements in API documentation.",
    "request_id": "{unique_id}",
    "type": "API_ERROR"
  },
  "message": "Invalid bearer token"
}

{
  "error": {
    "code": 40004,
    "error_code": "CREDENTIALS_INVALID",
    "message": "<string>",
    "request_id": "<string>",
    "type": "LINKING_ERROR",
    "details": "<string>"
  }
}

Customer

Retrieve Institutions list

Retrieve list of all Institutions.

Authorization: customer_token or link_token

Optional parameters

You can use the following optional URL parameters to filter the Institutions list returned by Finverse.

Example: GET /institutions?products_supported=ACCOUNT_NUMBERS

Response fields

Full institutions array, containing a list of institutions with institution-level metadata.

login_actions (array)

(Informational) Details on dynamic login actions that may be required by the institution (e.g. 2FA). The Finverse Link UI will dynamically display any login actions.

There are two types of login actions:

* Actions which require user-input inside the linking flow, e.g. 2FA steps requiring a code-input like SMS OTP or token-based OTP. These are labeled as type = ACTION.
* Actions which require the user to take action outside the linking flow, e.g. 2FA steps like push notification approval (in the user’s bank app). In these cases the action flow provides an informational message to the user to complete the action step. These are labeled as type = INFO.

buttons (array)

For a given login_action, describes the user-facing buttons to display to enable the user to interact with the requested action. Only used for type = ACTION.

fields (array)

For a given login_action, describes the fields which require user-input to enable the user to interact with the requested action. Only used for type = ACTION.

options (array)

For a field with type= SELECT, lists the possible options, from which user needs to select one value.

messages (array)

For a given login_action, describes the user-facing message(s) to inform the user about what action to take.

login_details (object)

Additional details on login requirements for each institution.

login_methods (array)

Additional details on login methods, containing login_fields for each institution.

login_fields (array)

For a given login_method, describes the login fields required to authenticate with the institution. These represent the minimum login fields required for all users. Additional fields may be required for some users (those will be dynamically displayed in Finverse Link).

payment_info (object)

Additional details on payment methods supported.

GET

institutions

Retrieve Institutions list

curl --request GET \
  --url https://api.prod.finverse.net/institutions \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.prod.finverse.net/institutions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.prod.finverse.net/institutions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prod.finverse.net/institutions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.prod.finverse.net/institutions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

[
  {
    "color": "#FFFFFF",
    "countries": [
      "HKG"
    ],
    "institution_id": "hsbc-hk",
    "institution_name": "HSBC (HK) - Personal",
    "institution_type": "BANK",
    "login_actions": [
      {
        "buttons": [
          {
            "name": "buttons_login",
            "type": "SUBMIT",
            "value": "Login"
          }
        ],
        "fields": [
          {
            "label": "One Time Password",
            "name": "otp",
            "options": [],
            "placeholder": "One Time Password",
            "type": "INPUT"
          }
        ],
        "messages": [
          {
            "name": "messages_otp_body",
            "type": "BODY",
            "value": "Enter the OTP (one time password) sent to your mobile phone"
          }
        ],
        "name": "MOBILE_OTP",
        "type": "ACTION"
      }
    ],
    "login_details": {
      "secretRequired": "true",
      "secret_required": true
    },
    "login_methods": [
      {
        "id": "PASSWORD",
        "is_default_method": true,
        "login_fields": [
          {
            "key": "username",
            "name": "Username",
            "type": "text"
          },
          {
            "key": "secret",
            "name": "Memorable answer",
            "type": "password"
          },
          {
            "key": "password",
            "name": "Password",
            "type": "password"
          }
        ],
        "name": "Password",
        "status": "SUPPORTED"
      },
      {
        "id": "TOKEN_OTP",
        "is_default_method": false,
        "login_fields": [
          {
            "key": "username",
            "name": "Username",
            "type": "text"
          },
          {
            "key": "secret",
            "name": "Memorable answer",
            "type": "text"
          },
          {
            "key": "otp",
            "name": "Security Code",
            "type": "text"
          }
        ],
        "name": "Security Code",
        "status": "ALPHA"
      }
    ],
    "login_url": "https://www.services.online-banking.hsbc.com.hk/",
    "parent_institution_name": "HSBC",
    "payment_info": {
      "currencies_supported": null,
      "other_info": {
        "bank_code": "004"
      },
      "payments_supported": [
        "MANDATE"
      ]
    },
    "portal_name": "HSBC Personal Account",
    "products_supported": [
      "ACCOUNTS",
      "TRANSACTIONS",
      "STATEMENTS",
      "ACCOUNT_NUMBERS",
      "HISTORICAL_TRANSACTIONS",
      "BALANCE_HISTORY",
      "IDENTITY",
      "PAYMENTS"
    ],
    "status": "SUPPORTED",
    "status_details": null,
    "tags": [
      "real"
    ],
    "updated_at": "2022-07-19T06:47:43.855Z",
    "user_type": [
      "PERSONAL",
      "INDIVIDUAL"
    ]
  },
  {
    "color": "#FFFFFF",
    "countries": [
      "HKG",
      "SGP",
      "PHL"
    ],
    "institution_id": "testbank",
    "institution_name": "TestBank HK",
    "institution_type": "BANK",
    "login_actions": [
      {
        "buttons": [
          {
            "name": "buttons_login",
            "type": "SUBMIT",
            "value": "Login"
          }
        ],
        "fields": [
          {
            "label": "One Time Password",
            "name": "otp",
            "options": [],
            "placeholder": "One Time Password",
            "type": "INPUT"
          }
        ],
        "messages": [
          {
            "name": "messages_otp_body_testbank",
            "type": "BODY",
            "value": "Please enter the OTP. Hint: otp_1234"
          }
        ],
        "name": "MOBILE_OTP",
        "type": "ACTION"
      },
      {
        "buttons": [
          {
            "name": "buttons_send_notification",
            "type": "SUBMIT",
            "value": "Send Notification"
          }
        ],
        "fields": [
          {
            "label": "Select a device",
            "name": "device",
            "options": [],
            "placeholder": "Select a device",
            "type": "SELECT"
          }
        ],
        "messages": [
          {
            "name": "messages_device_selection_approval_title",
            "type": "BODY",
            "value": "Please select the device to send login approval request to"
          }
        ],
        "name": "DEVICE_SELECTION",
        "type": "ACTION"
      },
      {
        "buttons": [],
        "fields": [],
        "messages": [
          {
            "name": "messages_sent_to_phone",
            "type": "TITLE",
            "value": "Please approve the login request sent to your phone"
          },
          {
            "name": "messages_approval_timeout_default",
            "type": "BODY",
            "value": "You will have up to 90 seconds to approve the login request"
          }
        ],
        "name": "PUSH_SENT",
        "type": "INFO"
      },
      {
        "buttons": [],
        "fields": [],
        "messages": [
          {
            "name": "messages_sent_to_phone",
            "type": "TITLE",
            "value": "Please approve the login request sent to your phone"
          },
          {
            "name": "messages_sent_to",
            "type": "BODY",
            "value": "Please approve the login request sent to your phone"
          },
          {
            "name": "messages_device",
            "type": "HIGHLIGHT",
            "value": "<device>"
          },
          {
            "name": "messages_approval_timeout_default",
            "type": "BODY",
            "value": "You will have up to 90 seconds to approve the login request"
          }
        ],
        "name": "PUSH_SENT",
        "type": "INFO"
      }
    ],
    "login_details": {
      "infoMessage": "Use credentials: User ID = usergood | Password = datagood",
      "info_message": "Use credentials: User ID = usergood | Password = datagood"
    },
    "login_methods": [
      {
        "id": "PASSWORD",
        "is_default_method": true,
        "login_fields": [
          {
            "key": "username",
            "name": "User ID",
            "type": "text"
          },
          {
            "key": "password",
            "name": "Password",
            "type": "password"
          }
        ],
        "name": "Password",
        "status": "SUPPORTED"
      },
      {
        "id": "SECRET",
        "is_default_method": false,
        "login_fields": [
          {
            "key": "username",
            "name": "User ID",
            "type": "text"
          },
          {
            "key": "password",
            "name": "Password",
            "type": "password"
          },
          {
            "key": "secret",
            "name": "Secret",
            "type": "text"
          }
        ],
        "name": "Password with secret",
        "status": "SUPPORTED"
      },
      {
        "id": "ORGANISATION_ID",
        "is_default_method": false,
        "login_fields": [
          {
            "key": "organisationId",
            "name": "Organisation ID",
            "type": "text"
          },
          {
            "key": "username",
            "name": "User ID",
            "type": "text"
          },
          {
            "key": "password",
            "name": "Password",
            "type": "password"
          }
        ],
        "name": "Organisation Id",
        "status": "SUPPORTED"
      }
    ],
    "login_url": "https://woauth.dev.finverse.net",
    "parent_institution_name": "TEST",
    "payment_info": {
      "currencies_supported": null,
      "other_info": {},
      "payments_supported": [
        "DEBIT_AUTHORIZATION",
        "MANDATE"
      ]
    },
    "portal_name": "Test Bank Personal Account",
    "products_supported": [
      "ACCOUNTS",
      "TRANSACTIONS",
      "STATEMENTS",
      "ACCOUNT_NUMBERS",
      "IDENTITY",
      "PAYMENTS"
    ],
    "status": "SUPPORTED",
    "status_details": null,
    "tags": [
      "test"
    ],
    "updated_at": "2022-07-19T06:47:43.829Z",
    "user_type": [
      "PERSONAL",
      "INDIVIDUAL"
    ]
  }
]

{
  "code": 401,
  "error": {
    "code": "NOT_AUTHORIZED",
    "details": "Invalid bearer token",
    "error_code": "NOT_AUTHORIZED",
    "message": "Authorization failed. Please review authorization requirements in API documentation.",
    "request_id": "{unique_id}",
    "type": "API_ERROR"
  },
  "message": "Invalid bearer token"
}

{
  "error": {
    "code": 40004,
    "error_code": "CREDENTIALS_INVALID",
    "message": "<string>",
    "request_id": "<string>",
    "type": "LINKING_ERROR",
    "details": "<string>"
  }
}

Authorizations

Authorization

string

header

required

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

Query Parameters

country

string

(Deprecated) The country the institution belongs to

countries

string[]

The countries the institution belongs to

products_supported

string

The products that this institution supports

institution_type

enum<string>

The type of institution

Available options:

BANK,

WALLET,

TEST

Response

Successful

countries

string[]

required

Example:

["HKG"]

institution_id

string

required

Example:

123

institution_name

string

required

Example:

"Mock Bank"

institution_type

enum<string>

required

Available options:

BANK,

WALLET,

TEST

Example:

"BANK"

products_supported

enum<string>[]

required

Available options:

ACCOUNTS,

TRANSACTIONS,

STATEMENTS,

ACCOUNT_NUMBERS,

IDENTITY,

AUTO_DEBIT_SETUP

Example:

[
  "ACCOUNTS",
  "TRANSACTIONS",
  "STATEMENTS",
  "ACCOUNT_NUMBERS",
  "IDENTITY",
  "AUTO_DEBIT_SETUP"
]

status

enum<string>

required

Available options:

SUPPORTED,

ALPHA,

BETA

Example:

"SUPPORTED"

user_type

enum<string>[]

required

Available options:

PERSONAL,

INDIVIDUAL,

BUSINESS

color

string

Example:

"#FFFFFF"

Show child attributes

Example:

"https://example.com/login"

parent_institution_name

string

Example:

"Parent Mock Bank"

payment_info

object

Show child attributes

portal_name

string

Example:

"Personal Internet Banking"

status_details

object

Example:

{}