Bottomline PTX
API docs by Redocly

(v5.9.11)

Download OpenAPI specification:

Introduction

The PTX Verify API is organised around REST and uses standard REST features such as resource orientated URLs and HTTP response codes to indicate API errors.

All API calls require an API key which will be provided when you sign up to use the API.

When using the API, you'll need to make a POST request of Content-Type application/json. The URL you will target depends on how you're using the service:

◦ If testing against our online RESTful API: https://verify.uat.uk.pt-x.com/

◦ If in production with our online RESTful API: https://verify.uk.pt-x.com/

◦ If using your own network, you'll need to use the URL/IP address on which you are hosting the service.

International Validation

Obtain comprehensive validation and conversion between International Bank Account Numbers (IBAN) and Domestic Account details.

Validate an Iban

Validates an IBAN (ISO-13616 International Bank Account Number), checking the country code, the checksum and that the length of the IBAN is correct for the country.

Request Body schema: application/json
required

The IBAN.

ApiKey
required
string

The API key, fixed format and provided at sign up.

Iban
required
string

The IBAN to validate.

Responses

Request samples

Content type
application/json
{
  • "ApiKey": "xxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  • "Iban": "TR350006200023400009073271"
}

Response samples

Content type
{
  • "CountryCode": "TR",
  • "Bban": "0006200023400009073271",
  • "InvalidIssue": 0,
  • "Valid": true,
  • "InvalidReason": "",
  • "InvalidParameter": ""
}

Validate an IBAN (advanced validation)

Validates an IBAN (ISO-13616 International Bank Account Number), checking the country code, the checksum and that the length of the IBAN is correct for the country.

In addition to the standard IBAN validation, the advanced validation request also deconstructs the IBAN and validates the account details.

Request Body schema: application/json
required

A JSON object containing the IBAN.

ApiKey
required
string

The API key, fixed format and provided at sign up.

Iban
required
string

The IBAN to validate.

Responses

Request samples

Content type
application/json
{
  • "ApiKey": "xxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  • "Iban": "TR350006200023400009073271"
}

Response samples

Content type
{
  • "InputIban": "TR350006200023400009073271",
  • "AdditionalValidationInfo": false,
  • "AdditionalValidationInfoText": null,
  • "OutputCountryCode": null,
  • "OutputCountryName": null,
  • "OutputIban": "TR350006200023400009073271",
  • "OutputBban": "0006200023400009073271",
  • "OutputAccountNumber": "0023400009073271",
  • "BankBranch": {
    },
  • "InvalidIssue": 6,
  • "Valid": false,
  • "InvalidReason": "(FAIL 02bc) = The Bank Identifier could not be found.",
  • "InvalidParameter": "iban"
}

Retrieve IBAN countries

Retrieves list of countries that support the advanced IBAN (ISO-13616 International Bank Account Number) validation method.

Request Body schema: application/json
required

The API key, fixed format and provided at sign up.

ApiKey
required
string

The API key, fixed format and provided at sign up.

Responses

Request samples

Content type
application/json
{
  • "ApiKey": "xxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx"
}

Response samples

Content type
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Validate a BBAN

Validates a BBAN (Basic Bank Account Number) against the provided IBAN country. The BBAN format is validated and then deconstructed so that its constituent account details can also be verified.

Request Body schema: application/json
required

A JSON object containing the BBAN.

ApiKey
required
string

The API key, fixed format and provided at sign up.

CountryCode
required
string

The country code

BBan
required
string

The BBAN

Responses

Request samples

Content type
application/json
{
  • "ApiKey": "xxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  • "CountryCode": "GB",
  • "BBan": "LOYD30919700875502"
}

Response samples

Content type
{
  • "InputCountryCode": "GB",
  • "InputBban": "LOYD30919700875502",
  • "AdditionalValidationInfo": false,
  • "AdditionalValidationInfoText": null,
  • "OutputCountryCode": "GB",
  • "OutputCountryName": "UNITED KINGDOM",
  • "OutputIban": "GB24LOYD30919700875502",
  • "OutputBban": "LOYD30919700875502",
  • "OutputAccountNumber": "00875502",
  • "BankBranch": {
    },
  • "InvalidIssue": 0,
  • "Valid": true,
  • "InvalidReason": "",
  • "InvalidParameter": ""
}

Validate a domestic account

Validates a domestic account details against the provided IBAN country, checking that the bank branch exists and that the account passes the appropriate modulus check for the institution. It also returns, where possible, a converted IBAN (ISO-13616 International Bank Account Number) and BBAN (Basic Bank Account Number) for the account and bank branch administrative details.

Request Body schema: application/json
required

A JSON object containign the account to be validated

ApiKey
required
string

The API key, fixed format and provided at sign up.

CountryCode
required
string

The country code.

BankIdentifier
required
string

The bank identifier.

AccountNumber
required
string

The account number.

AdditionalData
string

Any additional data.

Responses

Request samples

Content type
application/json
{
  • "ApiKey": "xxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  • "CountryCode": "GB",
  • "BankIdentifier": "309197",
  • "AccountNumber": "0875529"
}

