Filtering Banks for User Selection

In order to grant you, the PISPClosedPayment Initiation Service Provider – a TPP that initiates a payment order at the request of the payment service user with respect to a payment account held at another payment service provider., the necessary permissions related to one or more user-selected bank accounts, the customer will need to choose a Token-connected bank in which those accounts are held. This bank selection process entails narrowing the complete list of Token-connected banks to the desired country (where the bank is located), and then filtering this smaller list by the open banking (PISClosedPayment Initiation Service – with the consent of the end-user, initiates a payment from a user-held account upon user authentication.) feature(s) needed — features that are in fact supported by the bank. The result is an even smaller list (subset) of Token-connected banks supporting the feature criteria specified, a list which is then displayed to the customer for selection. Of course, if the customer's bank isn't in the list, the payment initiation request cannot go forward.

To present the user with an appropriate list of banks from which to select, you have two options:

  1. Redirect the user to the bank selection screen in the Token web app
  2. Display your own bank selection UIClosedUser Interface – at the most basic level, this is the series of screens, pages, and visual elements—like buttons and icons—that enable a user to interact with your product or service.

The first method is invoked by default. It allows the user to search for their bank by entering the bank name or other bank identifier. The second leverages the SDK's getBanks method to retrieve a list of bank objects. Employing getBanks gives you the chance filter-out the banks that support the features you need before displaying them to the user for selection.

Using Token's Bank Selection Screens

If you choose to employ Token's web app for bank selection (pictured below, hover to enlarge), just submit the token request and construct the redirect URL with the requestId returned in the callback, then direct your front-end to visit it.

There are a couple of ways to accomplish this.

  1. Send an HTTP POST call to your backend to initiate the token request and redirect using a HTTP 302ClosedAn HTTP response with this status code will additionally provide a URL in the header field Location. This is an invitation to the user agent (i.e., a web browser) to make a second, otherwise identical, request to the new URL specified in the location field. The end result is a redirection to the new URL..
  2. Create a Token button for your UI that, when clicked, redirects the user to the Token web app or launches a pop-up window in the user's browser. Use token.createRequest to automatically choose the best option based on the user's device (laptop/desktop vs. smartphone/tablet).

You can learn more about these redirect options for bank selection in the discussion on redirecting the user to authenticate.

Using the getBanks Method

As introduced above, the SDK's getBanks method is used to retrieve a list of Token-connected Bank objects matching your filtering criteria with respect to where the bank is located and the open banking features it supports. Based on the results, you can then perform additional filtering within your environment before presenting the finalised list to the customer for selection. Once the selection is made, you'll need to include the Bank ID of the chosen bank in your access token request.

Bank Object

Let's begin with the basic Bank object. It contains all the open banking information available for a single Token-connected bank. The PISClosedPayment Initiation Service – with the consent of the end-user, initiates a payment from a user-held account upon user authentication.-related fields and attributes in the Bank object are listed in the following table.

