Once you've successfully activated your Token.io user account, you're ready to start integrating our API. Before initiating a request to a Token.io-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 user is requesting, presuming the user is an authorized account holder with a Token.io-connected bank. The GET /banks call filters the list of Token.io-connected banks based on your selection criteria with respect to bank location and bank-supported features.
See Base URLs and Common Request Headers for more information on structuring the GET /banks request.
In the GET /banks request, there are numerous filtering criteria you can add as parameters to narrow your query. Field descriptions and usage are shown in the API definition. You can request a list of all banks available to users in a specific country or countries supporting particular features. Then, upon identifying the bank(s) meeting your criteria, you can display the results for user selection. If no matches are found, you can display that result to the user, as well.
Hence, in response to a successful request — for example, GET /banks?ids = ob-iron — the payload returned in the response will take this format:
APIv1 Sample Response to GET {{BASE_URL}}/banks?ids=iron
{
"banks": [
{
"bankGroup": "xyz-bank-group",
"bic": "HLFXESMMXXX", // bank's BIC code
"countries": ["FR","DE"],
"credentialFields": [ // if populated, user credentials to be captured by TPP prior to request initiation
{
"description": "User authentication",
"displayName": "Client ID",
"id": "clientId",
"options": ["SMS", "Phone Call"],
"password": true //v1 only
}],
"id": "ob-iron", // Token.io bankId
"name": "Iron Bank",
"logoUri": "https://s3-us-west-2.amazonaws.com/tokenio-assets/1.0.0/logos/iron/iron_square.png",
"fullLogoUri": "https://s3-us-west-2.amazonaws.com/tokenio-assets/1.0.0/logos/iron/iron_full.png",
"fieldsFormatInformation": [{ // bank-dependent formats indicating allowable characters
"name": "field name", // name of the field
"path": "path", // field location in request payload
"constraint": "^[A-Za-z0-9?:()./, u0027±s]*$" // regex indicating allowable characters
}],
"mandatory-fields": { //populated request fields required by this bank
"pis" { // object.field names are bank-defined
"debtor-account": true
"debtor-name": true
"beneficiary-name": true
}
"supportsInformation": true,
"requiresOneStepPayment : false.
"supportsSendPayment": true,
"supportsFundsConfirmation": true,
"provider": "Token",
"supportsScheduledPayment": true,
"supportsStandingOrder": true,
"supportsTransactionsDateFilter": false,
"supportsReturnRefundAccount": true,
"supportedTransferDestinationTypes": ["BIC", "FASTER_PAYMENTS", "SEPA"]
"transactionHistoryLimit": -1,
}],
"paging": {
"page": 1,
"perPage": 200,
"pageCount": 1
}
}in GET /banks, when a bank name has a special character, it requires JSON parsing to display correctly.
For example, in the name "Caja Rural de L'alcudia" the apostrophe should be parsed with "\u0027" as the unicode character ': "Caja Rural de L\u0027alcudia" .
Mandatory fields are bank-dependent and are handled on a bank-by-bank basis, as discussed below.
You can optionally perform additional internal filtering on the result set returned by Token.io before displaying the results to the user for final selection. When retrieving the list of banks for which search text is provided in a GET /banks?field=search-string call, an alphabetical sort, 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 unnecessary.
Some banks require the TPP to provide certain fields in the AIS initiation request. These are referred to as Mandatory fields. The Mandatory fields are captured in the mandatoryFields object in the banks object within the GET /banks response from Token.io. The mandatoryFields object contains the fields which must be populated by the TPP for the given bank to accept an AIS initiation request, or request for 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 that are 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.
"mandatoryFields": {
"access" : {
"fields" : ["access_body.resource_type_list.source.account_identifier.iban"]
}
},If mandatoryFields are required for a bank in GET /banks, you must provide these fields within the initiation request.
If the field is not provided by the TPP, then either Token.io or the bank may return an error as a result of the missing field.
Certain banks require the user to provide the accounts for which access is to be given by the bank to the TPP. Therefore the requirement here is for the TPP to capture account information from the user and send it as part of the token request.
The TPP should send the account information in the accessBody.accountResourceList.resources[]. Each accountIdentifier object populated must identify one of the following types:
Token, for linked accountsibanbbangbDomestic– 8-digit bank account number in the UK; also requires thesortCodebankgiro– identifier for domestic bank accounts in Swedenplusgiro– identifier for domestic transaction clearing system in Swedenmsisdn– mobile station international subscriber director number is basically the user's mobile phone number; used as a unique identity to enable routing of voice and SMS traffic to and from a specific subscription/ device on a wireless/mobile network
In EU countries that don't use the euro as their domestic currency, iban should be used for domestic source accounts, with the exception of Sweden. For Swedish domestic, the accountIdentifier can be either bankgiro or plusgiro. Specify a plusgiroNumber for the plusgiro payment rail. If the payment rail is bankgiro, provide a bankgiroNumber.
The resources object containing the accountIdentifier also contains a customerData object identifying the accountholder's legalNames and address (see the Token.io API reference for complete object-field specifications). The customerData object is optional in accordance with the following rules:
A non-empty
accountResourceListmust populateaccountIdentifier. PopulatingcustomerData.legalNames, for instance, without identifying the bank account will throw anInvalidArgument "Missing required field bank_account or account_identifier in source account"error.If the
accountIdentifierobject is populated, it must also have a populated identifier type; otherwise, anInvalidArgument "Missing required field<field name>in source account"error will result. Here, field name depends on the identifier type. For most types —bban,iban,msisdn,bankgiro, andplusgiro— only one field is mandatory. However,gbDomesticrequires bothaccountNumberandsortCode.In cases for which the bank account cannot be mapped to an
accountIdentifiertype, it is excluded from the account validation check. These cases compriseCUSTOM,BANK,GUEST,ACH,TOKEN_AUTHORIZATION, andSECRET.
A PAN is disallowed in the token request payload within the refId and description fields. In accordance with the PA-DSS security standard, Regex is used for pattern matching of numeric strings that intentionally or inadvertently reveal or resemble a PAN in the refId or description of a token request. Potential PAN patterns found will now throw an exception.
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, in which name identifies the field and path is its location (in relation to object.field) within the requestPayload:
"fieldsFormatInformation": [{ // bank-dependent formats indicating allowable characters
"constraint": "^[A-Za-z0-9?:()./,\u0027+\\-\\s]*$"// regex indicating allowable characters
"name": "description", // name of the field
"path": "description", // field location in token request payload
}],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, minus sign, and a space. 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.
Banks support different authentication models:
Redirect – the user connects with the TPP but is redirected to the bank's web interface for authentication.
Embedded – the payment process is executed entirely through the UI presented by the TPP.
Decoupled – the user authenticates using an external form of identification, for example, the bank's dedicated mobile app.
See Authentication for a more detailed description of the authentication models.
Use the GET /banks call to determine which authentication model is required. If the bank supports embedded and decoupled authentication, additional credentials will be available in the credentialFields field.
We recommend that you maintain bank information regularly, by caching daily at 11pm UTC.
Use the GET /banks call to retrieve bank information.
If you have any feedback about the developer documentation, please contact devdocs@token.io