Response samples

Content type
{
  • "InputCountryCode": "GB",
  • "InputBankIdentifier": "309197",
  • "InputAccountNumber": "0875529",
  • "AdditionalValidationInfo": false,
  • "AdditionalValidationInfoText": null,
  • "OutputCountryCode": "GB",
  • "OutputCountryName": "UNITED KINGDOM",
  • "OutputIban": "GB71LOYD30919700875529",
  • "OutputBban": "LOYD30919700875529",
  • "OutputAccountNumber": "00875529",
  • "BankBranch": {
    },
  • "InvalidIssue": 0,
  • "Valid": true,
  • "InvalidReason": "",
  • "InvalidParameter": ""
}

Validate an account using international server

Validates an account using the provided account details, returning a full response from the international server.

Request Body schema: application/json
required

A JSON object of type PostIbanAdvanced

ApiKey
required
string

The API key, fixed format and provided at sign up.

CountryCode
required
string

The country code.

BankIdentifier
required
string

The bank identifier.

AccountNumber
required
string

The account number.

AdditionalData
string

Any additional data.

Responses

Request samples

Content type
application/json
{
  • "ApiKey": "xxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  • "AccountNumber": "TR350006200023400009073271"
}

Response samples

Content type
{
  • "InputCountryCode": "",
  • "InputBankIdentifier": "",
  • "InputAccountNumber": "TR350006200023400009073271",
  • "ErrorMessageDescription": "",
  • "Response": {
    }
}

UK Account Validation

Validate a UK account to check a bank account and sort code details against the Extended Industry Sort Code Directory (EISCD) to ensure that the bank branch exists, and to confirm the validity of the account number for that sort code algorithmically. Account details are automatically transposed where appropriate and building society roll number requirements are also validated.

Validate a UK bank account

Validates a UK bank or building society account details.

Invalid issue codes and descriptions

Code Description InvalidParameter
1 The sort code is either too long or too short. sortcode
2 The sort code contains non-numeric characters or invalid/misplaced separators. sortcode
3 The account number is too short. accountNumber
4 The account number is too long. accountNumber
5 The account number contains non-numeric characters. accountNumber
6 The sort code and account number do not pass the modulus check. sortcode
7 The sort code is not found in the database. sortcode
8 The account number requires transcription, but it is too short. accountNumber
9 The account number requires transcription, but it is too long. accountNumber
10 The account number requires transcription, but it does not have the expected prefix. accountNumber
11 The account number requires transcription, but it is not in the expected format. accountNumber
12 The account number and sort code also require a Building Society Roll Number, but none was supplied. accountNumber
13 The account number and sort code require a Building Society Roll Number, but the one supplied is not in the expected format. accountNumber
Request Body schema: application/json
required

UkBankAccount object

ApiKey
required
string

The API key, fixed format and provided at sign up.

SortCode
required
string [ 6 .. 6 ]

The sort code.

AccountNumber
required
string [ 8 .. 8 ]

The account number.

BuildingSocietyRollNumber
string

The building society roll number.

Responses

Request samples

Content type
application/json
{
  • "ApiKey": "xxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  • "SortCode": "209448",
  • "AccountNumber": "70221236",
  • "BuildingSocietyRollNumber": ""
}

Response samples

Content type
{
  • "AccountDetailsInput": {
    },
  • "AccountDetailsOutput": {
    },
  • "AccountIBAN": "GB05BARC20944870221236",
  • "AccountTranscribed": false,
  • "UKBankBranch": {
    },
  • "RequiresBuildingSocietyRollNumber": false,
  • "BuildingSocietyRollNumberTranscribed": false,
  • "InvalidIssue": 0,
  • "Valid": true,
  • "InvalidReason": "",
  • "InvalidParameter": ""
}

List UK bank branches

Returns a list of up to 1,000 bank branches that match the criteria provided.

Request Body schema: application/json
required

JSON object containing the details of the bank branch.

ApiKey
required
string

The API key, fixed format and provided at sign up.

Id
string

The ID.

BankName
string

The Bank name.

BankOfficeTitle
string

The Bank office title.

BranchName
string

The branch name.

OfficeTitle
string

The office title.

Town
string

The town.

County
string

The county.

Postcode
string

The post code of the branch.

BacsCredits
boolean

If true, will only return results that support BACS credits.

BacsDebits
boolean

If true, will only return results that support BACS debits.

FasterPayments
boolean

If true, will only return results that support Faster Payments.

Chaps
boolean

If true, will only return results that support CHAPS.

Responses

Request samples

Content type
application/json
{
  • "ApiKey": "xxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  • "BankName": "BARCLAYS BANK PLC",
  • "Postcode": "BH15 2BB",
  • "BacsCredits": false,
  • "BacsDebits": false,
  • "FasterPayments": false,
  • "Chaps": false
}

Response samples

Content type
[
  • {
    },
  • {
    }
]

Retrieve a UK bank branch

Returns the branch details for a specific sort code.

Request Body schema: application/json
required

JSON object containing the Sort Code of the branch

