Creating an Access Token Request
Submitting an access token request is pivotal to successfully querying a customer's account information.
The scope of analysis and service supported by the Token SDK includes comparing a customer's (PSUPayment Services User – an individual person or legal business entity making use of an Open Banking service as a payee, payer or both.) accounts and transaction history to a range of financial service options, aggregating data across participating financial institutions and customers to create marketing profiles, and making new transactions and account changes on the PSU's behalf.
Remember, to access Account Details, the value of supports_account_details_api must be true in the Bank object for each bank displayed to the user for selection from the GET /banks payload.
API support for accessing a PSU's account information institutes a communications workflow that ensures all PSD2 mandates for PSU consent and authorisation are met. Pictured next (hover to enlarge) is the general flow.
First, however, you have to build the token request and store it. At a minimum, it must contain the relevant details for the account you wish to access — bank, grantor (the account holder), your memberId, and the type of information (resources) you want to receive about the account — account list, balances, transactions, and/or transfer destinations — along with a description of why you are requesting the information and your callback URL, so you can redeem the token once it's issued. There are also a number of other, optional, data items you can include for your own tracking and control.
A request-id is generated and returned with the token payload in response to your token request submission. This identifier references the stored TokenRequest and is used to validate the conditions of the request and to verify that these conditions remain unchanged. You must include the request-id in the URL that redirects the customer to Token to obtain user authentication and authorisation.
Each token request submission has a time limit of 20 minutes. If you do not receive a response within the allotted timeframe, your token request expires and a new request will have to be created and submitted.
Tip: If you know the request-id, you can retrieve the result of any token request — even requests that have expired — with a call to getTokenRequestResult(tokenRequestId). An unauthenticated call can be made within the 20-minute expiration period. It looks like this:
// Get the token request result based on a token's tokenRequestId=
You can make an authenticated call to fetch the request result at any time if you are the TPP that created the original token request. The authenticated version of the call looks like this:
// Get the token request result based on a token's tokenRequestId
Most importantly, the TPP member creating the TokenRequest must match the TPP member redeeming the token or token redemption will fail and access will be denied.
All access token requests are created with the selected-language variant of the accessTokenRequestBuilder() method. Once the token request is created, you store it, awaiting a corresponding request-id, which is returned by Token in a response payload. In addition to the request-id, the response payload reflects all the information you included in your original request. Equipped with the request-id, you can redeem the token, thereby receiving the requested information regarding the customer's bank account(s).
Even though it's really quite simple and incredibly secure, accuracy remains paramount vis-à-vis making the right calls with the right information at the right time.
Here's the basic structure of the request.
* Stores an access token request.
* @param grantee – Token member requesting the access token be created
* @return – a token request-id
public static String
// Create token request to be stored
request = TokenRequest.
// TPP's member ID
// callback URL
// customer-user alias
// bank ID
// nonce for CSRF check
// use keys in bank authorization metadata from getBanks() response
The key fields comprising an access token request are defined in the following table.
Caution: A PANPrimary Account Number – refers to a 14-, 15-, 16-, or even up to 19-digit number generated as a unique identifier designated for a primary account; also called payment card number and permanent card number. is disallowed in the token request payload within the refId and description fields. In accordance with the PA-DSSPayment Application Data Security Standard – Council-managed program formerly under the supervision of the Visa Inc. program known as the Payment Application Best Practices (PABP). The goal of PA-DSS is to help software vendors and others develop secure payment applications that do not store prohibited data, such as full magnetic stripe, CVV2 or PIN data, and ensure their payment applications support compliance with the PCI DSS. Payment applications that are sold, distributed or licensed to third parties are subject to the PA-DSS requirements. In-house payment applications developed by merchants or service providers that are not sold to a third party are not subject to the PA-DSS requirements, but must still be secured in accordance with the PCI DSS. security standard, RegexAPI to define a pattern for searching or manipulating strings. 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.
Nonce generation to protect account information ensures that the specified transfer destination account cannot be reused in a CSRFCross-site request forgery, also known as XSRF, Sea Surf or Session Riding – is an attack vector that tricks a web browser into executing an unwanted action in an application to which a user is logged in. CSRFs are typically conducted using malicious social engineering, such as an email or link that tricks the victim into sending a forged request to a server. As the unsuspecting user is authenticated by their application at the time of the attack, it’s impossible to distinguish a legitimate request from a forged one. Token guards against this type of attack by checking each request against the session ID. replay attack. As desired, you can add to or replace the resource types in the example (in yellow) with TRANSACTIONS and/or TRANSFER_DESTINATIONS.
Important Update: In the access token response payload, account_identifiers are now specified in AccountDetails, which include bic and account_holder_name, along with account_number and/or sort_code. In general, four types of account identifiers are supported:
- Token, for linked accounts
- Iban – IBANInternational Bank Account Number – a number attached to all bank accounts in the EU countries, plus Norway, Switzerland, Liechtenstein and Hungary. The IBAN is made up of a code identifying the country to which the account belongs, the account holder's bank, and the account number itself.
- Bban – BBANBasic Bank Account Number – represents a country-specific bank account number. The BBAN is the last part of the IBAN when used for international funds transfers. Every country has its own specific BBAN format and length. See https://www.mobilefish.com/services/bban_iban/bban_iban.php for help with BBAN conversion.
- GbDomestic – 8-digit bank account number in the UK
Only fields supported by the responding bank will be populated.
These fields were recently added pursuant to deprecating the resolveTransferDestinations call by TPPs. Previously, TPPs could obtain these data — account identifiers, BICBank 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., and customer name — after a getAccount or getAccountDetails call with a subsequent resolveTransferDestinations call, wherein the debit-side bank returned its preferred transfer method(s) — SEPASingle 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., FPSFaster Payments Service – UK banking initiative to reduce payment times between different banks' customer accounts from the three working days that transfers take using the long-established BACS system to typically a few seconds., DomesticBanks make domestic wire transfers (as opposed to international wire transfers) to send funds to financial institutions residing in the same country or financial zone., etc. — along with the bic and CustomerData.
However, to optimise API utilisation and eliminate the additional call to resolveTransferDestinations, banks are now required to populate account_identifiers, bic and account_holder_name in the accountDetails object returned by the getAccount and getAccountDetails calls. TPPs are therefore encouraged to discontinue relying on the resolveTranserDestinations method.
After storing the transfer token request, you're ready to construct the redirect URL for authorisation so the customer can authenticate, provide consent, and authorise account information access as previously outlined in the AIS communication workflow.
Tip: When integrating the Token SDK with a mobile app, you can initiate the token request in WebViewA browser engine that you can insert like an iframe into your native app and programmatically tell it what web content to load. so that the redirect is also in the form of an HTTP 302An 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.. However, in terms of activity layout, WebView lacks many features found in a fully developed web browser.