Confirmation of Payee Outbound (UK)

Introduction

Improve customer experience and decrease misdirected UK payments by verifying the beneficiary's bank account details before creating or updating a beneficiary.

This guide is designed to help you verify a beneficiary's bank account details for outbound local GBP payments, via the Verify Beneficiary Account API, our Confirmation of Payee service. Verifying beneficiaries helps avoid payments being sent to the wrong account and adds another layer of protection in the fight against fraud and scams.

For clients under the Sponsored and Treasury service model and contracted with The Currency Cloud Limited, it is a mandatory requirement to integrate with this API if you offer local GBP payments to your end-customers.

Beta notice:

Please be aware that this API is in beta. Some response codes and reasons may change during this period. We will always provide at least 10 days advance notice before implementing any changes that may be breaking during the beta period.

What is it?

The Verify Beneficiary Account API can be used to verify a beneficiary's bank account number and, in some markets, check the name of the individual or company provided.

How does it work?

1. 01The end-customer inputs the beneficiary's account details.
2. 02Currencycloud forwards this request to the beneficiary's bank or cross-references it against a dataset.
3. 03For the UK market, we return a response displaying the result of the verification with the following fields: answer, actual_name, reason_code, reason and reason_type.

Who is an end-customer, and where does the verification need to take place?

In most cases, an end-customer will be an individual or business that we contract with and provide regulated payment services to. The requirement is that the end-customer must be able to receive a verification response before they proceed to create the beneficiary on your interface. For example, if you are an accounts payable platform, the end-customer using the platform must be able to verify the beneficiary details before creating the beneficiary and submitting the invoice payment.

However, in some use-cases, the end-customer cannot create a beneficiary but you are still technically in scope to provide this service. An example of this might be a Wealthtech that automatically populates the same account details used to pay-in. If this applies to you, please consult your Customer Success Manager and Solutions consultant and we'll work with you to understand your usecase.

Availability

We currently offer the Verify Beneficiary Account API in the UK in Beta. We will support more countries in the future. Contact customer support or your Customer Success Manager to find out more.

Step 1: Login

Please refer to the Authentication guide for instructions for starting a new API session. Make sure your Contact ID is enabled to access this product in our Demo environment.

Step 2: Verify Beneficiary

Requests

To verify a beneficiary's bank account details in the UK, make a POST request to the Verify Beneficiary Account endpoint.

The request body includes the following parameters: 

Content-Type: multipart/form-data

Example Request:

{
 "payment_type": "regular",
 "bank_country": "GB",
 "currency": "GBP",
 "account_number": "73515966",
 "beneficiary_entity_type": "individual",
 "beneficiary_company_name": null,
 "beneficiary_first_name": "Ricardo",
 "beneficiary_last_name": "Sousa",
 "routing_code_type_1": "sort_code",
 "routing_code_value_1": "015561,
 "routing_code_type_2": null,
 "routing_code_value_2": null,
 "bic_swift": null,
 "iban": null,
 "secondary_reference_data": null
}

Responses

Please note that you must disable you interface's ability to cache data so that no end-customer is able to access data previously obtained under a Confirmation of Payee request without undertaking a further Confirmation of Payee request.

Example Responses

200
{
  "answer": "full_match",
  "actual_name": "Ricardo Sousa",
  "reason_code": "AV100",
  "reason": "Full match.",
  "reason_type": "okay"
}

200
{
  "answer": "close_match",
  "actual_name": "Ricardo Sous",
  "reason_code": "AV300",
  "reason": "String is a close match to the account name.",
  "reason_type": "warning"
}

The following parameters are included in the JSON response body:

Guidance on reflecting API responses in the UI

When integrating with our Verify Beneficiary Account API, it is important to handle the various responses effectively in order to provide a seamless user experience. Below are suggestions for implementing each response in your interface, with copy and UX handling suggestions.

Reminder: If you're a 'Sponsored' or 'Treasury' model client that contracts with The Currency Cloud Limited using the API then you must include the beneficiary account verification step as part of your UK beneficiary creation flow before paying out to a beneficiary via our create payment API.

1. AV100 (Full match)

Request:

{
  "payment_type": "regular",
  "bank_country": "GB",
  "currency": "GBP",
  "account_number": "73515966",
  "beneficiary_entity_type": "individual",
  "beneficiary_company_name": null,
  "beneficiary_first_name": "Ricardo",
  "beneficiary_last_name": "Sousa",
  "routing_code_type_1": "sort_code",
  "routing_code_value_1": "015561",
  "routing_code_type_2": null,
  "routing_code_value_2": null,
  "bic_swift": null,
  "iban": null,
  "secondary_reference_data": null
}

Response:

200
{
  "answer": "full_match",
  "actual_name": "Ricardo Sousa",
  "reason_code": "AV100",
  "reason": "Full match.",
  "reason_type": "okay"
}

API Reason: Full Match

Description: The beneficiary's bank was able to confirm a full name and account match.

Handling: The end-customer can proceed with creating the beneficiary.

UI Suggestion:

2. AV300 (Close match)

Request:

{
  "payment_type": "regular",
  "bank_country": "GB",
  "currency": "GBP",
  "account_number": "73515966",
  "beneficiary_entity_type": "individual",
  "beneficiary_company_name": null,
  "beneficiary_first_name": "Ricardo",
  "beneficiary_last_name": "Sous",
  "routing_code_type_1": "sort_code",
  "routing_code_value_1": "015561",
  "routing_code_type_2": null,
  "routing_code_value_2": null,
  "bic_swift": null,
  "iban": null,
  "secondary_reference_data": null
}

Response:

200
{
        "answer": "close_match",
        "actual_name": "Ricardo Sousa",
        "reason_code": "AV300",
        "reason": "String is a close match to the account name.",
        "reason_type": "warning"
}

API Response: AV300

Description: This is a close match. Display a message highlighting the error, and the risk of proceeding with creation. The actual account_name will be provided in the response.

Handling: In the event of a close match, display the actual_name to the end-customer. Consider providing a call to action or button to nudge the user into submitting the correct details. This reduces cognitive load and makes it easier for them to adjust their choice.

In the event of a close match, it's important that you explain the problem and solution clearly. However, if the end-customer decides to proceed, present a dialogue box with a secondary warning indicating that they do so at their own discretion and risk.

UI Suggestion:

3. AV201 (No match)

Request:

{
  "payment_type": "regular",
  "bank_country": "GB",
  "currency": "GBP",
  "account_number": "11235813",
  "beneficiary_entity_type": "individual",
  "beneficiary_company_name": null,
  "beneficiary_first_name": "Ricardo",
  "beneficiary_last_name": "Smith",
  "routing_code_type_1": "sort_code",
  "routing_code_value_1": "314159",
  "routing_code_type_2": null,
  "routing_code_value_2": null,
  "bic_swift": null,
  "iban": null,
  "secondary_reference_data": null
}

Response:

200
{
  "answer": "no_match",
  "actual_name": null,
  "reason_code": "AV201",
  "reason": "String does not match the account name.",
  "reason_type": "rejected"
}

API Response: AV201

Response: String does not match the account name. 

Handling: There is no match. Display a negative notice highlighting the error. The actual_name will not be provided in the response. Create a button to give the end-customer the choice to edit the account details or keep what they entered.

In the event of a no match, it's important that you explain the problem clearly. However, if the end-customer decides to proceed, present a dialogue box with a secondary warning indicating that they do so at their own discretion and risk.

UI Suggestion:

Reason codes

This section provides a full list of reason codes along with recommendations for reflecting them on your User Interface.

The style and tone of the Currencycloud Direct platform serves as the basis for our copy and handling suggestions. Although it's not necessary to match this exactly, your integration should closely mirror it to maintain a consistent user experience.

Successful Responses (HTTP 200)