PIS-related Fields in the Bank object
Field Description
country ISO 3166-1 Alpha 2 code in upper case, identifying the country in which the bank is located
full_logo_uri Link to full-size brand icon (logo) for the bank
id ISO 9362 business identifier code (BICClosedBank Identifier Code – a unique identifier for a specific financial institution. A 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.) for the bank (also known as SWIFTClosedSociety for Worldwide Interbank Financial Telecommunication – provides a secure network allowing more than 10,000 financial institutions in 212 different countries to send and receive information about financial transactions to each other. As broadly used as SWIFT is, keep in mind that it is only a messaging system; SWIFT does not hold any funds or securities, nor does it manage client accounts.-BIC, BIC, SWIFT ID or SWIFT code)).
identifier Additional Bank ID (e.g., BLZClosedBankleitzah – an 8 digit code used for money transfers with domestic banks in Germany. The code is used to identify an individual branch of a financial organization in Germany. For international monetary transfers, a SWIFT Code is used with Bankleitzahl and Account Number. for German banks); optional
logo_uri Small, square bank avatar icon
name Name of the bank (e.g., "First National Bank")
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). provider (e.g.,Token, FinApi)
requires_one_step_payment Bank supports immediate redemption of transfers only ; no TPP token redemption supported
supported_transfer_destination_types List of transfer destination types supported by the bank (e.g., SEPAClosedSingle Euro Payments Area – a payments system created by the European Union (EU) which harmonizes the way cashless payments transact between euro countries. European consumers, businesses, and government agents who make payments by direct debit, instant credit transfer, and through credit transfers use the SEPA architecture. The single euro payment area is approved and regulated by the European Commission. SEPA currently includes 36 members. It encompasses the 28 EU member states along with Iceland, Norway, Liechtenstein, Switzerland, Andorra, Vatican City, Monaco and San Marino. The single euro payment area remains an ongoing, collaborative process between these parties. SEPA is in the process of harmonizing rules regarding mobile and online payments., ELIXIRClosedA payments system that ensures electronic interbank settlement in Poland. Transactions directed to the system are settled within one of three Elixir sessions held each business day and closed on the same day in the National Bank of Poland's SORBNET2 system, which guarantees interbank transfer of funds., etc.)
supports_bulk_transfer Bank supports a group of payments (e.g., in a file) paid to multiple creditor accounts from the same debtor account, on the same date, with the same currency and through the same payment request.
supports_guest_checkout Bank supports one-time payment by an account holder who is not a registered member in the Token ecosystem
supports_receive_payment Bank supports transfers made to the one of its accounts initiated on behalf of the account holder by a TPP
supports_scheduled_payment Bank supports future-dated payments
supports_send_payment Bank supports TPP payment initiation
supports_standing_order Bank supports recurring payments based on a start date, end date, and frequency

These fields constitute the supported features you can specify in the bankFeatures parameter of a getBanks call for payment initiation.

Additional Filtering Criteria

In addition to bankFeatures, the getBanks method also specifies the parameters listed in the next table.

Fields in getBanks method
Field Description
bankIds Returns banks with a bank id matching any of the bank IDs you provide in this field, up to a maximum of 1,000 banks
search Returns banks with a name or identifier containing this case-sensitive search string
country Returns banks located in a country matching any one of the country codes (ISO 3166-1 Alpha 2) included in this field
page Returns only the paged results of the specified page; default = 1
perPage Maximum number of records to return per page, up to a maximum of 200; default = 200
sort Sorts collected results by bank name in ascending alpha order
provider Returns banks using the specified provider only — FinApi, Token (case-sensitive)
bankFeatures List of supported features desired (see Bank object above)

Here's how to use the getBanks method:

/**

 * Returns a list of token-enabled banks.

 *

 * @param bankIds If specified, return banks whose 'id' matches any one of the given ids

 * (case-insensitive). Can be at most 1000.

 * @param search If specified, return banks whose 'name' or 'identifier' contains the given

 * search string (case-insensitive)

 * @param country If specified, return banks whose 'country' matches the given ISO 3166-1

 * alpha-2 country code (case-insensitive)

 * @param page Result page to retrieve. Default to 1 if not specified.

 * @param perPage Maximum number of records per page. Can be at most 200. Default to 200

 * if not specified.

 * @param sort The key to sort the results. Could be one of: name, provider and country.

 * Defaults to name if not specified.

 * @param provider If specified, return banks whose 'provider' matches the given provider

 * (case insensitive).

 * @return a list of banks

*/

public List<Bank> getBanksBlocking(

        @Nullable List<String> bankIds,

        @Nullable String search,

        @Nullable String country,

        @Nullable Integer page,

        @Nullable Integer perPage,

        @Nullable String sort,

        @Nullable String provider) {

    return getBanks(bankIds, search, country, page, perPage, sort, provider).blockingSingle();

}

Upon obtaining the user-selected bankId from your UI, be sure to include it in the TokenRequest with setBankId() as discussed in Creating an Transfer Token Request. But, before diving into the details of building out the token request, let's first take a look at the overall request-response flow for account information between the customer, the TPP, and the bank through the Token CloudClosedFunctionality, data and resources running on physical and virtual servers maintained and controlled by Token, and accessed via an Internet connection..