Bank Selection using GET /banks

After you successfully register with Token as a TPP, you're ready to get started with API integration. The first step, before initiating a request to a Token-connected bank, is getting the list of banks in a particular country that support the features you need to access — or, more specifically, the features your PSUPayment Services User – an individual person or legal business entity making use of an Open Banking service as a payee, payer or both. is requesting, presuming the PSU is an authorized account holder with a Token-connected bank. A GET /banks call filters the list of Token-connected banks based on your selection criteria with respect to bank location and bank-supported features.

Base URLs

See Base URLs.

Headers

See Common Request Headers.

Selection Criteria

As you'll find in the developer dashboard's Swagger reference, there are numerous filtering criteria you can configure to narrow your query. You can request a list of all banks supporting requested features or all banks in a specified country or countries supporting requested features. Then, upon identifying the bank or banks meeting your service request criteria, you can display the results for PSU selection. Obviously, if no matches are found, you can display that result to the user, as well, in accordance with your particular UI conventions.

In response to a successful request, the typical GET /banks payload takes this form:

Along with the bank's authorizationMetadata (above in red), the list of Token-connected banks matching the requested filtering criteria specifies the following essentials:

Fields in the Bank object

Field	Description	Example Values
bankGroup	Group name if the bank is part of a group	Credit Agricole Credit du Nord
countries	Passes in a list of countries by ISO 3166-1 Alpha 2 code in upper case; only banks located in these countries are returned	get /banks?countries=FR&countries=GB
credentialFields	Fields required as part of initial authorisation at the bank	IBANInternational Bank Account Number – a number attached to all bank accounts in the EU countries, plus Norway, Switzerland, Liechtenstein and Hungary. The IBAN is made up of a code identifying the country to which the account belongs, the account holder's bank, and the account number itself. (e.g., AT483200000012345864)
ids	Passes in a list of bank ids for which details are required	get /banks?ids=ob-barclays&ids=ob-lloyds
logoUri	URL to the bank's approved logo
mandatoryFields	Specific fields required by this particular bank for the request to be successful
memberId	Member ID associated with a list of banks configured with the member's licence; returns only banks configured with the member's licence	get /banks?memberId=m:213xyzabc3453434
name	Name of the bank (e.g., "First National Bank")	K&H Bank Barclays
openBankingStandard	API standard adopted/supported by the bank	NextgenPsd2 OBIE Token
provider	Open Banking SaaSSoftware as a Service (SaaS) – a software distribution model in which a third-party provider hosts applications and makes them available to customers over the Internet. SaaS is one of three main categories of cloud computing, alongside infrastructure as a service (IaaS) and platform as a service (PaaS). adapter or provider (e.g.,Token, FinApi)	CMA9 Token NextgenPsd2 Sparkasse
supportedTransferDestinationTypes	Payment methods supported by the bank	See Beneficiary Account Details
Bank-supported Features
requiresOneStepPayment	Flow adopted by bank - One Step or Two Step. If Two Step, value is set to Transfer	get /banks?countries=FR&countries=GB&bank_features.requires_one_step_payment.value=true
supportsFundsConfirmation	If set to true. supports confirmation of available funds	get /banks?countries=FR&countries=GB&bank_features.supports_funds_confirmation.value=true
supportsInformation	If set to true, AIS is supported	get /banks?countries=FR&countries=GB&bank_features.supports_information.value=true
supportsScheduledPayment	If set to true, bank supports future-dated payments	get /banks?countries=FR&countries=GB&bank_features.supports_schedule_payment.value=true
supportsSendPayment	If set to true, single immediate payment is supported	get /banks?countries=FR&countries=GB&bank_features.supports_send_payment.value=true
supportsStandingOrder	If set to true, bank supports standing order for recurring payment	get /banks?countries=FR&countries=GB&bank_features.supports_standing_order.value=true
supportsTransactionsDateFilter	If set to true, supports filtering transactions by date range	get /banks?countries=FR&countries=GB&bank_features.transactions_date_filter.value=true

