TOKENSĀ
Tokens in Validate API
Validate API calls and tokensĀ
There are various tokens used in an API call depending on the purpose of the call. This could be either to authenticate the API call itself or to provide additional information based on a previous API request.
There are three different types of tokens that might be needed depending on the action being completed in an API call. These are ā
- Security token. This is used for authenticating an API call. A security token is typically active for a period of 10 minutes from the first successful authentication call. Subsequent API calls donāt need to be authenticated as along as the security token is used in the API calls during the active period.
- Bank token. This token helps provide additional/enhanced branch/bank information based on a previous related bank/branch API call. Where APIs accept bank tokens, you can gather additional information linked to the previous call.
- Free token. A few APIs accept free tokens. Use this token in such APIs to gather additional information while the security token is active.
Please refer to Appendix A for more information about the tokens.
Transactions and charges for APIsĀ
The Validate suite of APIs provide for multiple API endpoints. These endpoints help provide specific outcomes for various purposes and use cases. The entire suite of API end points is listed in the documentation link (BankersAlmanacĀ® Validateā¢ API endpoints).
A few endpoints require separate subscriptions and not all API endpoints are charged as separate transaction within a subscription. The table below describes the details ā
| Endpoint actionĀ | DescriptionĀ | SubscriptionĀ | Is the transaction chargeable?Ā |
| Authentication | Before API use, a security token must be generated to authenticate the API. The security token lasts for a period of 10 minutes. | Validate, SPV1 and ASV2 | No |
| Validation (primary APIs) | Use primary Validate APIs to make the first call. The primary calls will provide a Bank Token or a Free Token. These can be used in Enhanced Validation. | Validate | Yes |
| Enhanced Validation | Use these APIs to obtain enhanced information based on initial primary Validate calls. Include Free Token in these calls to save on transaction costs. | Validate | No |
| Safe Payment Verification (SPV) | SPV has its own subscription. While the Security token is through the same call, each SPV is charged as a separate transaction. | SPV | Yes3 |
| Account Status Verification (ASV) | SPV has its own subscription. While the Security token is through the same call, each SPV is charged as a separate transaction. | ASV | Yes4 |
| Validate UI Portal | For UI or portal users the user login acts as a security authentication. The web portal will provide both primary and enhanced information together, so each search is chargeable. | Web interface | Yes |
List of APIs, acquiring or using tokensĀ
The entire suite of API end points is listed in the documentation link (BankersAlmanacĀ® Validateā¢ API endpoints). A primary endpoint call will provide a Bank token or a Free token for use in the supplementary endpoint calls. The supplementary endpoint calls support the acquired token.
The table below provides the API endpoints list and where the tokens are provided. Please note that all APIs (except authentication end point) will need a Security Token.
| Ā | Ā | Provides token in responseĀ | Supports/use token in as an inputĀ | ||
| Endpoint Name5Ā | Type of callĀ Ā | Bank TokenĀ | Free TokenĀ | Bank TokenĀ | Free TokenĀ |
| Authenticate |
Authentication call. Provides Security Token |
– | – | – | – |
| Validation | Primary call. | Yes | Yes | – | – |
| (Bank) Search | Primary call. | Yes | Yes | – | – |
| Local Language | Primary call. | Yes | Yes | – | – |
| Payer Payee | Primary call. | Yes | Yes | – | – |
| Payer | Primary call. | Yes | Yes | – | – |
| (IBAN) Conversion | Primary call. | – | – | – | – |
| (SSI) Payer Payee | Standalone call | – | – | – | – |
| Best (Routing) | Standalone call | – | – | – | – |
| (Country Currency) All | Standalone call | – | – | – | – |
| (ISO Currency) Search | Standalone call | – | – | – | – |
| Country Services | Standalone call | – | – | – | – |
| Health Check | Standalone call | – | – | – | – |
| Correspondent (Network) | Standalone call | – | – | – | – |
| (Bank) Account Number | Primary call. | Yes | Yes | Yes | Yes |
| Payment Processing | Supplementary call. | Yes | Yes | Yes | Yes |
| Payment Purpose Code | Supplementary call | – | – | Yes | Yes |
| Holiday (Data) | Supplementary call | – | – | Yes | Yes |
| Payment Network | – | – | Yes | – | |
() ā Names is brackets is not included in the endpoint name. Check the exact endpoint name in these cases.Ā
Legacy API support for Free TokensĀ
The entire suite of API end points is listed in the documentation link (BankersAlmanacĀ® Validateā¢ API endpoints). A primary endpoint call will provide a Bank token or a Free token for use in the supplementary endpoint calls. The supplementary endpoint
| Endpoint Name6Ā | Legacy version supportĀ |
| (Bank) Account Number | v1.6 |
| Payment Processing | v2, v2.0.1, v2.0.11, v2.0.2 |
| Payment Purpose Code | v4.4, v4.5, v4.5.1, v4.5.2, v4.6 |
| Holiday (Data) | v4.6, v4.6.1, v4.6.2 |
| Payment Network | v2.1, v2.1.1, v2.1.2 |
Appendix A
Details on the various types of tokensĀ
Security tokenĀ Ā
The Bankers Almanac Validate REST API require users to authenticate before validating bank details and retrieving data from the system. We do this by authenticating the user details and returning a security token that can be used with the calls. The security tokens are time limited (10 minutes), and we recommend that you generate a new security token with each call.
The authentication service will confirm that you have an active user account and will create a security token for you. This security token should then be included in the call you make to validate the data or to retrieve other data from the Validate suite of calls. The security token is a security measure to ensure that when you pass the request call to us, your user details are not directly visible.
The security token is used to authenticate the user account and your company, check your subscription and to ensure that the request is registered against your user account. In addition, the security token is time limited, and once expired a new security token will have to be created, therefore it is recommended that you create a new security token for each customer request you perform.
Free tokenĀ Ā
Free token is generated in the primary service calls to be used in supplementary calls and is valid for 10 minutes. First you do a primary service call which will return a free token as part of the response. The free token is meant to be used to enhance a validation that is done e.g. I have validated the account structure and now I want to understand the PPCs, so you can use the free token to enrich the validation.
The endpoints that allow you to use a free token should have a parameter named āfree tokenā.
Bank tokenĀ Ā
This is a token created for the specific bank branch returned in the response. The usual use case for this is, after doing a primary call which resulted in bank branch results, you do a supplementary call to get more information using the bank Token and free Token combination. Using the bank token and the free token the supplementary call is not charged.