ApiKey
required
string

The API key, fixed format and provided at sign up.

SortCode
required
string

The sort code.

Responses

Request samples

Content type
application/json
{
  • "ApiKey": "xxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  • "SortCode": "011001"
}

Response samples

Content type
{
  • "BankBIC": "NWBKGB21",
  • "BranchBIC": "36P",
  • "BankCode": null,
  • "BankName": "NATIONAL WESTMINSTER BANK PLC",
  • "BankOfficeTitle": "MANCHESTER,CITY CENTRE",
  • "BranchName": "City Centre",
  • "OfficeTitle": "Manchester, City Centre",
  • "ContactAddress1": "Chatham Customer Service Centre",
  • "ContactAddress2": "Western Avenue",
  • "ContactAddress3": "Waterside Court",
  • "ContactAddress4": "Chatham Maritime",
  • "ContactAddressCity": "Chatham",
  • "ContactAddressCounty": "Kent",
  • "ContactAddressPostCode": "ME4 4RT",
  • "ContactAddressPostCountry": "UNITED KINGDOM",
  • "ContactPhoneNumber": "0870 2403355",
  • "SortCode": "011001",
  • "DateLastChanged": "2016-04-06",
  • "TransactionInfo": {
    },
  • "ChapsBankBIC": "NWBKGB55",
  • "ChapsBranchBIC": "XXX"
}

Payer Bank Account Verification (DD)

Verify account details that a payee provides to protect your goods and services against potential fraudsters. The API allows you to search for addresses, retrieve a formatted address, verify a personal account and verify a business account.

Search for addresses

Searches for a list of addresses that match a given input criteria. Each part of the address must be separated by a comma, e.g. Cae Synamon, LL55 1LN.

Request Body schema: application/json
required

JSON object of type PostSearchAddress

ApiKey
required
string

The API key, fixed format and provided at sign up.

Query
required
string

The free text format of the address to search for.

Take
required
string

The number of records to return.

Responses

Request samples

Content type
application/json
{
  • "ApiKey": "xxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  • "Query": "LL551LN",
  • "Take": "25"
}

Response samples

Content type
{
  • "TotalMatches": 4,
  • "Count": 4,
  • "Results": [
    ]
}

Get a formatted address

Retrieves a formatted address using a unique identifier obtained from the Search for addresses call.

Note: The content and format of the identifiers can change without notice so should not be cached.

Request Body schema: application/json
required

JSON object of type PostGetFormattedAddress

ApiKey
required
string

The API key, fixed format and provided at sign up.

Id
required
string

Id of the address obtained from the Search for addresses call. The format and content of the Id can change without notice and should not be cached.

Responses

Request samples

Content type
application/json
{
  • "ApiKey": "xxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  • "Id": "MRF|fc546cfe-ccb0-4cd7-b6a7-960b089af5b5|7.730iOMRFEAjjBwAAAAABAwEAAAAAiNYMkABhIAIAAAAAAAAAAAD..2QAAAAA.....wAAAAAAAAAAAAAAAAAAAENhZSBTeW5hbW9uLExMNTUgMUxOAAAAAAA-$20"
}

Response samples

Content type
{
  • "AddressKey": "MRF|fc546cfe-ccb0-4cd7-b6a7-960b089af5b5|7.730iOMRFEAjjBwAAAAABAwEAAAAAiNYMkABhIAIAAAAAAAAAAAD..2QAAAAA.....wAAAAAAAAAAAAAAAAAAAENhZSBTeW5hbW9uLExMNTUgMUxOAAAAAAA-$20",
  • "Organisation": "",
  • "Flat": "",
  • "HouseName": "Cae Synamon",
  • "HouseNumber": "",
  • "Street": "Bangor Road",
  • "Locality": "CAERNARFON",
  • "PostalCode": "LL55 1LN",
  • "Country": "UNITED KINGDOM",
  • "IsBusinessAddress": false
}

Verify payer’s personal account

Verifies if a UK personal bank account is associated with a given person (the payer).

Example data

First Name Surname DOB Sort Code Account Number Street Postcode House Number House Name Flat Outcome PDS, AS, S
Lisa Jali 1985-07-07T00:00:00 070116 00007338 Bangor Road LL55 1LN Cae Synamon 9, 9, Open
Ashely Marma 1968-04-10T00:00:00 070116 00003036 Wydeville Manor Road SE120ES 1 Abbey Lodge 9, 8, Open
Tanya Pealing 1984-10-20T00:00:00 070116 00003554 Asolando Drive SE171EH 1 Ben Ezra Court 0, 0, Closed
Maureen Borton 1984-11-21T00:00:00 070116 00065090 Ainley Wood SK164BP 1 0, 0, Deceased
Loveina Tutton 1969-03-24T00:00:00 070116 00003072 Barnhurst Lane CT18 7AU Acorns Flat 19 9, 9, NotSingle

Outcome legend

Code Meaning Description
PDS Personal details score 0 to 9, indicates how closely personal information has been matched.
AS Address score 0 to 9, indicates how closely address information has been matched.
S Status Bank account status.

