Filtering Banks for User Selection
In order to grant you, the PISP, the necessary permissions related to one or more user-selected bank accounts, the customer will need to choose a Token.io-connected bank in which those accounts are held. This bank selection process entails narrowing the complete list of Token.io-connected banks to the desired country (where the bank is located), and then filtering this smaller list by the open banking () feature(s) needed — features that are in fact supported by the bank. The result is an even smaller list (subset) of Token.io-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:
- Redirect the user to the bank selection screen in the Token.io web app
- Display your own bank selection
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.io's Bank Selection Screens
If you choose to employ Token.io's web app for bank selection (pictured below, click 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.
- Send an HTTP POST call to your backend to initiate the token request and redirect using a .
- Create a Token.io button for your UI that, when clicked, redirects the user to the Token.io 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.io-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.io-connected bank. The -related fields and attributes in the Bank object are listed in the following table.
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 | |
credentialFields | Fields required as part of initial authorization at the bank | |
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 | |
name | Name of the bank (e.g., "First National Bank") |
|
openBankingStandard | API standard adopted/supported by the bank |
|
provider | Open Banking adapter or provider (e.g.,Token, FinApi) |
|
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 | |
supportsPayment | If set to true, single immediate payment is supported | |
supportsFundsConfirmation | If set to true. supports confirmation of available funds | |
supportsInformation | If set to true, AIS is supported | |
supportsScheduledPayment | If set to true, bank supports future-dated payments | |
supportsSendPayment | If set to true, single immediate payment is supported | |
supportsStandingOrder | If set to true, bank supports standing order for recurring payment | |
supportsTransactionsDateFilter | If set to true, supports filtering transactions by date range |
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.
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
();
}
Tip: When retrieving the list of banks for which search text is provided in a getBanks() 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.
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 .