Here we’ll run through the response to our core call Receiver Bank Validation which is call 1.01 in the Validate API. This validates the bank code and account number that you are trying to send payments to. We’ll run through the sections of the response and what we give in each. You’ll find this is very consistent throughout the API whichever call you are using.
To see how flexible our validation API is you can do this using the following samples. These are examples of the validations for a UK code and account number, but from it you’ll see that we support many different formats of account number and bank code all within the same call. We do this so that you can integrate a minimum number of fields and still get the answer you need to make the payment.
Examples
Validate a BIC
countryCode GB
nationalId LOYDGB2LXXX
accountNumber
Validate a sort code
countryCode GB
nationalId 309408
accountNumber
Validate a sort code and account number
countryCode GB
nationalId 309408
accountNumber 01638696
Validate a BBAN
countryCode GB
nationalId
accountNumber 30940801638696
Validate an IBAN
countryCode GB
nationalId
accountNumber GB50LOYD30940801638696
Breakdown of the response you get
If you run one of the validation samples above or you use our tool to see what happens when you try an input which can be found here) then you will get the response which we have broken down for you below to give you a detailed explanation of our response.
The top section gives you the search details and our recommendations. The rest of the response gives you details on the bank and bank branch itself.
Sample of the first portion of a response
“countryCode”: “GB”,
“nationalId”: “309408”,
“accountNumber”: “01638696”,
“recommendedNatId”: “”,
“recommendedAcct”: “GB50LOYD30940801638696”,
“recommendedBIC”: “LOYDGB21124”,
“status”: “PASS”,
“comment”: “The BIC is not connected to the SWIFT network; please enter a BIC without a 1 as the 8th digit. For example LOYDGB21124 is not connected and LOYDGB2LXXX is. (05ro)”,
“ref”: “20170711170316996”,
Explanation of the first portion of a response
The first elements in GREEN give you back the search criteria that you entered
“countryCode”: “GB”,
“nationalId”: “LOYDGB2LXXX”,
“accountNumber”: “”,
The next section in BLUE give you back our recommendations of the format which you should be using. This can be changed by signing into the self-service hub https://management.bankersalmanac.com/vss-web and going to the bottom left and using the “recommendations” section. 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”,
The next elements are our status and comment on the status which are highlighted in PURPLE these tell you if we have been able to check the details that you submitted and any issues that we found with them. These again can be changed by signing into the self-service hub https://management.bankersalmanac.com/vss-web and 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 map any errors.
“status”: “PASS”,
“comment”: “The BIC is not connected to the SWIFT network; please enter a BIC without a 1 as the 8th digit. For example LOYDGB21124 is not connected and LOYDGB2LXXX is. (05ro)”,
The last element that is relevant in this section is the ref field in RED. 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”,
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. Please feel free to give me a call if you want to discuss any of this.
I will discuss one section here the branch as each section has the same fields for its branch details.
“bankName”: “LLOYDS BANK PLC”,
“branch”: “(HEMEL HEMPSTEAD MARLOWES -309408)”,
“street”: “198-200 MARLOWES”,
“city”: “HEMEL HEMPSTEAD”,
“postZip”: “HP1 1BH”,
“region”: null,
“country”: “UNITED KINGDOM”,
“codeDetails”: {
“codeName1”: “BIC”,
“codeValue1”: “LOYDGB21124”,
“codeName2”: “CHIPS”,
“codeValue2”: “”,
“codeName3”: “BIC-4”,
“codeValue3”: “LOYD”,
“codeName4”: “Sort Code”,
“codeValue4”: “309408”
},
“sepaDetails”: {
“ctStatus”: “YES”,
“ddStatus”: “YES”,
“bbStatus”: “YES”
},
“additionalData”: {
“ssiAvailable”: “Y”,
“payServiceAvailable”: “Y”,
“contactsAvailable”: “Y”,
“messageAvailable”: “N”,
“holidayAvailable”: “Y”
},
“bankToken”: “ByLDfa5sM5pxdr3A1ZeJ6JfdznEwWBxyjmmDEow57MIoLbI0SqXGpQieie”
- Bank address details
This is the address information for the branch that you have requested.
“bankName”: “LLOYDS BANK PLC”,
“branch”: “(HEMEL HEMPSTEAD MARLOWES -309408)”,
“street”: “198-200 MARLOWES”,
“city”: “HEMEL HEMPSTEAD”,
“postZip”: “HP1 1BH”,
“region”: null,
“country”: “UNITED KINGDOM”,
- Code details
These are the codes for the branch and are always in the order as described below. The name of code 4 will vary country to country and will be the local name of the code set.
codeName1 BIC – This is the BIC code from SWIFT for the branch
codeName2 CHIPS – This is the CHIPS code which is a US interbank network
codeName3 BIC-4 – This is the 4 digit BIC for the branch
codeName4 Sort Code – This is the domestic code set for the branch
e.g.
“codeDetails”: {
“codeName1”: “BIC”,
“codeValue1”: “LOYDGB21124”,
“codeName2”: “CHIPS”,
“codeValue2”: “”,
“codeName3”: “BIC-4”,
“codeValue3”: “LOYD”,
“codeName4”: “Sort Code”,
“codeValue4”: “309408”
- SEPA compliance
This tells you if the branch can make/receive SEPA payments for the 3 different section
ctStatus SEPA credit transfers
ddStatus SEPA core direct debits
bbStatus SEPA business to business direct debits
e.g.
“sepaDetails”: {
“ctStatus”: “YES”,
“ddStatus”: “YES”,
“bbStatus”: “YES”
- Additional Data
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.
ssiAvailable Are SSIs available in a currency for this branch, this will not be relevant to you
payServiceAvailable 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
contactsAvailable This indicates if we publish contact details for the bank so you can call them
messageAvailable This indicates if payment reason codes are available
holidayAvailable This indicates if holiday details are available
We have 4 new calls upcoming which may be of interest to you. Below is a quick description of the calls and if you wat we can get you the details as soon as they’re available
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.