Bank account verification with open banking

Adyen's verification through bank report service uses Adyen's open banking gateway to retrieve bank account verification reports from third-party banks.

For example, you consider hiring an unregistered third-party individual on a contract-basis for services, such as food-delivery or as a courier. You want to make sure the person is who they say they are before you enter into an agreement with them for their services.

You can verify them through Account Information Service Providers (AISPs) such as Plaid or Tink. The third-party individual can authorize their bank to share a bank account verification report with you, which provides bank account ownership verification and Know Your Customer (KYC) verification quickly and securely.

Requirements

Before you begin, take into account the following requirements and preparations.

How it works

When you want to verify a third-party individual's bank account ownership through a redirect, use the following flow.

1. Make a request to the /routes generation endpoint to get a list of available account verification routes. Each route represents a possible connection path between the third-party individual and their bank. When the third-party individual successfully connects through one of these routes, you will receive a report code. Use the code to:

   • Request a bank account verification report.
   • Verify the third-party individual's identity using the information in the bank account verification report.

   The /routes generation endpoint dynamically compiles and returns a list of the most suitable AISPs available for account verification. The list is based on the location of the bank where the third-party individual (the external account holder) is registered. Note, the redirectUrl you provide is used to receive the report code, but it does not influence route selection.

   A report code is not guaranteed for every route. The third-party individual must successfully complete the bank connection flow for a code to be generated.

2. Redirect the third-party individual to the AISP's bank selection and authentication/authorization flow. After the third-party individual completes the authentication flow and authorizes their bank to generate and share a report, the merchant receives a report code (or error details). This report code or error details will be provided in the redirectUrl the merchant specified in the routes generation request.
3. Use the report code to make a request to the /reports/{code} endpoint. This request retrieves a bank account verification report containing information about the third-party individual and account number (ACH, BSB, EFT, IBAN) the third-party individual has agreed to share with the merchant.

Generate a list of routes

To get a list of available account verification routes.

1. Make a POST /routes request with the following parameters in the request body. The request header includes, your ADYEN-API-KEY and application/json specifying the format of the request body:

   Parameter	Required	Description
   country		The location where the third-party individual's bank account is registered. Adyen uses this information to determine the best provider for the given location, and to configure the open banking flow for that respective location.
   locale		The language to configure for the verification flow user interface. This information is used to configure the open banking flow with the same language for a consistent user experience.
   state		This is an optional value to identify the request in callback handling. You can generate this value on a per-session basis to protect the callback against Cross-Site Request Forgery (CSRF) attacks. This value must be composed of characters that can be successfully URL-encoded. Note, this value will be stored in external systems, so make sure that you avoid exposing any sensitive information in a plain-text format.
   redirectUrl		The URL where Adyen should redirect the third-party individual when the open banking flow finishes. Adyen's open banking gateway returns a report code as a parameter in the URL response. You can use this code when making a request to the /reports/{code} endpoint to get the bank account verification report for the third-party individual.

2. The response contains the details about the provider that the third-party individual will be redirected to during the flow, and the link to begin the open banking flow.

   Parameter	Description
   provider	Metadata about the selected provider, including the name and company logo. You can use this information to inform the third-party individual about the provider they will be redirected to when they select the link.
   link	The redirection link. You can use this link to redirect the third-party individual to the open banking flow when it is selected.

Redirect and handle the result

The Adyen open banking gateway handles the outgoing and incoming communications with the AISP. When the third-party individual opens the route link, the gateway redirects them to the external financial institution for account verification. After the verification flow at the external financial institution is complete, the gateway redirects the third-party individual from the financial institution back to the redirectUrl provided in the generate list of routes step.

For successful callbacks, the gateway adds a report code to the query parameters. Use this code to download a bank account verification report from the /reports/{code} endpoint in the view the bank account verification report step. In cases where there are errors, the third-party individual is redirected to the redirectUrl with the error information in the query parameters.

1. View the response of the redirectUrl and check if there was a successful redirection callback. A successful redirection callback may look like this:

2. The response contains the details about the type indicating success or error, the state , a signature, and a code. Use this codeto download a bank account verification report from the /reports/{code} endpoint in the view the bank account verification report step.

   Parameter	Description
   code	The report code that can be used to download the verification report in the gateway /reports/{code} endpoint.
   state	The state provided in the generate a list of routes step.
   type	The event type, success in the case of a successful callback or error, if the callback fails.
   signature	A JSON Web Signature (JWS) that signs the contents of the redirect URL, ensuring the integrity and authenticity of the data.

   If you encounter a redirection error callback, it may look like this:

   The response contains the details about the type indicating success or error, the error_code and error_message associated with the failed redirection request callback, state, and a signature.

   Parameter	Description
   error_code	The error code associated with the failed redirection request callback.
   error_message	The error message associated with the failed redirection request callback.
   state	The state provided in the generate a list of routes step.
   type	The event type, success in the case of a successful callback or error, if the callback fails.
   signature	A JSON Web Signature (JWS) that signs the contents of the redirect URL, ensuring the integrity and authenticity of the data.

Error codes and messages

Here's a list of error codes and corresponding error messages you can receive from Adyen's open banking gateway. Depending on the context of the error code and message, you choose how to handle the error and present options to your third-party individual.

View the bank account verification report

To download the bank account verification report for a third-party individual.

1. Make a GET /reports/{code} request, where code is a unique identifier for a specific bank account verification report. This is the code you received as a result of a successful callback to the open banking flow:

   Parameter	Required	Description
   code		The code you receive after a successful open banking flow that is included as a query parameter in the redirectUrl callback.

2. Confirm that the x-state header matches the state provided in the generate a list of routes request.

3. The response returns the report resource, identified by its unique id. You also receive the country where the report was generated, and the accounts that were verified through the open banking authorization flow.

   Parameter	Description
   id	The unique identifier of the report.
   country	The location where the report was generated.
   accounts	The list of verified accounts for the third-party individual. The accounts array allows for use-cases where more than one account can be verified. When a single account selection is permitted, the list will return that account.

See also