Bank Selection using GET /banks
After you successfully register with Token as a TPP, you're ready to get started with API integration. Payment 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.
Base URLs
See Base URLs.
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:
{
"banks"
: [
{
"authorizationMetadata"
: [
{
"description"
: "string"
,
"name"
: "string"
},
],
"bankGroup"
: "string"
,
"countries"
: [
"string"
],
"country"
: "string"
,
"credentialFields"
: [
{
"description"
: "string"
,
"displayName"
: "string"
,
"id"
: "string"
,
"options"
: [
"string"
],
"password"
: true
}
"id"
: "pa-alior"
,
"name"
: "Alior Bank"
,
"supportsInformation"
: true
,
"requiresOneStepPayment
: false
.
"supportsSendPayment"
: true
,
"provider"
: "PolishAPI"
,
"country"
: "PL"
,
"supportsScheduledPayment"
: true
,
"supportsStandingOrder"
: true
,
},
Along with the bank's authorizationMetadata (above in red), the list of Token-connected banks matching the requested filtering criteria specifies the following essentials:
Field | Description | Example Values |
---|---|---|
bankGroup | Group name if the bank is part of a group |
|
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 | |
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") |
|
openBankingStandard | API standard adopted/supported by the bank |
|
provider | Open Banking SaaS![]() |
|
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
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:
debtor-account: true
debtor-name: false
beneficiary-name: true
polishApi {
delivery-mode: true
}
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:
{
transfer
{
domestic
{
fields
: ["transfer_body.instructions.transfer_destinations.customer_data.legal_names"]
stet_fields
: ["transfer_body.instructions.metadata.provider_transfer_metadata.stet_transfer_metadata.beneficiary.creditor_agent"]
},
international
{
fields
: ["transfer_body.instructions.transfer_destinations.customer_data.legal_names"]
stet_fields
: ["transfer_body.instructions.metadata.provider_transfer_metadata.stet_transfer_metadata.beneficiary.creditor_agent"]
}
}, standing_order
{
domestic
{
fields
: ["standing_order_body.instructions.transfer_destinations.customer_data.legal_names"]
stet_fields
: ["standing_order_body.instructions.metadata.provider_standing_order_metadata.stet_standing_order_metadata.beneficiary.creditor_agent"]
},
international
{
fields
: ["standing_order_body.instructions.transfer_destinations.customer_data.legal_names"]
stet_fields
: ["standing_order_body.instructions.metadata.provider_standing_order_metadata.stet_standing_order_metadata.beneficiary.creditor_agent"]
}
}
}
Careful: The mandatory-fields for a provider bank within the GET /banks response are specific to that bank and are required in token requests to that bank for the given instrument. Be sure to populate all bank-specific mandatory fields in your token request or the request will be rejected.
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 PIS
Payment 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 PIN
Personal 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 URL
Uniform 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.