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 PSUClosedPayment 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:

{

"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:

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
bics* Passes in a list of banks matching a full or partial Bank Identification Code. The BIC is composed of a 4-character bank code, a 2-character country code, a 2-character location code and an optional 3-character branch code. Length can be 8 or 11 characters get /banks?bics=DEUTITMMXXX&bics=BKTRGB2LXXX

example fetches Deutsche Bank S.P.A. – Milano and
Deutsche Bank Trust Company Americas, London Branch

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") get /banks?search=buda

example returns all banks with names beginning with "buda" plus all banks with a BIC string beginning with "buda"

openBankingStandard API standard adopted/supported by the bank
  • NextgenPsd2
  • OBIE
  • Token
provider Open Banking SaaSClosedSoftware 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

 

* The search parameter works to find partial string matches for name and bics. Using bics or ids as the query parameter will return exact (full string) matches only. bics must have a string length of 8 or 11. Using a different length for a bics query will throw an error. bics and ids as query parameters can be used multiple times, up to 1000. Please note that the BIC for some banks may not yet have been updated in the system.

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:

        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 STETClosedCreated 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:

mandatory_fields {

     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 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 AISClosedAccount Information Service – supports TPP secure access to customer accounts and data, but only with the bank-verified consent of the customer. or PISClosedPayment 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 PINClosedPersonal 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:

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