Answer	Reason Code	Reason	Reason Type	Suggested Copy	How to handle
full_match	AV100	Full match	Okay	Beneficiary details confirmed The details entered for the beneficiary have been confirmed as an exact match. Please proceed with beneficiary creation. [Back] [Cancel] [Create Beneficiary]	Display a positive notice to end-customer, indicating successful verification.
no_match	AV200	There is no account with the given account number.	Rejected	Unable to confirm the account details The account number and sort code provided for the beneficiary do not match those on record. Please check the information you have entered and click 'Back' to update if necessary, or click 'Create Beneficiary' if you are sure the details are correct. [Back] [Cancel] [Create beneficiary] Are you sure you want to continue? Paying this person or business may lead to your money being sent to the wrong account. We may not be able to recover the money for you. [Cancel] [Continue Anyway]	1. Display a negative notice highlighting the error. 2. Create a button to give the end-customer the choice to go Back, Cancel or Create Beneficiary. 3. If the user clicks/taps 'Back' a new API request must be submitted to check the new details. 4. If the user clicks/taps 'Create Beneficiary', end-customer should receive a secondary warning via a dialogue box.
no_match	AV201	String does not match the account name.	Rejected	No match for beneficiary name The name you have provided for the beneficiary does not match that on record. Please check the information you have entered and click 'Back' to update if necessary, or click 'Create Beneficiary' if you are sure the details are correct. [Back] [Cancel] [Create Beneficiary] Are you sure you want to continue? Paying this person or business may lead to your money being sent to the wrong account. We may not be able to recover the money for you. [Cancel] [Continue Anyway]	1. Display a negative notice highlighting the error. 2. Create a button to give the end-customer the choice to go Back, Cancel or Create Beneficiary. 3. If the user clicks/taps 'Back' a new API request must be submitted to check the new details. 4. If the user clicks/taps 'Create Beneficiary', end-customer should receive a secondary warning via a dialogue box.
no_match	AV202 AV203 AV204 AV205	Unable to check account details.	Rejected	Unable to check provided details It has not been possible to check the beneficiary details you have provided. Please check the information you have entered and click 'Back' to update if necessary, or click 'Create Beneficiary' if you are sure the details are correct. [Back] [Cancel] [Create Beneficiary] Are you sure you want to continue? Paying this person or business may lead to your money being sent to the wrong account. We may not be able to recover the money for you. [Cancel] [Continue Anyway]	1. Display a negative notice highlighting the error. 2. Create a button to give the end-customer the choice to go Back, Cancel or Create Beneficiary. 3. If the user clicks/taps 'Back' a new API request must be submitted to check the new details. 4. If the user clicks/taps 'Create Beneficiary', end-customer should receive a secondary warning via a dialogue box.
no_match	AV206	Invalid secondary customer reference data.	Rejected	No match for provided details The reference details you have provided for the beneficiary do not match those on record. Please check the information you have entered and click 'Back' to update if necessary, or click 'Create Beneficiary' if you are sure the details are correct. [Back] [Cancel] [Create Beneficiary] Are you sure you want to continue? Paying this person or business may lead to your money being sent to the wrong account. We may not be able to recover the money for you. [Cancel] [Continue Anyway]	1. Display a negative notice highlighting the error. 2. Create a button to give the end-customer the choice to go Back, Cancel or Create Beneficiary. 3. If the user clicks/taps 'Back' a new API request must be submitted to check the new details. 4. If the user clicks/taps 'Create Beneficiary', end-customer should receive a secondary warning via a dialogue box.
no_match	AV207	Unable to check account details.	Rejected		Using data not included in our test pack results in this response in our demo environment. If this occurs in the production environment, please report to [email protected].
close_match	AV300	String is a close match to the account name	Warning	Incorrect beneficiary name The details you have provided for the beneficiary closely match those on record, however the name is '[actual_name]'. Please check the information you have entered and click 'Back' to update the Beneficiary Name to '[actual_name]' if necessary, or click 'Create Beneficiary' if you are sure the details are correct. [Back] [Cancel] [Create Beneficiary] (disabled until selection is made) Are you sure you want to continue? Paying this person or business may lead to your money being sent to the wrong account. We may not be able to recover the money for you. [Cancel] [Continue Anyway]	1. Display a negative notice highlighting the error. 2. The actual_name will be provided. Wrap the provided copy around the [actual_name]. 3. Create a button to give the end-customer the choice to go Back, Cancel or Create Beneficiary. 4. If the user clicks/taps 'Back' a new API request must be submitted to check the new details. 5. If the user clicks/taps 'Create Beneficiary', end-customer should receive a secondary warning via a dialogue box.
close_match	AV301	String is a close match to the account name. The type of account is Business when Personal was indicated in the request.	Warning	Incorrect company name The details you have provided for the beneficiary closely match those on record, however the company name is '[actual_name]'. Please check the information you have entered and click 'Back' to update the Company Name to '[actual_name]' if necessary, or click 'Create Beneficiary' if you are sure the details are correct. [Back] [Cancel] [Create Beneficiary] (disabled until selection is made) Are you sure you want to continue? Paying this person or business may lead to your money being sent to the wrong account. We may not be able to recover the money for you. [Cancel] [Continue Anyway]	1. Display a negative notice highlighting the error. 2. The actual_name will be provided. Wrap the provided copy around the [actual_name]. 3. Create a button to give the end-customer the choice to go Back, Cancel or Create Beneficiary. 4. If the user clicks/taps 'Back' a new API request must be submitted to check the new details. 5. If the user clicks/taps 'Create Beneficiary', end-customer should receive a secondary warning via a dialogue box.
close_match	AV302	String is a close match to the account name. The type of account is Personal when Business was indicated in the request.	Warning	Incorrect beneficiary name The details you have provided for the beneficiary closely match those on record, however the name is '[actual_name]'. Please check the information you have entered and click 'Back' to update the Beneficiary Name to '[actual_name]' if necessary, or click 'Create Beneficiary' if you are sure the details are correct. [Back] [Cancel] [Create Beneficiary] (disabled until selection is made) Are you sure you want to continue? Paying this person or business may lead to your money being sent to the wrong account. We may not be able to recover the money for you. [Cancel] [Continue Anyway]	1. Display a negative notice highlighting the error. 2. The actual_name will be provided. Wrap the provided copy around the [actual_name]. 3. Create a button to give the end-client the choice to go Back, Cancel or Create Beneficiary. 4. If the user clicks/taps 'Back' a new API request must be submitted to check the new details. 5. If the user clicks/taps 'Create Beneficiary', the end-customer should receive s secondary warning via a dialogue box.
close_match	AV303	String is a match to the account name, but the type of account is Business when Personal was indicated in the request.	Warning	Incorrect beneficiary type The details you have provided for the beneficiary closely match those on record, however the beneficiary is recognised as a company not an individual. Please check the information you have entered and click 'Back' to update the Beneficiary Type to 'Company' if necessary, or click 'Create Beneficiary' if you are sure the details are correct. [Back] [Cancel] [Create Beneficiary] Are you sure you want to continue? Paying this person or business may lead to your money being sent to the wrong account. We may not be able to recover the money for you. [Cancel] [Continue Anyway]	1. Display a negative notice highlighting the error. 2. Create a button to give the end-customer the choice to go Back, Cancel or Create Beneficiary. 3. If the user clicks/taps 'Back' a new API request must be submitted to check the new details. 4. If the user clicks/taps 'Create Beneficiary', the end-customer should receive a secondary warning via a dialogue box.
close_match	AV304	String is a close match to the account name, but the type of account is Personal when Business was indicated in the request.	Warning	Incorrect beneficiary type The details you have provided for the beneficiary closely match those on record, however it is recognised as an individual not a company. Please check the information you have entered and click 'Back' to update the Beneficiary Type to 'Individual' if necessary, or click 'Create Beneficiary' if you are sure the details are correct. [Back] [Cancel] [Create Beneficiary] Are you sure you want to continue? Paying this person or business may lead to your money being sent to the wrong account. We may not be able to recover the money for you. [Cancel] [Continue Anyway]	1. Display a negative notice highlighting the error. 2. Create a button to give the end-customer the choice to go Back, Cancel or Create Beneficiary. 3. If the user clicks/taps 'Back' a new API request must be submitted to check the new details. 4. If the user clicks/taps 'Create Beneficiary', end-customer should receive a secondary warning via a dialogue box.
close_match	AV305	Account has been switched to a different organisation.	Warning	Account has been switched The details you have provided for the beneficiary closely match those on record, however the account has been switched to a different organisation. Please check the information you have entered and click 'Back' to update if necessary, or click 'Create Beneficiary' if you are sure the details are correct. [Back] [Cancel] [Create Beneficiary] Are you sure you want to continue? Paying this person or business may lead to your money being sent to the wrong account. We may not be able to recover the money for you. [Cancel] [Continue Anyway]	1. Display a negative notice highlighting the error. 2. Create a button to give the end-customer the choice to go Back, Cancel or Create Beneficiary. 3. If the user clicks/taps 'Back' a new API request must be submitted to check the new details. 4. If the user clicks/taps 'Create Beneficiary', end-customer should receive a secondary warning via a dialogue box.