Personal Score

First Name Surname DOB Score Match Recommendation
Li Ja Not entered 1 No match. Typically you would reject this.
Li Ja 1985-07-07T00:00:00 1 No match. Typically you would reject this.
L Jal Not entered 3 Possible match.
Lise Jalo 1985-08-07T00:00:00 5 Probable match.
Lisa Jalo Not entered 5 Probable match.
Lise Jali Not entered 5 Probable match.
Lise Jali 1985-08-07T00:00:00 7 Highly probable match.
Lisa Jali Not entered 7 Highly probable match. This is not an exact match because the date of birth has not been supplied.
Lisa Jali 1885-07-07T00:00:00 7 Highly probable match.
Lisa Jali 1985-08-08T00:00:00 7 Highly probable match.
Lisa Jali 1985-07-06T00:00:00 8 Highly probable match.
Lisa Jali 1985-07-07T00:00:00 9 Exact match.

Address Score

House Number House Name Flat Street Post Code Score Recommendation
Synamon Bangor Road LL551LN 1 No match - typically you would reject this.
Cae Synamon Bangor R LL551LN 2 Possible match - typically you would reject this.
Caer Synamon Bangor Road LL550LN 5 Probable match.
Cae Synamon Bangor Road LL550LN 6 Probable match.
Cae Synamon Bangor Road LL551LN 7 Highly probable match.
Cae Synamon Bangor Road LL551LN 7 Highly probable match.
Cae Synamon Bangor Roa LL551LN 8 Highly probable match.
Cae Synamon Bangor Road LL551LN 9 Exact match.

Status Codes

Code Description
Open The bank account exists and is open.
Closed The bank account is closed.
Deceased The bank account belonged to someone who is deceased.
NonExistant The bank account does not exist.
NotSingle The bank account is open but not registered to a single person and may be a joint account.
NoMatch The bank account could not be matched with our records.
NoPersonalOrAddressDataAvailable No personal or address data was available for us to check the supplied details against.
ErrorInConditions An error warning was encountered - see the condition error codes.
ErrorInProcessingRequest An error was encountered while processing the request.

Condition codes

When conditions are returned, they contain a severity (either error, warning, or information), a code and a message. Below is a list of the error codes returned.

Condition error codes

Code Message Description
1 Sort code format is incorrect. This error is used by countries which have a single combined bank-branch code, such as sort code in the United Kingdom and the Republic of Ireland, or BLZ in Germany. The code contains the wrong number of digits or non-numeric characters (other than spaces or hyphens).
2 Bank code format is incorrect. This error is used by countries which have both a bank code and branch code or countries where only the bank details are validated.
3 Branch code format is incorrect. This error is used by countries which have both a bank code and branch code.
4 Account number format is incorrect. If the account number could be transposed, you get warning 1 instead of this error.
5 Check digit format is incorrect. This error is used by countries which have a separate check digit.
6 Bank or branch code is not in use. The bank-branch code format is correct but it is not allocated to an existing branch. This error is used by countries where the bank-branch code can be mapped to a specific branch, for example, sort code in the United Kingdom or the Republic of Ireland.
7 Modulus check has failed. Although the formats of the supplied fields are correct, one or more of them are incorrect.
8 Modulus check on bank code has failed. Although the formats of the supplied fields are correct, one or more of them are incorrect.
9 Modulus check on account number has failed. Although the formats of the account details and check digits are correct, the modulus check on the account number failed. Therefore one or both of the account number and check digits are incorrect.
11 Sort code has been closed. Used when the branch has closed and there is no redirected branch.
12 Sort code has been transferred. This branch has been closed and the accounts have been redirected to another branch.
13 Bank has been closed. You will not get this error if the bank has been transferred.
14 Bank has been transferred. The bank has been closed and the accounts have been redirected to another bank.

Condition warning codes

