API response and what to expect

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

https://apps.applyfinancial.co.uk/validate-api/rest/convert/1.0.1?countryCode=GB&token=ADDTOKEN&noBranch=&errorComment=E&accountNumber=&nationalId=LOYDGB2LXXX

Validate a sort code

countryCode                      GB

nationalId                          309408

accountNumber

https://apps.applyfinancial.co.uk/validate-api/rest/convert/1.0.1?countryCode=GB&token=ADDTOKEN&noBranch=&errorComment=E&accountNumber=&nationalId=309408

Validate a sort code and account number

countryCode                      GB

nationalId                          309408

accountNumber               01638696

https://apps.applyfinancial.co.uk/validate-api/rest/convert/1.0.1?countryCode=GB&token=ADDTOKEN&noBranch=&errorComment=E&accountNumber=01638696&nationalId=309408

Validate a BBAN

countryCode                      GB

nationalId

accountNumber                30940801638696

https://apps.applyfinancial.co.uk/validate-api/rest/convert/1.0.1?countryCode=GB&token=ADDTOKEN&noBranch=&errorComment=E&accountNumber=30940801638696&nationalId=

Validate an IBAN

countryCode                      GB

nationalId

accountNumber               GB50LOYD30940801638696

https://apps.applyfinancial.co.uk/validate-api/rest/convert/1.0.1?countryCode=GB&token=ADDTOKEN&noBranch=&errorComment=E&accountNumber=GB50LOYD30940801638696&nationalId

 

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://apps.applyfinancial.co.uk/vss-web/apply/ 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://apps.applyfinancial.co.uk/vss-web/apply/ and 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 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”

 

  1. 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”,

 

  1. 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”

 

  1. 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”

 

  1. 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

https://documents.applyfinancial.co.uk/validate-api/section-2-correspondents-and-payment-networks/call-2-1-payment-network-channel-membership/

 

contactsAvailable                             This indicates if we publish contact details for the bank so you can call them

https://documents.applyfinancial.co.uk/validate-api/section-4-data-lookup/call-4-2-contact-details-service/

 

messageAvailable                            This indicates if payment reason codes are available

https://documents.applyfinancial.co.uk/validate-api/section-4-data-lookup/call-4-5-payment-reason-code/

 

holidayAvailable                               This indicates if holiday details are available

https://documents.applyfinancial.co.uk/validate-api/section-4-data-lookup/call-4-6-holiday-data/

 

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.