Bank Selection using GET /banks (APIv1)

After you successfully register with Token as a TPP, you're ready to get started with API integration. Before initiating a request to a Token-connected bank, you'll need to get the list of banks in the desired 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. As defined in Swagger Object and field Definitions, 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.

Hence, in response to a successful request — for example, GET /banks?ids=gold — the payload returned in the response will take these forms:

You can add query parameters to filter the results of your GET /banks request. Field descriptions and usage as a query parameter are listed in the following table.

Mandatory fields are entirely bank-dependent and must therefore be handled on a bank-by-bank basis, as discussed next.

Mandatory Fields

A mandatoryFields object is a property for a specific bank included in the banks object within a GET /banks response from Token (see example above). It describes those fields which 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 mandatoryFields. Consequently, fields required for all banks (e.g., refId) or which are always optional (e.g., description) are not part of mandatoryFields.

As applicable, the mandatoryFields object is organized by service (e.g., pis, ais) and “instrument” (e.g., transfer, standingOrder, and so forth.). Each payment instrument is further organized according to the bank-adopted API standard — NextGenPsd2Common API standard for PSD2 developed by the Berlin Group to create uniform and interoperable communications between banks and TPPs., PolishApiOpen Banking API standard adopted by banks in Poland to enable TPP access to payment accounts in accordance with PSD2 rules and regulations., 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. or Cma9As part of the Open Banking initiative, the CMA9 are the nine largest banks in the UK as determined by the Competition and Markets Authority (CMA). The CMA is an independent department of the UK government chartered to promote market competition and fairness, and reduce any harmful monopolies. — for domestic and international transfers to create the following general structure:

When added within the bank object in the response example above, a particular bank's mandatoryFields might be populated like this:

See List of Possible Mandatory Fields for the complete list.

Mapping mandatoryFields from a GET /banks Response to Payment Request Fields

Certain mandatoryFields will need to be provided by the user, whilst others must be provided by the TPP. If the TPP uses the Token webapp, mandatoryFields not included in the token request will be captured from the user by the webapp. If the webapp is not used for showing initial consent, the TPP must ensure that bank-specific mandatoryFields are included in the token request when initiating a payment to the given bank.

Hence, if a user’s account is on the debtor side, the debtor name and debtor account details need to be captured from the user. If the beneficiary in the transaction is the TPP, the TPP should specify its account information on the creditor (beneficiary) side.

The following table lists the mapping from the respective mandatory field in the bank's GET /banks response call to the expected information required in a subsequent transfer request:

Mapping mandatoryFields to Request Values