Code Message Description
1 Account details were not in standard form and have been transposed. The conversion is performed according to rules for the issuing institution, for example converting all letters to upper case, removing separators, or by padding, typically with zeroes, to a fixed width. This is the standard message we return when any of the account details (including the bank and branch details) have been transposed to the format needed to transmit to the ACH (Automated Clearing House).
2 Modulus check algorithm is unavailable for these account details. We cannot confirm the validity of this account number, only the format can be checked. Manually reconfirm the account details before continuing. Typically, you should not treat this condition as an error.
3 Account number does not use a modulus check algorithm. This warning occurs if we have identified that modulus checking is not performed on this account.
4 Sort code is due to close - there is a close date set for this branch after the current system date. If this is a one-off payment or Direct Debit collection before the closure date on an existing account it is unlikely to be rejected. However, reject any details that are creating a regular Direct Debit.
5 Account does not support Direct Debit transactions. If the details are to create a Direct Debit instruction, reject the details. For other transactions, such as credits, ignore this warning.
6 Sort code does not support Direct Debit transactions. If the details are to create a Direct Debit instruction, reject the details. For other transactions, such as credits, ignore this warning.
7 Account does not support Direct Credit transactions. If the details are to create a Direct Credit instruction, reject the details. For other transactions, such as debits, ignore this warning.
8 Sort code does not support Direct Credit transactions. For debits this should not cause a problem. However, for credits either contact the branch or reject the details.
11 Sort code is due to be transferred The branch is due to close and all accounts are transferring to another branch at a date after the current system date.
12 BIC information not available. Returned when we do not have any specific BIC information for the branch and cannot determine whether the BIC is valid.
13 IBAN cannot be reliably formed. This warning is returned when we cannot form a reliable IBAN because some of the information needed is ambiguous.
14 BIC is for test or training only. If the details entered are not for a test or training record, reject the details.
15 BIC is not connected to the SWIFT network. If the details are to create a SWIFT payment or return SWIFT information, reject the details. Otherwise, you can ignore this warning.
16 IBAN cannot be formed because the account number has too many characters. If you need the IBAN, reject the details. Otherwise, you can ignore this warning.
17 Unable to decompose the IBAN therefore the generated details may not be correct. If you need the bank or branch code, you should validate the returned details. Otherwise ignore this message.
26 Account is a foreign currency account. If this is a domestic payment in the local currency, reject the details. Otherwise, you can ignore this warning.
27 Unable to validate branch details. This is returned when we do not include branch level information for these countries. We check the format of the branch code, and perform any modulus checks.
28 Branch not found, head office data returned. This is returned when we do not have branch level information for these account details. The relevant head office information is returned instead.
64 Account is a Foreign Currency account. This account cannot be modulus checked. Reject the details if you should not be using Foreign Currency accounts for your application.
65 Collection account requires a reference or roll account number. The account requires a reference or roll number to debit or credit the account. Check the details are correct, and if so, determine the roll number required.
67 Sort code does not support AUDDIS transactions. For AUDDIS instructions either contact the branch or reject the details.
70 Sort code does not support Claims for Unpaid Cheque transactions. If this limitation is a problem for your application, reject the details.
72 Sort code does not support Building Society Credit transactions. If this limitation is a problem for your application, reject the details.
73 Sort code does not support Dividend Interest Payment transactions. If this limitation is a problem for your application, reject the details.
74 Account does not support Claims for Unpaid Cheque transactions. If this limitation is a problem for your application, reject the details.
76 Account does not support Building Society Credit transactions. If this limitation is a problem for your application, reject the details.
77 Account does not support Dividend Interest Payment transactions. If this limitation is a problem for your application, reject the details.
78 Account does not support AUDDIS transactions. For AUDDIS instructions either contact the branch or reject the details.
79 Sort code does not support account switching. If this limitation is a problem for your payments, reject the details.
80 Sort code supports partial account switching only. If this limitation is a problem for your payments, reject the details.
81 Sort code does not support Bacs transactions. This branch is closed to Bacs transactions but may accept other types of transactions. If this limitation is a problem for your payments, reject the details.
82 This bank branch will be closing for Bacs clearing within 30 days. If this limitation is a problem for your payments, reject the details. The branch may still be accepting other types of transactions.

Warning conditions only used for SEPA data

Code Message Description
18 Branch is not SEPA compliant for Credit Transfers (CT). If this is a SEPA transfer, reject the details. Otherwise, you can ignore this warning.
19 Branch will cease to be SEPA compliant for Credit Transfers (CT) within 30 days. If this is a one-off SEPA Credit Transfer it is unlikely to be rejected. However, you should reject the details because they could be wrong in the future.
20 Branch is not SEPA compliant for Direct Debits (DD). If this is a SEPA payment, reject the details. Otherwise, you can ignore this warning.
21 Branch will cease to be SEPA compliant for Direct Debits (DD) within 30 days. If this is a one-off SEPA Direct Debit it is unlikely to be rejected. However, you should reject the details because they could be wrong in the future.
47 Branch is not SEPA compliant for Business Direct Debits. If this is a SEPA payment, reject the details. Otherwise, you can ignore this warning.
48 Branch will cease to be SEPA compliant for Business Direct Debits within 30 days. If this is a one-off SEPA Business Direct Debit it is unlikely to be rejected. However, you should reject the details because they could be wrong in the future.

Information conditions

Code Message Description
2 Branch is not located within the parent country. For example, it could be an Irish bank located in England.
3 BIC matched on SWIFT Branch BIC. BIC matched on SWIFT Branch BIC.
4 BIC matched on SWIFT Routing BIC. BIC matched on SWIFT Routing BIC.
5 BIC matched on Branch BIC. BIC matched on Branch BIC.
6 BIC matched on the IBAN BIC. BIC matched on the IBAN BIC.
7 BIC matched on the SSI BIC. BIC matched on the SSI BIC.
64 BIC matched on CHAPS Euro Routing BIC. BIC matched on CHAPS Euro Routing BIC.
65 BIC matched on CHAPS Sterling Routing BIC. BIC matched on CHAPS Sterling Routing BIC.
66 The Faster Payments status is not specified. The Faster Payments status is not specified.
Request Body schema: application/json
required

JSON object of type PersonalBaoRequest

FirstName
required
string

First name.

