Quick Start for Validate API

Introduction

We have made the integration of our API into your user flow as simple as possible.

The basic flow for the calls is

1. Create an app
2. Get the API user Key for the app created
3. Add the user key parameter to your API calls to report and authenticate
4. Submit the details you wish to validate

If you cannot find anything or are wondering how best to use something, then please just ask and we are happy to help.

Validation Call

The Validating Bank and Account Number call is the API call for this service. The call will check the details you submit and respond with a status of PASS, CAUTION or FAIL and we always respond with a recommendation for the format of bank code and account number that you entered to make the payment. This call is very flexible and uses the inbuilt intelligence so you can validate the details your customers have rather than be prescriptive about the exact format they require.

For example, for the UK you can submit bank details in the following formats:

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 do not need to be strict with the customer and that your customers can make payments more easily and more accurately.

Getting Started with Receiver Bank Validation

Validate API Example

This is a simple REST API. To get going all you need is to get the API Key and submit the details that your customer has in a GET call (along with the API Key in other to authenticate) and you will be able to validate the data and have the answer.

This one call copes with domestic and international payment details and will check them in as many ways as possible and return you the details. When it comes to validating data, you do not expose your user credentials to end users.

Along with your API Key, the two parameters that you need for the authentication of the call are your username and password. These are your email address and the password for the account.

Validating the data

Now that you have the details required for authentication, you will then need the details your customer gave you i.e., sort code and bank account number, submit them along with the country code and you will get your answer. Our solution will understand the details that you submitted and will inform you if they are correct or not and the reason why.

Example of how to validate the data

IBAN Validation

The request to validate an IBAN would look like the request below, you will need to include the API Key in the request and include the bank details you wish to Validate.

Validating data for the Global BA Validations API

Validating data for UK BA Validations API

Validating data for the Americas BA Validations API

The national id field can be an ABA code, or any domestic id and the account number would be a domestic account number or as in the example above an IBAN.

Please find the details for this call below.

Validating a Bank Code and Account Number

To validate a bank code and account number, use call 1.01. Call 1.01 is our core call and allows our clients to validate all formats of codes and account numbers.

If you are 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. We'll respond with details of the bank branch.

For example, to validate the the UK bank code 309408 and the account number 01638696, the details we require are

• Country Code: GB
• National Id: 309408
• Account Number: 01638696

Validating data for the Global BA Validations API

Validating data for UK BA Validations API

Validating data for the Americas BA Validations API

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 several optional fields which you can use to tailor the output and are listed below.

FIELD NAME	DESCRIPTION	FORMAT	MANDATORY or OPTIONAL	DEFAULT VALUE
countryCode	ISO Country Code	Alpha	Mandatory
nationalId	Domestic bank ID	Alphanumeric	Optional
accountNumber	Domestic Account Number, BBAN or IBAN	Alphanumeric	Optional

The response for this request can be modified with several flags (query parameters) 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
dataStore	Yes/No flag if you wish the data to be stored for periodic scanning using the	Y or N	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

API Flow Bank Code & Account Number or IBAN

Flow

We have kept the flow simple

1. Request an API Key by selecting the option to generate an API key
2. Enter the bank details you have either in a code/account or name search
3. Make the API call with these details
4. You will receive a response back with the details of the validation (Pass or caution or fail).

1. API Key

Generate an API Key for each new validation you conduct

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:

FIELD NAME	DESCRIPTION	FORMAT	MANDATORY or OPTIONAL	DEFAULT VALUE
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”: “”,

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.

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 available in 3 section, branch, head office and payment branch details. What you use from this depends on what you require for your systems/compliance and business processes.

This consists of the bank address details and its codes, followed by the following additional details (which are visible as part of the response returned).

Please note that, although we have provided information below on these additional details and you receive them as part of the response received, they are not configurable, as they are not part of the service offered through any of the plans available on this website. If you would like to upgrade to the product where these additional details are offered as a configurable service, please select the following link.

https://risk.lexisnexis.com/products/bankers-almanac-validate

SEPA Status

This tells you the SEPA status for

• SEPA credit transfers
• SEPA direct debits
• SEPA B2B direct debits
• SEPA Instant credit transfers

Additional details and validations

The final section tells you if we have additional information for the branch which can be retrieved by upgrading to the Validate VSS product which you can find more information on by visiting the following link:

https://risk.lexisnexis.com/products/bankers-almanac-validate

The following information is configurable through the VSS product

“additionalData”: {
“ssiAvailable”: “Y”,
“payServiceAvailable”: “Y”,
“contactsAvailable”: “Y”,
“messageAvailable”: “N”,
“holidayAvailable”: “Y”
}

A further description of each is provided below.

Additional validations

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.

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.

Other elements which are available in calls

(please note that these are only configurable by upgrading to the Validate VSS product, see https://risk.lexisnexis.com/products/bankers-almanac-validate for more information)

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.