This call will enable you to validate the bank details and will be the call that is our enhanced replacement for the call 1.01. If you want simpler validation then bank code validation can be completed using the call link below.
If you’re just validating a bank code or a BIC with an account number then just complete the country code, bank code, bank code field in the call. You can also validate
- Individuals name
- Address details
- Charge type
- Transaction date
https://validate.bankersalmanac.com/validate-api/rest/convert/1.0.12
Sample request
What do the optional fields do in the request
These fields are the core fields that you will use. For the request listed above you only need complete the countryCode and nationalId fields. We have a number of optional fields which you can use to tailor the output and are listed below.
| Field Name | Description | Mandatory or Optional | Additional details |
| cdtrSalName | The persons salutation for example Mr, Mrs, Ms, Dr, etc | Optional | |
| cdtrFirstName | The creditors full first name | Optional | |
| cdtrMiddleName | The creditors full middle name | Optional | |
| cdtrLastName | The creditors last name, surname or family name | Optional | |
| cdtrAddr1 | The creditors address line 1 | Optional | |
| cdtrAddr2 | The creditors address line 2 | Optional | |
| cdtrCity | The creditors city | Optional | |
| cdtrRegion | The creditors region, county or state | Optional | |
| cdtrZip | The creditors zip code or postal code | Optional | |
| cdtrCompanyName | The creditors company name | Optional | |
| accountType | Account type, individual or corporate | Optional | |
| cdtrNatId | The creditors domestic bank code, or BIC | Mandatory | |
| cdtrAcct | The creditors account number or IBAN | Mandatory | |
| cdtrCtryCde | The creditors account ISO 2 digit country code, these can be downloaded in | Optional | These can be downloaded from here https://validate.bankersalmanac.com/validate-api/rest/convert/4.3 |
| chrg | The charge type used in the payment | Optional | |
| trnsDt | The transaction date in the format YYYY/MM/DD | Optional | |
| currencyCode | The payment ISO 3 digit currency code | Optional | These can be downloaded from here https://validate.bankersalmanac.com/validate-api/rest/convert/4.31 |
| pmtInfId | The payment reference | Optional | |
| amt | The payment amount | Optional | |
| token | Security token | Mandatory |
The response for this request can be modified with a number of flags which allow us to give you a response which meets your business requirements.
| FIELD NAME | DESCRIPTION | FORMAT | MANDATORY or
OPTIONAL | DEFAULT VALUE |
| errorComment | E or S, if the field is set to E then you will be able to
edit the error text in the self service hub | E or S | Optional | N |
| ref | Free text unique reference for you to use. If this is not completed by you we will respond with a unique reference | Alphanumeric & Extended Characters | Optional | |
| noBranch | Yes/No flag if you do not wish to return the branch details. | Y or N | Optional | Y |
| bic8 | Yes/No flag if you wish any head office with xxx to be returned as a BIC8 or BIC11. Yes if you wish to have a BIC8 (without head office XXX) No or leave blank if you want all BICs returned as BIC11 | Y or N | Optional | N |
| isoAddr | This restricts the field size to the ISO defined 80 characters | Y or N | Optional | N |
| payBranchType | This allows you to choose the branch type from either
I IBAN R Routing P Payment B Branch H Head Office | I,B,H,R | Optional | P |
| group | The group name that this data should be saved in. Currently not used. | Alphanumeric & Extended Characters | Optional | |
| page | This requests the page number you are after, the default for this is 1 | Numeric | Optional | 1 |
| pageSize | This defines the number of branches on a page, the default is 10 | Numeric | Optional | 10 |
Making the account number mandatory
If you need the account number to be mandatory then please got to the self service hub using the link below.
https://management.bankersalmanac.com/vss-web
Then go to the error module in the bottom left and change the error below to FAIL
08an Account number not entered
Then save the changes and the service will set the account number as mandatory.
Example Output
The recommended fields Tell you what we believe you should be using
| Field Name | Description | Sample Data | |
| cdtrSalName | The persons salutation for example Mr, Mrs, Ms, Dr, etc | “Mr”, | |
| cdtrFirstName | The creditors full first name | “Joe”, | |
| cdtrMiddleName | The creditors full middle name | “”, | |
| cdtrLastName | The creditors last name, surname or family name | “Sample”, | |
| cdtrAddr1 | The creditors address line 1 | “Small House”, | |
| cdtrAddr2 | The creditors address line 2 | “Hilly Road”, | |
| cdtrCity | The creditors city | “White Shoes”, | |
| cdtrRegion | The creditors region, county or state | “Essex”, | |
| cdtrZip | The creditors zip code or postal code | “CM1 7QB”, | |
| cdtrCompanyName | The creditors company name | “”, | |
| accountType | Account type, individual or corporate | “I”, | |
| statusAcctType | Is the account type valid | “PASS”, | |
| commentAcctType | Error message | null, | |
| status | “CAUTION”, | ||
| comment | “No country service config found (35sy)”, | ||
| applyRef | Apply financial transaction reference | “201909071313GBSTRANGE PAYMENT3094081638696USD”, | |
| cdtrNatId | The creditors domestic bank code, or BIC | “309408”, | |
| cdtrAcct | The creditors account number or IBAN | “1638696”, | |
| cdtrCtryCde | The creditors account ISO 2 digit country code, these can be downloaded in | “GB”, | |
| sepaCountry | Is the country in the SEPA region | “Y”, | |
| ibanCountry | Is the country an IBAN country | “M”, | |
| cdtrBranchDetails | Label | [ | |
| bankName | Bank name | “LLOYDS BANK PLC”, | |
| branch | Branch name | “(HEMEL HEMPSTEAD MARLOWES -309408)”, | |
| street | Bank street address | “198-200 MARLOWES”, | |
| city | Bank city address | “HEMEL HEMPSTEAD”, | |
| postZip | Bank zip code | “HP11BH”, | |
| region | Bank region | “”, | |
| country | Bank country | “UNITED KINGDOM”, | |
| codeDetails | Label | { | |
| codeName1 | Branch BIC field label | “BIC”, | |
| codeValue1 | Branch BIC | “LOYDGB21124”, | |
| codeName2 | CHIPS code field label | “CHIPS”, | |
| codeValue2 | CHIPS code | “”, | |
| codeName3 | Branch BIC4 field label | “BIC-4”, | |
| codeValue3 | Branch BIC4 | “LOYD”, | |
| codeName4 | Domestic bank code name and label | “Sort Code”, | |
| codeValue4 | Domestic bank code | “309408”, | |
| codeName5 | MICR Code or secondary bank code name and label | null, | |
| codeValue5 | MICR Code or secondary bank code | null | |
| }, | |||
| sepaDetails | Label | { | |
| ctStatus | SEPA credit transfer status | “Y”, | |
| ddStatus | SEPA dd status | “Y”, | |
| bbStatus | SEPA b2b status | “Y”, | |
| ictStatus | SEPA Instant credit transfer status | “N” | |
| }, | |||
| additionalData | Label | { | |
| ssiAvailable | Do we have SSIs for this bank | “Y”, | |
| payServiceAvailable | Do we have domestic clearing information available | “Y”, | |
| contactsAvailable | Do we have contact information for this bank | “Y” | |
| availLang | Languages available | “GB” | |
| } | |||
| } | |||
| ], | |||
| recommendation | Label | { | |
| recommendedDomNatId | Domestic currency recommended national id | “309408”, | |
| recommendedDomAcct | Domestic currency recommended account number | “01638696”, | |
| recommendedDomBIC | Domestic currency recommended BIC | “LOYDGB21124”, | |
| recommendedIntNatId | International currency recommended national id | “”, | |
| recommendedIntAcct | International currency recommended account number | “GB50LOYD30940801638696”, | |
| recommendedIntBIC | International currency recommended BIC | “LOYDGB21124”, | |
| recommendedBICSWIFTConnected | Is the recommended BIC swift connected | “N” | |
| recommendedSWIFTConnectedBIC | Recommended SWIFT connected BIC | “LOYDGB2LXXX”, | |
| acccurrency | Currency of the account | “GBP”, | |
| }, | |||
| cdtrAcctStat | Account number validation status | “PASS”, | |
| cdtrAcctCom | Account number error text | “The BIC is not connected to the SWIFT network. (05ro)”, | |
| holidays | Label | [ | |
| { | |||
| country | Country Code | null, | |
| title | Holiday name | “USD – Labor Day”, | |
| date | Holiday date | “Sep 02, 2019” | |
| }, | |||
| { | |||
| country | Country Code | null, | |
| title | Holiday name | “USD – Columbus Day”, | |
| date | Holiday date | “Oct 14, 2019” | |
| } | |||
| ], | |||
| chrg | Charge submitted | “SHA”, | |
| recommendedChrg | Recommended charge | “OUR”, | |
| chrgOpt | Charge type options | “SHA, OUR, BEN, SLEV”, | |
| statusChrg | Charge submitted status | “CAUTION”, | |
| commentChrg | Charge submitted error text | “Recommended a different charge type (15mf)”, | |
| sepaStat | SEPA Status | “N”, | |
| trnsDt | Transaction date | “2019/09/19”, | |
| statusTrnsDt | Transaction date status | “PASS”, | |
| commentTrnsDt | Transaction date error message | “”, | |
| recommendedTrnsDt | Recommended transaction date | “2019/09/24”, | |
| currencyCode | Currency Code | “USD”, | |
| currencyName | Currency Code name | “US DOLLAR”, | |
| currencyStat | Currency Code status | “PASS”, | |
| currencyCom | Currency Code error | “”, | |
| pmtInfId | Payment reference | “Strange payment”, | |
| statusPmtInfId | Payment reference status | “PASS”, | |
| commentPmtInfId | Payment reference error message | “”, | |
| amt | Amount | “”, | |
| statusAmt | Amount status | “PASS”, | |
| commentAmt | Amount error message | “”, | |
| cdtrCleansedDetails | Label | { | |
| fatfStatus | FATF Status | “PASS”, | |
| fatfComment | FATF error message | “”, | |
| recomName | Complete creditor name | “Mr Joe Sample”, | |
| recomAddress | Complete creditor address | “Small House Hilly Road”, | |
| recomCity | Complete creditor city | “White Shoes”, | |
| recomState | Complete creditor state, county or region | “Essex”, | |
| recomPostZipCode | Complete zip code | “CM1 7QB” | |
| }, | |||
| paymentRequirements | Label | { | |
| cdtrEmpnum | Creditor Employee Number | M | M,O,N |
| cdtrCorpaddr | Creditor Company Address | O | M,O,N |
| cdtrAddr | Creditor Address | N | M,O,N |
| bankAddr | Creditor Bank Address | N | M,O,N |
| crdtrNationId | Creditor National Id | N | M,O,N |
| crdtrNation | Creditor Nationality | N | M,O,N |
| crdtrPassnum | Creditor Passport Number | N | M,O,N |
| ppcStatus | Payment purpose code is required | N | M,O,N |
|
registrationNumber
| Corproate Registration Number | M | M,O,N |
|
cdtrTaxCd
| Creditor Tax Code | O | M,O,N |
|
telephoneNumber
| Creditor Telephone Number | O | M,O,N |
| status | requirements status | “CAUTION”, | |
| comment | requiremetns error | “No country service config found (35sy)” | |
| }, | |||
| companyId | apply financial company id | “COMOIUVNOR”, | |
| groupId | apply financial group id | “”, | |
| errorComment | Error text type | “E”, | |
| page | page returned | “0”, | |
| pageSize | number of entries per page | “20”, | |
| pageTotal | number of pages | “0”, | |
| strict | strcit flag applied | “N”, | |
| ref | reference | null, | |
| extendedToken | extended token for payment revalidation | “Wby7mSMjXBou24GmSRVErkw2wKXYp99M26kwQJlvU4VD9BNK8EHVipqC9Cg31NipUlgxKZ7NLNiiiszD6mt3UEWQIubZH8VEvfWG”, | |
| freeToken | free token to get additional details with | “9d3F9GRxiiUkFPEii0mPo10s2hB0PjJaispCxrFXcTu8hRSZfUjITUbVQieie” |