Get account holder consent

Adyen uses OAuth 2.0, an open standard for authorization, to allow third-party applications to get an account holder's explicit consent to access their account data. This page explains how to get an account holder's consent to access their Adyen business account information.

Requirements

How it works

Here is how the OAuth flow works with Adyen open banking:

• In your client app, the account holder selects to give access to their payment data with Adyen.
• Your client app redirects the account holder to Adyen's authentication interface so they can authenticate and give their consent to access their account data. Depending on the consent they give, you can check their account details, view the balance on their account, or initiate a payment.
• Adyen generates an authorization code and returns it to your client app through the redirect URL.
• Your server uses the authorization code to get an access token. The access token is needed for two things:
  • To authenticate open banking requests to Adyen for this account holder.
  • To get the account holder's consent ID, which is needed to get their account details.
• Your server uses the access token to create a consent and get a consentId.

After you get the access token and the consentId, you can make requests to Adyen open banking APIs to retrieve the account holder's Adyen business account details.

Implement Adyen connect button

In your app or on your website, implement a Connect with Adyen button. This button sends a GET /bankoauth/authorize request to your server, which redirects the account holder to an Adyen dialog for authentication and consent. Use the URL from the next step to get the account holder's consent.

Redirect account holder for authentication

To redirect the account holder so they can authenticate and give consent:

1. Make a GET /bankoauth/authorize request with the following query parameters:

   Note that this request does not require any type of authorization.

   Parameter	Required	Description
   client_id		Identifies the client (your app) making the request. This should match the QWAC certificate’s organization identifier.
   response_type		Specifies the response type expected from the authorization server. Set to code.
   redirect_uri		Specifies the URI to which the authorization server redirects the user after authentication and consent.
   scope		Defines the requested permissions or access levels that the client is seeking. It specifies the scope of the resources or actions the client intends to access on behalf of the user. Multiple scopes can be requested, separated by spaces. Possible values: bank.aisp:read, bank.pisp:write, and bank.cof:read.
   code_challenge_method		Set to S256.
   code_challenge		SHA256 hash of the code_verifier to be provided when getting the access token in the next step. The code_verifier is a random string generated by the third-party provider.
   state		A string generated by the client, which is included in the request and returned by the authorization server. It helps maintain the integrity of the authorization flow by preventing CSRF attacks.

   By including these parameters, the authorization server can properly authenticate the account holder.

   Here is an example of a GET request:

2. Embed the HTML code that you receive in the response into your app or website so the account holder can authenticate with their Adyen business account.

3. After the account holder has authenticated, get the code that is sent back to your client's redirect_uri. You need this code in the next step, to get an access token. This redirect will include the following query parameters in the URL.

   Parameter	Description
   code	The authorization code used to exchange for an access token. The code is short-lived and expires in five minutes.
   state	The same value as in the initial redirect URL.

   An example of a redirect URL may look like this:

Get an access token

To exchange the authorization code from the previous step for an access token:

1. From the server, make a POST /token request with the following parameters in the request body:

   Parameter	Required	Description
   grant_type		Set to authorization_code.
   code		The authorization code provided in the redirect URL.
   code_verifier		The code verifier.
   redirect_uri		The redirect URI for your client.

   Authentication type: use client_id and client_secret for basic authentication.

2. From the response, save the access_token and the refresh_token. You need the access_token in the next step, to get a consentId. The response contains the following fields:

   Parameter	Description
   token_type	The token type: bearer.
   expires_in	The expiry of the access token, in seconds. By default, 24 hours.
   access_token	The access token which can be used to access the open banking APIs.
   scope	The scope for the access_token. Multiple scopes are possible, separated by spaces.
   refresh_token	The OAuth refresh token that you can use to get new access tokens with the same scope. The refresh token expires as soon as it is used, providing a new access token and a new refresh token. A refresh token is one-time-use.

   If you lose the refresh token, there is no way to recover the granted access. You will need to redirect the account holder for authentication again.

Create a consent

To create a new consent use the access token to get a consentId. This consentId is needed to get the account details for the account holder. This consent needs to be approved by the account holder to continue.

1. Make a POST /consents request with the following parameters in the request body. The request header includes the TPP-Signature-Certificate: QSEALCertificate, which is the full eIDAS certificate encoded in Base64 format.

   Parameter	Required	Description
   access		The type of access requested. Set allPsd2 to allAccounts. This means you are requesting access to all of the user's accounts with Adyen.
   recurringIndicator		Indicates that the consent is being requested for recurring access to the user's account information or payment initiation.
   validUntil		Specifies the consent's validity end date in YYYY-MM-DD (ISO format). Maximum 90-day duration and 10 uses per day. Consent expires after this date.
   frequencyPerDay		Indicates the maximum number of times per day that you are allowed to access the user's account information or initiate payments.
   combinedServiceIndicator		Indicates whether you are requesting access to the user's account information or payment initiation services individually or as a combined service.

2. The response contains the consentStatus, consentId, and links to requested resources. From the response, save the consentId, you need this for the Adyen open banking requests to get the account details for this account holder. You can continue to poll the endpoint until you receive an updated consentStatus.

   • If you want to get information about consent authorization and to determine where your account holder is in the authentication flow, you will need the authorization-id-consent. This is the last set of characters at the end of thescaStatus link below. Save this authorization-id-consent to use in the get authorization information.

Refresh an access token

Because the access token is short-lived, a new access token has to be requested regularly to continue using open banking APIs. To find your original refresh token, see the response from get an access token. To refresh an access token:

1. Make a POST request to the /token endpoint. Provide the following parameters in the request body:

   Parameter	Required	Description
   grant_type		Set to refresh_token.
   refresh_token		The refresh token.

   Authentication type: use client_id and client_secret for basic authentication.

2. From the response, save the new access_token and refresh_token. The response contains the following fields:

   Parameter	Description
   token_type	The token type: bearer.
   expires_in	The expiry of the access token, in seconds. By default, 24 hours.
   access_token	The access token which can be used to access the open banking APIs.
   refresh_token	The OAuth refresh token that you can use to get new access tokens with the same scope. The refresh token has an unlimited validity but it expires with a short grace period when the refresh token is used to renew the access token. A refresh token is one-time-use.

   {
      "token_type": "bearer",
      "expires_in": 86400,
      "access_token": "oa_Elnme5TE0FH0v8qXEAQ56ME0Zxp0s1ETtGizd07mEY0MTh1",
      "refresh_token": "oa_T7ZKiG5HsdTBAstDksw4WslQhbQQr0CwfSom90NkSV9w8zB"
   }