Technical Errors

HTTP 503 - Service Unavailable**

Error Code	Error Reason	Required Copy	How to handle
service_unavailable	Service is temporarily unavailable	Unable to check provided details It has not been possible to check the beneficiary details you have provided at this time. Please try creating the beneficiary again later, or click 'Create Beneficiary' if you are sure the details are correct. [Back] [Cancel] [Create Beneficiary] Are you sure you want to continue? Paying this person or business may lead to your money being sent to the wrong account. We may not be able to recover the money for you. [Cancel] [Continue Anyway]	Connection has failed 1. Display a negative notice highlighting the issue. 2. Introduce an internal retry mechanism, before presenting the error back to the user. 3. If the user clicks/taps 'Back to details, the end-customer goes back to the beneficiary creation screen. 4. A new request is required to check the new details. 5. If the user clicks/taps 'Continue Anyway', the end-customer should receive a secondary warning.

HTTP 400 - Bad Request

Required copy and handling requirements are not applicable for HTTP 400 errors as the end-customer should not be able to trigger these validations.

Step 3: Create or Update Beneficiary

After successfully verifying the details, you can set up a new beneficiary record or update an existing one using the Beneficiaries API. Make a POST request to the Create Beneficiary endpoint to create a new beneficiary or to the Update Beneficiary endpoint to update an existing one.