Surname
required
string

Surname.

Dob
string <date-time>

Date of birth in yyyy-mm-ddT00:00:00 format: optional, but without a DOB the highest personal score returned is a 7.

ApiKey
required
string

The API key, fixed format and provided at sign up.

SortCode
required
string

Sort code.

AccountNumber
required
string

Account number.

RollNumber
string

Bank roll number.

Street
string

Street.

City
string

City.

Postcode
required
string

Postcode.

HouseNumber
string

House number. Data is required in at least one of HouseNumber, HouseName or Flat.

HouseName
string

House name. Data is required in at least one of HouseNumber, HouseName or Flat.

Flat
string

Flat name. Data is required in at least one of HouseNumber, HouseName or Flat.

Responses

Request samples

Content type
application/json
{
  • "FirstName": "Lisa",
  • "Surname": "Jali",
  • "Dob": "1985-07-07",
  • "ApiKey": "xxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  • "SortCode": "070116",
  • "AccountNumber": "00007338",
  • "Street": "Bangor Road",
  • "Postcode": "LL55 1LN",
  • "HouseNumber": "",
  • "HouseName": "Cae Synamon",
  • "Flat": ""
}

Response samples

Content type
{
  • "PersonalDetailsScore": 9,
  • "AddressScore": 9,
  • "Status": "Open",
  • "Conditions": [
    ]
}

Verify payer’s business account

Verifies if a UK business bank account is associated with a given business (the payer).

Example data and scores

Please see the Verify payer's personal account call within Payer Bank Account Verification (DD) for details about the personal score, address score, status and conditions.

Request Body schema: application/json
required

JSON object of type BusinessBaoRequest

CompanyName
required
string

Company name.

RegistrationNumber
string

House registration number uniquely identifying a company within a country for tax purposes.

CompanyType
string

Company type, either L - limited, U – unknown or D - non-limited.

ProprietorFirstName
string

Proprietor's first name.

ProprietorSurname
string

Proprietor's surname.

ProprietorDob
string <date-time>

Proprietor's date of birth, format yyyy-mm-ddT00:00:00.

ApiKey
required
string

The API key, fixed format and provided at sign up.

SortCode
required
string

Sort code.

AccountNumber
required
string

Account number.

RollNumber
string

Bank roll number.

Street
string

Street.

City
string

City.

Postcode
required
string

Postcode.

HouseNumber
string

House number. Data is required in at least one of HouseNumber, HouseName or Flat.

HouseName
string

House name. Data is required in at least one of HouseNumber, HouseName or Flat.

Flat
string

Flat name. Data is required in at least one of HouseNumber, HouseName or Flat.

Responses

Request samples

Content type
application/json
{
  • "CompanyName": "Vitruvius Stonework Limited",
  • "RegistrationNumber": "60674010",
  • "ProprietorFirstName": "Abbas",
  • "ProprietorSurname": "Howes",
  • "ProprietorDob": "1970-11-09",
  • "ApiKey": "xxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  • "SortCode": "404745",
  • "AccountNumber": "51406795",
  • "Street": "Charlmont Road",
  • "Postcode": "SW179AB",
  • "HouseNumber": "1",
  • "HouseName": "Springbank Chapelgreen"
}

Response samples

Content type
{
  • "CompanyNameScore": 9,
  • "RegistrationNumberMatch": "Match",
  • "CompanyNameAndAddressScore": 9,
  • "CompanyTypeMatch": "Match",
  • "ProprietorDetailsScore": 9,
  • "Status": "Open",
  • "Conditions": [
    ]
}

Payee Bank Account Verification

Verify account details that a payer provides to protect your goods and services against potential fraudsters. The API allows you to search for addresses, retrieve a formatted address, verify a payee’s name returning a match decision or score and verify a payee’s name and address returning a match score.

Search for addresses

Searches for a list of addresses that match a given input criteria. Each part of the address must be separated by a comma, e.g. Cae Synamon, LL55 1LN.

Request Body schema: application/json
required

JSON object of type PostSearchAddress

ApiKey
required
string

The API key, fixed format and provided at sign up.

Query
required
string

The free text format of the address to search for.

Take
required
string

The number of records to return.

Responses

Request samples

Content type
application/json
{
  • "ApiKey": "xxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  • "Query": "LL551LN",
  • "Take": "25"
}

Response samples

Content type
{
  • "TotalMatches": 4,
  • "Count": 4,
  • "Results": [
    ]
}

Get a formatted address

Retrieves a formatted address using a unique identifier obtained from the Search for addresses call.

Note: The content and format of the identifiers can change without notice so should not be cached.

Request Body schema: application/json
required

JSON object of type PostGetFormattedAddress

ApiKey
required
string

The API key, fixed format and provided at sign up.

Id
required
string

Id of the address obtained from the Search for addresses call. The format and content of the Id can change without notice and should not be cached.

Responses

Request samples

