No momento, esta página não está disponível em português
Marketpay icon

Authentication

Learn how to get an access and refresh token.

Adyen uses OAuth 2.0, an open standard for authorization, to allow third-party applications access data on behalf of their users with their explicit consent.

Here's how the OAuth flow works with Open Banking:

  1. In your client app, the user selects to grant access to their payment data with Adyen.
  2. Your client app redirects the user to Adyen's authentication interface so they can authenticate and give their consent for data access or payment initiation capabilities.
  3. Adyen generates an authorisation code and returns it to your client app through the redirect URL.
  4. Your server uses the authorisation code to get an access token.

After you get the access token, you can use it to consume Adyen's Open Banking APIs to access user's payment data or initiate payments on their behalf depending on the granted scope.

Implement the Adyen connect button

In your app or on your website, implement a Connect with Adyen button. Use the URL from the next step to get user's consent.

Redirect user for authentication

To redirect the user to the grant consent dialog, make a GET /bankoauth/tpp-connect request. This request doesn't require any type of authorization. Provide the following query parameters:

Parameter 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 will redirect 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.
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.
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.

Authentication type: this request doesn't require any type of authorization.

By including these parameters, the authorization server can properly authenticate the user. The authentication process includes obtaining user's consent and redirecting them back to the client with the necessary information, such as an authorization code.

Here's an example of a GET request:

The response contains HTML code. Use this code to embed it into your app or website so the user can proceed with authentication.

After the user is successfully authenticated, a response is sent back to your client's redirect_uri. The URL contains the following appended parameters.

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 access token

To exchange the authorisation code from the previous step for an access token, make a POST /token request. Provide the following parameters in the request body:

Parameter 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.

The response contains the following fields:

Parameter Description
authorization_id The authorization id linked to the new token.
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 which allows to request 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.

If you lose the refresh token, there will be no way to recover the granted access. You'll need to redirect the user for authentication again.

Refresh access token

Because the access token is short-lived, a new access token has be requested regularly to continue using Open Banking APIs.

To refresh an access token, make a POST request to the /token endpoint. Provide the following parameters in the request body:

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

Authentication type: use client_id and client_secret for basic authentication.

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 which allows to request 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"
}

Próximas etapas