Mandatory Token Request Pass-ins

The authorizationMetadata returned in a GET /banks response must be included in your token request payload, mapped to the bank-dependent key-value fields. The purpose of these fields is to capture additional information from the user for initial authorization by the bank, thereby allowing the user to proceed with providing consent for the initiation request.

credentialFields specify what the bank requires the TPP to pass to it for user authentication in the token request.

A mandatory_fields object is a property for a specific bank (listed in banks) within the GET /banks response. It describes which fields must be populated for the given bank when initiating payment or requesting account access. Only fields specifically required by the source bank, rather than fields more broadly required by all banks, will appear in mandatory_fields. Consequently, fields always required for all banks (e.g., refId) or always optional (e.g., description) will not appear in mandatory_fields.

This mandatory_fields object is further subdivided into “instruments” (i.e., transfer, standing order, account access). Payment instruments may be further segregated by domestic versus international to create the following general structure:

For instance, nested within a particular instrument for a specific-bank, mandatory fields might be:

In which case, debtor-account (number), beneficiary-name (payee), and delivery-mode (for the Polish API standard) must be populated in token requests for this particular bank, but debtor-name is not required. Another bank may have different mandatory fields or none at all.

For a bank that has adopted the STETCreated according to the new Payment Services Directive (PSD2), this API aims to provide a secure and easy-to-use set of services to be implemented by European ASPSPs. standard, the mandatory_fields object might be populated like this:

See Mandatory Fields for the complete list.

Search and Sort

With this information in hand (i.e., available within your processing environment), you can optionally perform additional internal filtering before displaying the results to the PSU for final selection. However, when retrieving the list of banks for which search text is provided in a GET /banks() call, an alphabetical sort of search results, if specified in the call, is applied to the search results before they are returned to the caller. This makes applying additional sort criteria to the search results returned redundant and therefore unnecessary.

Authorisation Models

When users are redirected to a bank to authorise a payment or authorise access to their account(s), they are typically asked to login before proceeding to accept or decline consent for the TPP's AISAccount Information Service – supports TPP secure access to customer accounts and data, but only with the bank-verified consent of the customer. or PISPayment Initiation Service – with the consent of the end-user, initiates a payment from a user-held account upon user authentication. request. Certain banks, however, expect the TPP to capture this information from the user before the user is redirected to the bank. In some cases, this interaction can be a series of steps, with each succeeding step dependent on the value entered by the user in the previous step. For example, depending on the value input for username and password, the user might need to complete further authentication on their mobile device or enter another PINPersonal Identification Number – a security code for verifying a customer-user's identity. already in the user's possession.

For user-selected banks requiring the capture of authentication information prior to redirection to the bank for consent, the TPP is furnished with the initial user credentials in the response to its GET /banks call. A user ID is typically required as the first step in the credentials exchange. Should the bank require additional user verification, the respective fields are made available to the TPP (in the background) so it can capture the additional information from the user. The TPP then sends the captured fields back to the bank (through Token, again in the background). Iterations of this exchange continue to occur until all necessary steps to complete user authentication at the bank are complete; at which point the user is taken to the bank's consent page.

Call Variants

Variants on the GET /banks call include:

• GET /banks/countries – to get the list of countries in which Token-connected banks are located
• GET /banks/{bankId}/info – to get bank information for a specific Token-connected bank
• GET /banks/{bankId}/token-requests/{tokenRequestId}/url – to get the authorisation URLUniform Resource Locator (aka web address) – specifies a location on a computer network and a mechanism for retrieving it. of a specific Token-connected bank. Prerequisite is a successful token request that produces a valid tokenRequestId.

Upon user selection of a bank, the corresponding service flows listed next can be appropriately implemented.

• Account Information Service (AIS)
• Payment Initiation Service (PIS)
• Card-based Payment Instrument Issuer service (CBPII)