Content type
application/json
{
  • "ApiKey": "xxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  • "Id": "MRF|fc546cfe-ccb0-4cd7-b6a7-960b089af5b5|7.730iOMRFEAjjBwAAAAABAwEAAAAAiNYMkABhIAIAAAAAAAAAAAD..2QAAAAA.....wAAAAAAAAAAAAAAAAAAAENhZSBTeW5hbW9uLExMNTUgMUxOAAAAAAA-$20"
}

Response samples

Content type
{
  • "AddressKey": "MRF|fc546cfe-ccb0-4cd7-b6a7-960b089af5b5|7.730iOMRFEAjjBwAAAAABAwEAAAAAiNYMkABhIAIAAAAAAAAAAAD..2QAAAAA.....wAAAAAAAAAAAAAAAAAAAENhZSBTeW5hbW9uLExMNTUgMUxOAAAAAAA-$20",
  • "Organisation": "",
  • "Flat": "",
  • "HouseName": "Cae Synamon",
  • "HouseNumber": "",
  • "Street": "Bangor Road",
  • "Locality": "CAERNARFON",
  • "PostalCode": "LL55 1LN",
  • "Country": "UNITED KINGDOM",
  • "IsBusinessAddress": false
}

Verify payee’s name with a match decision

Verifies if a UK personal bank account is associated with a given payee name and returns a match decision.

Example data and scores

First Name Surname DOB Sort Code Account Number Outcome MS, AS
Lisa Jali 1985-07-07T00:00:00 070116 00007338 match, Open
Ashely Marma 1968-04-10T00:00:00 070116 00003036 match, Open
Tanya Pealing 1984-10-20T00:00:00 070116 00003554 noMatch, Closed
Maureen Borton 1984-11-21T00:00:00 070116 00065090 noMatch, Deceased
Loveina Tutton 1969-03-24T00:00:00 070116 00003072 match, NotSingle

Outcome legend

Code Meaning Description
MS Match Status indicates how closely the payee information has been matched, either match, possibleMatch or noMatch
AS Account Status Bank account status.

Please see the Verify payer's personal account call within Payer Bank Account Verification (DD) for details about the personal score, address score, status and conditions.

Request Body schema: application/json
required
PossibleMatchMin
integer <int32>

The lowest value at which a possible match will be returned in the 0- 9 range, where the default value is 4. If supplied, MatchMin must also be supplied, and the value must be less than MatchMin.

MatchMin
integer <int32>

The lowest value at which a match will returned in the 0 - 9 range, where the default value is 6. If supplied, PossibleMatchMin must also be supplied, and the value must be greater than PossibleMatchMin.

FirstName
required
string

First name.

Surname
required
string

Surname.

Dob
string <date-time>

Date of birth in yyyy-mm-ddT00:00:00 format: optional, but without a DOB the highest personal score returned is a 7.

ApiKey
required
string

The API key, fixed format and provided at sign up.

SortCode
required
string

Sort code.

AccountNumber
required
string

Account number.

Responses

Request samples

Content type
application/json
{
  • "PossibleMatchMin": 5,
  • "MatchMin": 6,
  • "FirstName": "Lisa",
  • "Surname": "Jali",
  • "Dob": "1985-07-07",
  • "ApiKey": "xxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  • "SortCode": "070116",
  • "AccountNumber": "00007338"
}

Response samples

Content type
{
  • "MatchStatus": "match",
  • "Conditions": [ ],
  • "AccountStatus": "Open"
}

Verify payee’s name with a match score

Verifies if a UK personal bank account is associated with a given payee name and address and returns a match score.

Example data and scores

First Name Surname DOB Sort Code Account Number Outcome MS, S
Lisa Jali 1985-07-07T00:00:00 070116 00007338 9, Open
Ashely Marma 1968-04-10T00:00:00 070116 00003036 9, Open
Tanya Pealing 1984-10-20T00:00:00 070116 00003554 0, Closed
Maureen Borton 1984-11-21T00:00:00 070116 00065090 0, Deceased
Loveina Tutton 1969-03-24T00:00:00 070116 00003072 9, NotSingle

Outcome legend

Code Meaning Description
MS Match score 0 to 9, indicates how closely the payee information has been matched.
S Status Bank account status.

Please see the Verify payer's personal account call within Payer Bank Account Verification (DD) for details about the personal score, address score, status and conditions.

Request Body schema: application/json
required

JSON object of type PostVerifyPayeeRequest

FirstName
required
string

First name.

Surname
required
string

Surname.

Dob
string <date-time>

Date of birth in yyyy-mm-ddT00:00:00 format: optional, but without a DOB the highest personal score returned is a 7.

ApiKey
required
string

The API key, fixed format and provided at sign up.

SortCode
required
string

Sort code.

AccountNumber
required
string

Account number.

Responses

Request samples

Content type
application/json
{
  • "FirstName": "Lisa",
  • "Surname": "Jali",
  • "Dob": "1985-07-07",
  • "ApiKey": "xxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  • "SortCode": "070116",
  • "AccountNumber": "00007338"
}

Response samples

Content type
{
  • "MatchScore": 9,
  • "Conditions": [ ],
  • "AccountStatus": "Open"
}

Verify payee’s name and address with a match score

Verifies if a UK personal bank account is associated with a given payee name and address combination and returns a match score.

Example data and scores

Please see the Verify payer's personal account call within Payer Bank Account Verification (DD) for details about the personal score, address score, status and conditions.

Request Body schema: application/json
required

JSON object of type PersonalBaoRequest

FirstName
required
string

First name.

Surname
required
string

Surname.

Dob
string <date-time>

Date of birth in yyyy-mm-ddT00:00:00 format: optional, but without a DOB the highest personal score returned is a 7.

ApiKey
required
string

The API key, fixed format and provided at sign up.

SortCode
required
string

Sort code.

AccountNumber
required
string

Account number.

RollNumber
string

Bank roll number.

Street
string

Street.

City
string

City.

Postcode
required
string

Postcode.

HouseNumber
string

House number. Data is required in at least one of HouseNumber, HouseName or Flat.

HouseName
string

House name. Data is required in at least one of HouseNumber, HouseName or Flat.

Flat
string

Flat name. Data is required in at least one of HouseNumber, HouseName or Flat.

Responses

Request samples

Content type
application/json
{
  • "FirstName": "Lisa",
  • "Surname": "Jali",
  • "Dob": "1985-07-07",
  • "ApiKey": "xxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  • "SortCode": "070116",
  • "AccountNumber": "00007338",
  • "Street": "Bangor Road",
  • "Postcode": "LL55 1LN",
  • "HouseNumber": "",
  • "HouseName": "Cae Synamon",
  • "Flat": ""
}

Response samples

Content type
{
  • "PersonalDetailsScore": 9,
  • "AddressScore": 9,
  • "Status": "Open",
  • "Conditions": [
    ]
}

Information

Obtain version and licensing information.

Get version

Retrieves the version number.

Request Body schema: application/json
required

The API key, fixed format and provided at sign up.

ApiKey
required
string

The API key, fixed format and provided at sign up.

Responses

Request samples

Content type
application/json
{
  • "ApiKey": "xxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx"
}

Response samples

Content type
"0.0.0.0"

Get licensed info

Retrieves licensing information for the current user.

Request Body schema: application/json
required

The API key, fixed format and provided at sign up.

ApiKey
required
string

The API key, fixed format and provided at sign up.

Responses

Request samples

Content type
application/json
{
  • "ApiKey": "xxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx"
}

Response samples

Content type
{
  • "Name": null,
  • "Identifier": null,
  • "Expires": "9999-12-31",
  • "LicencedItems": [
    ]
}

Confirmation of payee

Confirmation of payee

Verifies if a sort code and account numbers is associated with a given person or business.

Note: This API call is still supported but only for existing systems and for a limited time. We strongly recommend that you update your systems to use our new API call to avoid any loss in service. Please contact your Bottomline account manager for more details.

Example data

Name Sort Code Account Number Account Type Secondary Information Match Name Reason
MISS SAMANTHA SMYTHE 999996 00000001 Personal true
SAM SMYTHE 999996 00000001 Personal false MISS SAMANTHA SMYTHE Name is a close match
MR DAVID ATKINSON 999996 00000002 Personal true
DAVID ATKINSON 999996 00000002 Business false MR DAVID ATKINSON Name matches but this is a personal account not a business account
DAVED ATKINSON 999996 00000002 Business false MR DAVID ATKINSON Name is a close match but this is a personal account not a business account
BRIDGFORD GARDENING 999996 00000011 Business true
BRIDGFORD GARDENING 999996 00000011 Personal false Name matches but this is a business account not a personal account
BRIDGEFORD GARDENING 999996 00000011 Personal false BRIDGFORD GARDENING Name is a close match but this is a business account not a personal account
SWTCHED ACCOUNT 999996 00000016 Personal false This account has been switched using CASS
TOWER STORES 999996 00000063 Business false This account has been switched using CASS
NOT SUPPORTED 999996 00000062 Personal false CoP checks aren’t supported for this account
JAMES BROWN 999996 00000099 Personal false Account does not exist
JOHNSON LOGISTICS 999996 00000048 Business false JOHNSON LOGISTICS The account holder has opted out of CoP
Request Body schema: application/json
required

JSON object of type PostCop

ApiKey
required
string

The API key, fixed format and provided at sign up.

SortCode
required
string(^[0-9]{6,6}$)

The sort code of the bank account to verify.

AccountNumber
required
string(^[0-9]{8,8}$)

The account number of the bank account to verify.

AccountHoldersName
required
string

The full name of the account holder to verify.

SecondaryIdentification
string

Any secondary information required to verify the account holder's name.

AccountType
required
string

Account type, must be either Business or Personal.

Responses

Request samples

Content type
application/json
{
  • "ApiKey": "xxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  • "SortCode": "999996",
  • "AccountNumber": "00000001",
  • "AccountHoldersName": "Miss Samantha Smythe",
  • "AccountType": "Personal"
}

Response samples

Content type
{
  • "OriginalName": "Miss Samantha Smythe",
  • "Name": "",
  • "Match": true,
  • "Reason": "",
  • "ReasonCode": ""
}