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
Requirement | Description |
---|---|
Integration type | Not applicable; this documentation is intended for third-party providers. |
Setup steps | Before you begin, you must complete the Adyen onboarding steps. |
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:
-
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:
-
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.
-
After the account holder has authenticated, get the
code
that is sent back to your client'sredirect_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:
-
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
andclient_secret
for basic authentication. -
From the response, save the
access_token
and therefresh_token
. You need theaccess_token
in the next step, to get aconsentId
. 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.
-
Make a POST
/consents
request with the following parameters in the request body. The request header includes theTPP-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. -
The response contains the
consentStatus
,consentId
, and links to requested resources. From the response, save theconsentId
, 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 updatedconsentStatus
.- 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 thisauthorization-id-consent
to use in the get authorization information.
- 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
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:
-
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
andclient_secret
for basic authentication. -
From the response, save the new
access_token
andrefresh_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" }