API Flow Bank Code & Account Number or IBAN

Flow diagram


We have kept the flow simple

  1. Request a security token for every new validation
  2. Enter the bank details you have either in a code/account or name search
  3. Check what additional data and validations are available
  4. Get the freeToken and bankToken
  5. 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.

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

Validating all the Creditors/Beneficiary 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
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”: “”,


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


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


going to the bottom left and using the “Manage errors” section.

You can read more on how to change it here https://documents.applyfinancial.co.uk/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 tbales for the errors.


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

Finding correspondents

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

Connectivity to payment (channel) networks

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


Holiday Available  

This indicates if holiday details are available

Holiday data request

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

Local Language