Flow
We have kept the flow simple
- Request a security token for every new validation
- Enter the bank details you have either in a code/account or name search
- Check what additional data and validations are available
- Get the freeToken and bankToken
- Use those tokens to additional details or perform additional validations free of charge
This flow is covered below with links to more details:
1. Security token
Create a Security Token for each new validation you do.
https://documents.validate.bankersalmanac.com/security-token/
2. Validate the bank details
Validate the bank details, either with the bank code and account number or by using the IBAN or BBAN
https://documents.validate.bankersalmanac.com/validating-all-the-creditors-beneficary-details/
For example for the country code GB you can submit bank details in the following formats in this one call:.
| Supported format | National ID | Account Number |
| BIC only | LOYDGB2LXXX | |
| Bank Code only | 309408 | |
| Bank Code & Account Number | 309408 | 01638696 |
| BBAN | 30940801638696 | |
| BBAN | LOYD30940801638696 | |
| IBAN | GB50LOYD30940801638696 |
This gives you an idea of the breadth of formats we support per country, the API allows you to enter the details that your customer has. Â Meaning that you donât need to be strict with the customer and that your customers can make payments more easily and more accurately.
Understanding the response
Here is a quick run through the response so you know what we’re responding with
Search Criteria
The first three fields in the response show you your search criteria you that were entered.
âcountryCodeâ: âGBâ,
ânationalIdâ: âLOYDGB2LXXXâ,
âaccountNumberâ: ââ,
Recommendations
The next section shows you what we recommend.
The recommendations can be changed self-service hub by signing in as an administrator at the URL below
https://management.bankersalmanac.com/vss-web
and going to the bottom left and using the ârecommendationsâ section. The recommendations are set to International or cross border as default.
If in this case you made GB a domestic currency we would recommend back a sort code and account number for the UK as domestically we use sort code and account number and not a IBAN. We do this globally.
ârecommendedNatIdâ: ââ,
ârecommendedAcctâ: âGB50LOYD30940801638696â,
ârecommendedBICâ: âLOYDGB21124â,
Validation Status and Errors
The next fields are status and comment which tell you if the search was PASS, CAUTION or FAIL and the error text associated with it.
The Status and Error Text can both be  again can be changed by signing into the self-service hub here
https://management.bankersalmanac.com/vss-web
going to the bottom left and using the âManage errorsâ section.
You can read more on how to change it here https://documents.validate.bankersalmanac.com/self-service-hub-introduction/changing-errors-status-and-text.
The error text can be changed in the self-service hub and this text which you have personalised can be retrieved by adding the errorComment and setting it to E field to your request. This will mean that you donât have to use development time to create mapping tables for the errors.
Reference
If you submit a reference this is where it will be returned to you, if you did not submit a reference then we will complete it with our own unique reference for you and return it in this field.
ârefâ: â20170711170316996â,
Bank Details
The rest of the response is 3 sections branch, head office and payment branch details. What you use from this depends on what you require for you systems/compliance and business processes.
This consists of the bank address details and its codes, followed by
SEPA Status
This tells you the SEPA status for
SEPA credit transfers
SEPA direct debits
SEPA B2B direct debits
SEPA Instant credit transfers
The final field SEPA ICT request you to have the field sepaAll set to Y in the request to return this field
3. Which additional details and validations are available
The final section tells you if we have additional information for the branch which can be retrieved at no additional code using the final field bankToken. IF you use that token within 10 minutes using that in conjunction with the freeToken at the bottom of the response you will be able to retrieve the information detailed below.
These flags tell you what additional information is available
“additionalData”: {
“ssiAvailable”: “Y”,
“payServiceAvailable”: “Y”,
“contactsAvailable”: “Y”,
“messageAvailable”: “N”,
“holidayAvailable”: “Y”
4. Additional validations
Here is some more details on the additional validations that are available
Correspondents Available Â
Are SSIs available in a currency for this branch
https://documents.validate.bankersalmanac.com/correspondents/86-2/
Domestic Clearing Networks
payServiceAvailable flag indicates if they are or not
This indicates if we have information on the domestic payment network for example in the UK BACS, CHAPS, faster payments, etc, this can be retrieved using call 2.1. More information is held here
Contacts Available         Â
This indicates if we publish contact details for the bank so you can call them if you need to get information on a payment.
Message Available  Â
This indicates if payment reason codes are available. More information is held here
https://documents.validate.bankersalmanac.com/validate-api-2/call-4-5-payment-reason-code/
Holiday Available Â
This indicates if holiday details are available
Other elements which are available in calls
Complete Message Details Validation
This will validate the entire set of fields described in the data cleansing and the payment validation calls below
Data Cleansing and FATF
This will validate the Debtor and Creditor address, name fields and the payment reference field for character validity and that the name is a well-constructed and full name.
Payment Validation, SEPA and charging
This will validate the payment details and give back information on the validity of the data the bank branches and the payment charge types.
Holiday T+
The holiday call will return the holiday between the sender and receiver for the next 7 days and give you a possible delay time. IF you set your standard T+ date then we will tell you when the t+ date is likely to be so you can warn users of any possible payment delay.
Local Language
We’re return the bank details in the local language