Mandatory Field	Maps to Info in Transfer Request	When Webapp Used	When Webapp NOT Used
transfer_body.instructions. source.customer_data.legal_names	Debtor/Payer Name	TPP must provide only if TPP is the payer	TPP must provide; if TPP is not the payer, TPP must capture this information from the payer
transfer_body.instructions. source.account_identifier	Debtor Account Number	TPP must provide only if TPP is the payer	TPP must provide; if TPP is not the payer, TPP must capture this information from the payer
transfer_body.instructions. source.bic	Debtor BIC	TPP must provide only if TPP is the payer	TPP must provide; if TPP is not the payer, TPP must capture this information from the payer
transfer_body.instructions. transfer_destinations.customer_data.legal_names	Creditor/Beneficiary Name	TPP must provide only if TPP is the transaction beneficiary (payee)	TPP must provide; if TPP is not the payer, TPP must capture this information from the payer
transfer_body.instructions. transfer_destinations.account_identifier	Creditor Account Number	TPP must provide; if TPP is not the payee, TPP must capture this information from the payee	TPP must provide; if TPP is not the payee, TPP must capture this information from the payee
transfer_body.instructions. transfer_destinations.bic	Creditor BIC	TPP must provide; if TPP is not the payee, TPP must capture this information from the payee	TPP must provide; if TPP is not the payee, TPP must capture this information from the payee
transfer_body.instructions.metadata. provider_transfer_metadata. stet_transfer_metadata.beneficiary.creditor_agent	Creditor Agent information; required by STET-based banks	TPP must provide only if TPP is the transaction beneficiary (payee)	TPP must provide; if TPP is not the payee, TPP must capture this information from the beneficiary
transfer_body.instructions.metadata. provider_transfer_metadata. stet_transfer_metadata.payment_type_information	Payment Type Information; required by STET-based banks	TPP must provide	TPP must provide
transfer_body.instructions.metadata. provider_transfer_metadata. stet_transfer_metadata.debtor_agent	Debtor Agent Information; required by STET-based banks	TPP must provide	TPP must provide
transfer_body.instructions.metadata. provider_transfer_metadata. stet_transfer_metadata.end_to_end_id	End-to-end identifier; required by STET-based banks	TPP must provide	TPP must provide
transfer_body.instructions.metadata. provider_transfer_metadata. stet_transfer_metadata.execution_rule	Execution Rule; required by STET-based banks	TPP must provide	TPP must provide
transfer_body.instructions.metadata. provider_transfer_metadata. polish_api_transfer_metadata.delivery_mode	Delivery Mode; PolishApi-based banks only, where applicable	TPP must provide	TPP must provide
transfer_body.instructions.metadata. provider_transfer_metadata. polish_api_transfer_metadata.hold	Hold; PolishApi-based banks only, where applicable	TPP must provide	TPP must provide
transfer_body.instructions.metadata. provider_transfer_metadata. next_gen_psd2_metadata.end_to_end_identification	End-to-end identifier; NextGenPsd2-based banks only	TPP must provide	TPP must provide
transfer_body.instructions.metadata. provider_transfer_metadata. next_gen_psd2_metadata.remittance_information_structured	Remittance Information Structured; NextGenPsd2-based banks only	TPP must provide	TPP must provide
transfer_body.instructions.metadata. provider_transfer_metadata. next_gen_psd2_ metadata.creditor_agent	Creditor Agent information; NextGenPsd2-based banks only	TPP must provide only if TPP is the transaction beneficiary (payee)	TPP must provide; if TPP is not the payee, TPP must capture this information from the payee
transfer_body.instructions.metadata. provider_transfer_metadata. next_gen_psd2_ metadata.creditor_agent_name	Creditor Agent Name; NextGenPsd2-based banks only	TPP must provide only if TPP is the transaction beneficiary (payee)	TPP must provide; if TPP is not the payee, TPP must capture this information from the payee
transfer_body.instructions.metadata. provider_transfer_metadata. cma9_transfer_ metadata.instruction_identification	Instruction Identification; OBIE-based banks only	TPP must provide	TPP must provide
transfer_body.instructions.metadata. provider_transfer_metadata. cma9_transfer_metadata.end_to_end_identification	End-to-end identifier; OBIE-based banks only	TPP must provide	TPP must provide
transfer_body.instructions.metadata. provider_transfer_metadata. cma9_transfer_metadata.risk	Risk information; OBIE-based banks only	TPP must provide	TPP must provide

Payment Initiation Flow with mandatoryFields using Token Webapp

If you're using the Token webapp, the recommended PISPayment Initiation Service – with the consent of the end-user, initiates a payment from a user-held account upon user authentication. flow with mandatoryFields looks like this (hover to enlarge):

For more on 1-step payment versus 2-step, see Transmitting PSU Consent, as well as each supported payment type (Single Immediate, Future-dated, or Standing Order).

Payment Initiation Flow with mandatoryFields without using Token Webapp

If you're using your own licence but you're not using the Token webapp, the recommended PIS flow with mandatoryFields looks like this:

Again, see Transmitting PSU Consent, as well as each supported payment type (Single Immediate, Future-dated, or Standing Order) for more on 1-step payment versus 2-step.

Search and Sort

With the filtered 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?field=search-string 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.

Bank-dependent Field Formatting

The bank's response may include a fieldsFormatInformation object array describing specific formatting constraints imposed by the bank. This typically involves which special characters are allowed, if any, and/or other formats, such as all caps, allowable numerals, etc.

The response syntax for fieldsFormatInformation will look something like this (see sample response for placement), in which name identifies the field and path is its location vis-à-vis object.field) within the requestPayload:

In the example above, the constraint field limits what can be included in the field specified by name; in this case, description in the token requestPayload for the given bank, which allows A through Z, a through z, 0 through 9, question mark, colon, open parenthesis, close parenthesis, period, forward slash, comma, single quotation mark, plus sign, back slash, and s. All other characters or character codes are disallowed and, if included in the description field of a request submitted to this particular bank, an exception will be thrown.

See https://regexr.com/3cr6f to conveniently translate specific expressions, when necessary. See also the example request in Single Immediate Payment for the placement of description in the token request and/or the swagger definition for the POST /token-requests endpoint.

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)