Remember, if there's a 'close match' during Account Verification and the user picks the account name from the response, you need to use those details when creating or updating a beneficiary.

If the beneficiary is successfully created or updated, the response message will contain the full details about the beneficiary as recorded in your Currencycloud account.

Note the beneficiary's unique ID (id). You'll need this to make a payment to the beneficiary.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "aea097c2-39e4-49b5-aaa6-c860ca55ca0b",
  "bank_account_holder_name": "Acme GmbH",
  "name": "Acme GmbH",
  "email": null,
  "payment_types": [
    "regular"
  ],
  "beneficiary_address": [],
  "beneficiary_country": "DE",
  "beneficiary_entity_type": null,
  "beneficiary_company_name": null,
  "beneficiary_first_name": null,
  "beneficiary_last_name": null,
  "beneficiary_city": null,
  "beneficiary_postcode": null,
  "beneficiary_state_or_province": null,
  "beneficiary_date_of_birth": null,
  "beneficiary_identification_type": null,
  "beneficiary_identification_value": null,
  "bank_country": "DE",
  "bank_name": "Test Bank Plc",
  "bank_account_type": null,
  "currency": "EUR",
  "account_number": null,
  "routing_code_type_1": null,
  "routing_code_value_1": null,
  "routing_code_type_2": null,
  "routing_code_value_2": null,
  "bic_swift": "COBADEFF",
  "iban": "[Sensitive data redacted]",
  "default_beneficiary": "false",
  "creator_contact_id": "1993263d-be07-42d4-b75b-ae4ea18bcb6c",
  "bank_address": [],
  "created_at": "2021-02-02T11:52:23+00:00",
  "updated_at": "2021-02-02T11:52:23+00:00",
  "beneficiary_external_reference": null
}

Step 4: Develop your User Journey

The following best practices are recommended when integrating Verify Beneficiary Account API into your application:

• Clear Messaging: Ensure that the message accompanying each response is succinct, informative, and user-friendly.

• Visual Feedback: Use visual elements such as icons, colours, and message banners to provide clear feedback to users.

• Error Handling: Implement robust error handling to gracefully deal with unexpected responses or errors from the Verify Beneficiary Account API.

• Accessibility: Design the UI to be accessible to all users, ensuring that response messages are perceivable and understandable.

By following these guidelines you can seamlessly integrate the Verify Beneficiary Account API responses with your interface, providing users with a smooth and intuitive experience when verifying beneficiary details.

Here is an example: