{"title":"OAuth integration guide","category":"default","creationDate":1684500900,"content":"<p>With an OAuth integration, you can request access to a selection of your customer's account resources. When your customer authorizes your access request, you get a token that you can use to authorize API requests on their behalf.<\/p>\n<h2>Integration steps<\/h2>\n<ol>\n<li><a href=\"#step-1-register-your-client\">Register your client<\/a><\/li>\n<li><a href=\"#step-2-request-access\">Request access<\/a><\/li>\n<li><a href=\"#step-3-get-your-access-and-refresh-tokens\">Get your access and refresh tokens<\/a><\/li>\n<li><a href=\"#step-4-use-your-access-token\">Use your access token<\/a><\/li>\n<li><a href=\"#step-5-refresh-your-access-token\">Refresh your access token<\/a><\/li>\n<\/ol>\n<h2>Requirements<\/h2>\n<p>To integrate with Adyen's OAuth service, you need to have:<\/p>\n<ul>\n<li>An account with the <strong>OAuth apps manage<\/strong> <a href=\"\/pt\/account\/user-roles\">user role<\/a>.\n<ul>\n<li>On our test environment, merchant accounts created since November 2023 have this role enabled by default. If your account was created before, reach out to support.<\/li>\n<li>On our live environment, only partner accounts have the <strong>OAuth apps manage<\/strong> role.<\/li>\n<\/ul><\/li>\n<\/ul>\n<div class=\"sc-notice info\"><div>\n<p>We advise you first integrate in our test environment, especially when your integration involves the <a href=\"\/pt\/partners\/oauth\/scopes#make-online-payments\">online payments scope<\/a>.<\/p>\n<\/div><\/div>\n<h2>Step 1: Register your client<\/h2>\n<p>An OAuth client is your application or website which accesses your customer's account resources on their behalf.<\/p>\n<p>To register your OAuth client:<\/p>\n<ol>\n<li>Log in to your <a href=\"https:\/\/ca-test.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Partner Portal<\/a>.<\/li>\n<li>Go to <strong>Developer<\/strong> &gt; <strong>OAuth apps<\/strong>.<\/li>\n<li>Select <strong>Create OAuth app<\/strong>.<\/li>\n<li>Enter your application name, URL, and description and select <strong>Continue<\/strong>.<\/li>\n<li>Enter your <strong>Redirect URL<\/strong>, select the <a href=\"\/pt\/partners\/oauth\/scopes\">scope of access<\/a> and select <strong>Continue<\/strong>.\n<ul>\n<li>After your customer authorizes your application, we redirect them to your <strong>Redirect URL<\/strong>.<\/li>\n<\/ul><\/li>\n<li>Copy the <strong>Client secret<\/strong> and store it securely. We do not store this value for you to access later.<\/li>\n<\/ol>\n<p>At the moment it is not possible to extend the scopes after the OAuth app has been created. Your customer can also not select or deselect requested scopes. The authorization can only be granted with all requested scopes.<\/p>\n<h2>Step 2: Request access<\/h2>\n<h3>Step 2.1: Construct the access grant URL<\/h3>\n<p>To request access to your customer's account resources, you need to redirect them to an Adyen page where they authenticate and grant you access.<\/p>\n<p>Create the URL that points to this location, using the following reference:<\/p>\n<table>\n<thead>\n<tr>\n<th>Parameter<\/th>\n<th style=\"text-align: center;\">Required<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><em>ADYEN_ENVIRONMENT_URL<\/em><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>The base URL of the relevant Adyen environment: <br \/> <ul><li markdown=\"1\">For test environment, set to <code>ca-test.adyen.com<\/code>.<\/li><li markdown=\"1\">For live environment, set to <code>ca-live.adyen.com<\/code>.<\/li><\/ul><\/td>\n<\/tr>\n<tr>\n<td><em>CLIENT_ID<\/em><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>The client ID of your OAuth client.<\/td>\n<\/tr>\n<tr>\n<td><code>code_challenge_method<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>The <a href=\"#code-challenge\">code challenge<\/a> method. Set to <code>S256<\/code>.<\/td>\n<\/tr>\n<tr>\n<td><code>code_challenge<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>Your unique code verifier for this authorization. See <a href=\"#code-challenge\">code challenge<\/a>.<\/td>\n<\/tr>\n<tr>\n<td><code>response_type<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>The type of response. Set to <code>code<\/code>.<\/td>\n<\/tr>\n<tr>\n<td><code>redirect_uri<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>The URL where your customer is redirected after successful authorization. Must match the Redirect URL set for your OAuth client.<\/td>\n<\/tr>\n<tr>\n<td><code>state<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>A random string to protect against <a href=\"https:\/\/owasp.org\/www-community\/attacks\/csrf\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Cross Site Request Forgery<\/a>.<\/td>\n<\/tr>\n<tr>\n<td><code>scope<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>A list of space separated <a href=\"\/pt\/partners\/oauth\/scopes\">scope identifiers<\/a> you request access for. Must match the scopes set for your OAuth client.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<pre><code class=\"language-bash\">https:\/\/{ADYEN_ENVIRONMENT_URL}\/ca\/ca\/oauth\/connect.shtml?client_id={CLIENT_ID}\n&amp;code_challenge_method={CODE_CHALLENGE_METHOD}\n&amp;code_challenge={CODE_CHALLENGE}\n&amp;response_type={RESPONSE_TYPE}\n&amp;redirect_uri={REDIRECT_URI}\n&amp;state={STATE}\n&amp;scope={SCOPE}<\/code><\/pre>\n<h3>Code challenge<\/h3>\n<p>During the OAuth flow, we use <a href=\"https:\/\/datatracker.ietf.org\/doc\/html\/rfc7636\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Proof Key for Code Exchange<\/a> (PKCE) to add a layer of security on top of the client secret. PKCE works as follows:<\/p>\n<ol>\n<li>For every <a href=\"#step-2-request-access\">access request<\/a>, you create and supply a unique <code>code_challenge<\/code>, also known as a PKCE secret.<\/li>\n<li>When you <a href=\"#step-3-get-your-access-and-refresh-tokens\">exchange the authorization code for the access token<\/a>, you supply the associated <code>code_verifier<\/code>.<\/li>\n<\/ol>\n<p>If the authorization code is intercepted, it cannot be used without the PKCE secret.<\/p>\n<ol>\n<li>To create your <code>code_verifier<\/code>, generate a random string with the following properties:\n<ul>\n<li>The string has a minimum length of 43 characters and a maximum length of 128 characters.<\/li>\n<li>Allowed characters are [A-Z] \/ [a-z] \/ [0-9] \/ \"-\" \/ \".\" \/ \"_\" \/ \"~\".<\/li>\n<\/ul><\/li>\n<li>To create your <code>code_challenge<\/code>, create a <a href=\"https:\/\/datatracker.ietf.org\/doc\/html\/rfc4648#section-5\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">base64url<\/a>-encoded SHA256 hash of the <code>code_verifier<\/code>.<\/li>\n<\/ol>\n<h4>Example<\/h4>\n<ol>\n<li>To create your <code>code_verifier<\/code>, generate a random URL-safe string: <code>dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk<\/code>.<\/li>\n<li>To create your <code>code_challenge<\/code>, base64 URL-encode the SHA256 hash of the <code>code_verifier<\/code>: <code>E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM<\/code>.<\/li>\n<\/ol>\n<h3>Handle the redirect<\/h3>\n<p>Whether the authorization was <a href=\"#successful-authorization\">successful<\/a> or <a href=\"#failed-authorization\">failed<\/a>, your customer is redirected to your <code>redirect_uri<\/code>.<\/p>\n<h4>Successful authorization<\/h4>\n<p>After successful authorization, your customer is redirected to:<\/p>\n<pre><code class=\"language-bash\">https:\/\/{REDIRECT_URI}?code={CODE}&amp;state={STATE}<\/code><\/pre>\n<table>\n<thead>\n<tr>\n<th>Parameter name<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><em>REDIRECT_URI<\/em><\/td>\n<td>The URI that you have set when <a href=\"#step-2-request-access\">requesting access<\/a>.<\/td>\n<\/tr>\n<tr>\n<td><em>CODE<\/em><\/td>\n<td>The short-lived authorization code. <a href=\"#step-3-get-your-access-and-refresh-tokens\">Exchange this code<\/a> for an access token.<\/td>\n<\/tr>\n<tr>\n<td><em>STATE<\/em><\/td>\n<td>The same string as you provided for <code>state<\/code> <a href=\"#step-2-request-access\">in the access request<\/a>. Used to protect against Cross Site Request Forgery.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>In the next step, you will use the <em>CODE<\/em> to request access and refresh tokens.<\/p>\n<h4>Failed authorization<\/h4>\n<p>After failed authorization, your customer is redirected to:<\/p>\n<pre><code class=\"language-bash\">https:\/\/{REDIRECT_URI}?error={ERROR}<\/code><\/pre>\n<table>\n<thead>\n<tr>\n<th>Parameter name<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><em>REDIRECT_URI<\/em><\/td>\n<td>The URI that you have set when <a href=\"#step-2-request-access\">requesting access<\/a>.<\/td>\n<\/tr>\n<tr>\n<td><em>ERROR<\/em><\/td>\n<td>The relevant <a href=\"https:\/\/www.rfc-editor.org\/rfc\/rfc6749#section-4.1.2.1\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">OAuth error code<\/a>.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>Step 2.2: Redirect your customer<\/h3>\n<p>Add a button labeled <strong>Connect with Adyen<\/strong> to your application for your customers to initiate the access delegation.<\/p>\n<p>When your customer clicks the button, redirect them to the URL you constructed in <a href=\"\/pt\/partners\/oauth\/integration#step-2-1-construct-the-access-grant-url\">the previous step<\/a>, which points to an Adyen login screen where your customer authenticates and authorizes your request.<\/p>\n<pre><code class=\"language-html\">&lt;a href=\"\" class=\"adyen-connect\" target=\"_blank\"&gt;Connect with Adyen&lt;\/a&gt;\n&lt;!-- Set the value of the href attribute to the URL created in step 2.1 --&gt;<\/code><\/pre>\n<p>Then, style the button:<\/p>\n<pre><code class=\"language-css\">.adyen-connect {\n     display: inline-block;\n     padding: 10px 12px 8px;\n     background-color: #0ABF53;\n     color: #FFFFFF;\n     cursor: pointer;\n     font-family: Fakt, \"Helvetica Neue\", Arial, sans-serif;\n     font-weight: bold;\n     font-size: 15px;\n     text-decoration: none;\n     border: 1px solid #0ABF53;\n     box-sizing: border-box;\n     border-radius: 6px;\n     transition: all .2s\n}\n .adyen-connect:hover {\n     background-color: #0BD25B;\n     border-color: #0BD25B;\n}\n .adyen-connect:active {\n     background-color: #09AF4C;\n     border-color: #09AF4C;\n}\n .adyen-connect::before {\n     padding: 0 8px;\n     margin-right: 8px;\n     content: \"\";\n     background-repeat: no-repeat;\n     background-image: url(\"data:image\/svg+xml,%3Csvg%20width%3D%2215%22%20height%3D%2215%22%20viewBox%3D%220%200%2015%2015%22%20fill%3D%22none%22%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%3E%0A%3Cpath%20d%3D%22M11.748%20-0.0195312H0.212988V3.72347H7.72699C8.18999%203.72347%208.56999%204.11347%208.56999%204.58547V11.2285H6.96699C6.85501%2011.2273%206.74437%2011.2041%206.64139%2011.1601C6.5384%2011.1161%206.44509%2011.0523%206.3668%2010.9722C6.2885%2010.8922%206.22676%2010.7975%206.1851%2010.6935C6.14343%2010.5896%206.12267%2010.4784%206.12399%2010.3665V5.60447H2.94599C2.55467%205.60812%202.16791%205.68897%201.8079%205.84238C1.44788%205.9958%201.12168%206.21875%200.848001%206.49847C0.574318%206.77819%200.358532%207.10918%200.213013%207.47246C0.0674935%207.83573%20-0.00489811%208.22416%20-1.23367e-05%208.61547V11.9695C-1.23367e-05%2013.6375%201.31599%2014.9805%202.94599%2014.9805H14.694V2.98247C14.6989%202.59159%2014.6264%202.2036%2014.4808%201.84083C14.3352%201.47807%2014.1192%201.14767%2013.8454%200.868669C13.5716%200.589665%2013.2454%200.367556%2012.8854%200.215124C12.5254%200.062691%2012.1389%20-0.0170568%2011.748%20-0.0195312Z%22%20fill%3D%22white%22%2F%3E%0A%3C%2Fsvg%3E%0A\");\n}<\/code><\/pre>\n<h2>Step 3: Get your access and refresh tokens<\/h2>\n<p>Make a POST request to the <code>\/token<\/code> endpoint to exchange your authorization code for:<\/p>\n<ul>\n<li>A short-lived (24 hours by default) access token, to make API requests on behalf of your customer.<\/li>\n<li>A one-time-use refresh token, to <a href=\"#step-5-refresh-your-access-token\">get a new access token<\/a> after your previous expired.<\/li>\n<\/ul>\n<p>To get your access and refresh tokens, make an HTTP <code>POST<\/code> request to:<\/p>\n<pre><code class=\"language-shell\">curl --request POST 'https:\/\/{ADYEN_OAUTH_BASE_URL}\/v1\/token' \\\n--header 'Authorization: Basic {BASIC_AUTH_HEADER}' \\\n--header 'Content-Type: application\/x-www-form-urlencoded' \\\n--data-urlencode 'grant_type=authorization_code' \\\n--data-urlencode 'code={CODE}' \\\n--data-urlencode 'code_verifier={CODE_VERIFIER}' \\\n--data-urlencode 'redirect_uri={REDIRECT_URI}'<\/code><\/pre>\n<p>All the parameters in the request body are <code>x-www-form-urlencoded<\/code>.<\/p>\n<table>\n<thead>\n<tr>\n<th>Parameter name<\/th>\n<th style=\"text-align: center;\">Required<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><em>ADYEN_OAUTH_BASE_URL<\/em><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>The base URL of the Adyen OAuth API: <br \/> <ul><li markdown=\"1\">For test environment, set to <code>oauth-test.adyen.com<\/code>.<\/li><li markdown=\"1\">For live environment, set to <code>oauth-live.adyen.com<\/code>.<\/li><\/ul><\/td>\n<\/tr>\n<tr>\n<td><em>BASIC_AUTH_HEADER<\/em><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>A combination of <a href=\"\/pt\/partners\/oauth\/integration#step-1-register-your-client\">your OAuth client<\/a> ID and secret.<br\/>To create your basic access authentication value:<ol><li markdown=\"1\">Concatenate your client ID, a colon <code>:<\/code> and your client secret.<\/li><li markdown=\"1\">Base64 encode the result of the previous step.<\/li><\/ol><\/td>\n<\/tr>\n<tr>\n<td><code>grant_type<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>The type of grant. Set to <code>authorization_code<\/code>.<\/td>\n<\/tr>\n<tr>\n<td><code>code<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>The authorization code <a href=\"#handle-the-redirect\">returned after successful authorization<\/a>.<\/td>\n<\/tr>\n<tr>\n<td><code>code_verifier<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>The <a href=\"#code-challenge\"><code>code_verifier<\/code> that you created<\/a> for this authorization.<\/td>\n<\/tr>\n<tr>\n<td><code>redirect_uri<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>The URL where your customer is redirected after successful authorization. Must match the Redirect URL set for your OAuth client.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>Handle the response<\/h3>\n<p>The response body depends on whether your request was <a href=\"#get-access-refresh-tokens-successful-response\">successful<\/a> or <a href=\"#get-access-refresh-tokens-unsuccessful-response\">unsuccessful<\/a>.<\/p>\n<h4 id=\"get-access-refresh-tokens-successful-response\">Successful response<\/h4>\n<table>\n<thead>\n<tr>\n<th>Parameter name<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><code>token_type<\/code><\/td>\n<td>The token type. This value is set to <code>bearer<\/code>.<\/td>\n<\/tr>\n<tr>\n<td><code>expires_in<\/code><\/td>\n<td>The time in seconds after which the access token expires. By default, this value is set to <code>86400<\/code> (24 hours).<\/td>\n<\/tr>\n<tr>\n<td><code>access_token<\/code><\/td>\n<td>The access token, used to <a href=\"#step-4-use-your-access-token\">authenticate API requests<\/a> on behalf of your merchant.<\/td>\n<\/tr>\n<tr>\n<td><code>refresh_token<\/code><\/td>\n<td>The refresh token, used to <a href=\"#step-5-refresh-your-access-token\">get a new access token<\/a> once the previous has expired.<\/td>\n<\/tr>\n<tr>\n<td><code>scope<\/code><\/td>\n<td>The scope of access that the <code>access_token<\/code> provides.<\/td>\n<\/tr>\n<tr>\n<td><code>accounts<\/code><\/td>\n<td>The merchant accounts that the <code>access_token<\/code> provides access to.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h4 id=\"get-access-refresh-tokens-unsuccessful-response\">Unsuccessful response<\/h4>\n<table>\n<thead>\n<tr>\n<th>Parameter name<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><code>error<\/code><\/td>\n<td>The relevant <a href=\"https:\/\/www.rfc-editor.org\/rfc\/rfc6749#section-5.2\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">OAuth error code<\/a>.<\/td>\n<\/tr>\n<tr>\n<td><code>error_description<\/code><\/td>\n<td>A description of the error.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>Step 4: Use your access token<\/h2>\n<p>Authorize API requests with your access token as bearer token:<\/p>\n<pre><code class=\"language-bash\">curl --request {HTTP-METHOD} '{RESOURCE_API}' \\\n  --header 'Authorization: Bearer {ACCESS_TOKEN}'<\/code><\/pre>\n<h2>Step 5: Refresh your access token<\/h2>\n<p>Your access token is valid until the expiry period has elapsed. Find the expiry period in the <a href=\"#get-access-refresh-tokens-successful-response\">response of the <code>\/token<\/code> request<\/a>.<\/p>\n<p>Your refresh token expires only upon its usage. A short grace period is provided to allow for retries in the event of network errors or similar issues.<\/p>\n<p>To get a new access token, make an HTTP <code>POST<\/code> request to:<\/p>\n<pre><code class=\"language-bash\">curl --request POST 'https:\/\/{ADYEN_BASE_URL}\/v1\/token' \\\n--header 'Authorization: Basic {BASIC_AUTH_HEADER}' \\\n--header 'Content-Type: application\/x-www-form-urlencoded' \\\n--data-urlencode 'grant_type={GRANT_TYPE}' \\\n--data-urlencode 'refresh_token={REFRESH_TOKEN}' \\<\/code><\/pre>\n<p>All the parameters in the request body are <code>x-www-form-urlencoded<\/code>.<\/p>\n<table>\n<thead>\n<tr>\n<th>Parameter name<\/th>\n<th style=\"text-align: center;\">Required<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><em>ADYEN_BASE_URL<\/em><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>The base URL of the Adyen OAuth API: <br \/> <ul><li markdown=\"1\">For test environment, set to <code>oauth-test.adyen.com<\/code>.<\/li><li markdown=\"1\">For live environment, set to <code>oauth-live.adyen.com<\/code>.<\/li><\/ul><\/td>\n<\/tr>\n<tr>\n<td><em>BASIC_AUTH_HEADER<\/em><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>A combination of <a href=\"\/pt\/partners\/oauth\/integration#step-1-register-your-client\">your OAuth client<\/a> ID and secret.<br\/>To create your basic access authentication value:<ol><li markdown=\"1\">Concatenate your client ID, a colon <code>:<\/code>, and your client secret.<\/li><li markdown=\"1\">Base64 encode the result of the previous step.<\/li><\/ol><\/td>\n<\/tr>\n<tr>\n<td><code>grant_type<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>The type of grant. Set to <code>refresh_token<\/code>.<\/td>\n<\/tr>\n<tr>\n<td><code>refresh_token<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>Your refresh token.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>When you successfully refresh your access token:<\/p>\n<ul>\n<li>Your previous <code>access_token<\/code> immediately expires. This ensures there is no more than one valid <code>access_token<\/code> per authorization at a given point in time.<\/li>\n<li>Your previous <code>refresh_token<\/code> expires shortly. This lets you retry the operation if the response was lost, for example during network issues.<\/li>\n<\/ul>\n<h3>Successful response<\/h3>\n<table>\n<thead>\n<tr>\n<th>Parameter name<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><code>token_type<\/code><\/td>\n<td>The token type. This value is set to <code>bearer<\/code>.<\/td>\n<\/tr>\n<tr>\n<td><code>expires_in<\/code><\/td>\n<td>The time in seconds after which the access token expires. By default, this value is set to <code>86400<\/code> (24 hours).<\/td>\n<\/tr>\n<tr>\n<td><code>access_token<\/code><\/td>\n<td>The access token, used to authenticate API requests on behalf of your merchant.<\/td>\n<\/tr>\n<tr>\n<td><code>refresh_token<\/code><\/td>\n<td>The refresh token, used to get a new access tokens once the previous has expired.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>The scope of access and merchant accounts that the <code>access_token<\/code> provides access to remains unchanged from when you <a href=\"#step-3-get-your-access-and-refresh-tokens\">got your access and refresh tokens<\/a>.<\/p>\n<h3>Unsuccessful response<\/h3>\n<table>\n<thead>\n<tr>\n<th>Parameter name<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><code>error<\/code><\/td>\n<td>The relevant <a href=\"https:\/\/www.rfc-editor.org\/rfc\/rfc6749#section-5.2\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">OAuth error code<\/a>.<\/td>\n<\/tr>\n<tr>\n<td><code>error_description<\/code><\/td>\n<td>A description of the error.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>Go live<\/h2>\n<p>When you are ready to go live, make sure to:<\/p>\n<ol>\n<li>Register an OAuth client in your <a href=\"https:\/\/ca-live.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">live Partner Portal<\/a>.<\/li>\n<li>Change all instances of the OAuth client ID, client secret, and client URI to reflect the OAuth client in your live account.<\/li>\n<li>Change all API endpoints from test to live.<\/li>\n<\/ol>","url":"https:\/\/docs.adyen.com\/pt\/partners\/oauth\/integration","articleFields":{"description":"Integrate with our OAuth service to make API requests on your customer's behalf","feedback_component":true,"robots":"noindex,nofollow","last_edit_on":"07-11-2023 16:23","filters_component":false,"page_id":"28d61479-f141-458e-b470-bc6f1b5e8e9b","decision_tree":"[]"},"algolia":{"url":"https:\/\/docs.adyen.com\/pt\/partners\/oauth\/integration","title":"OAuth integration guide","content":"With an OAuth integration, you can request access to a selection of your customer's account resources. When your customer authorizes your access request, you get a token that you can use to authorize API requests on their behalf.\nIntegration steps\n\nRegister your client\nRequest access\nGet your access and refresh tokens\nUse your access token\nRefresh your access token\n\nRequirements\nTo integrate with Adyen's OAuth service, you need to have:\n\nAn account with the OAuth apps manage user role.\n\nOn our test environment, merchant accounts created since November 2023 have this role enabled by default. If your account was created before, reach out to support.\nOn our live environment, only partner accounts have the OAuth apps manage role.\n\n\n\nWe advise you first integrate in our test environment, especially when your integration involves the online payments scope.\n\nStep 1: Register your client\nAn OAuth client is your application or website which accesses your customer's account resources on their behalf.\nTo register your OAuth client:\n\nLog in to your Partner Portal.\nGo to Developer &gt; OAuth apps.\nSelect Create OAuth app.\nEnter your application name, URL, and description and select Continue.\nEnter your Redirect URL, select the scope of access and select Continue.\n\nAfter your customer authorizes your application, we redirect them to your Redirect URL.\n\nCopy the Client secret and store it securely. We do not store this value for you to access later.\n\nAt the moment it is not possible to extend the scopes after the OAuth app has been created. Your customer can also not select or deselect requested scopes. The authorization can only be granted with all requested scopes.\nStep 2: Request access\nStep 2.1: Construct the access grant URL\nTo request access to your customer's account resources, you need to redirect them to an Adyen page where they authenticate and grant you access.\nCreate the URL that points to this location, using the following reference:\n\n\n\nParameter\nRequired\nDescription\n\n\n\n\nADYEN_ENVIRONMENT_URL\n\nThe base URL of the relevant Adyen environment:  For test environment, set to ca-test.adyen.com.For live environment, set to ca-live.adyen.com.\n\n\nCLIENT_ID\n\nThe client ID of your OAuth client.\n\n\ncode_challenge_method\n\nThe code challenge method. Set to S256.\n\n\ncode_challenge\n\nYour unique code verifier for this authorization. See code challenge.\n\n\nresponse_type\n\nThe type of response. Set to code.\n\n\nredirect_uri\n\nThe URL where your customer is redirected after successful authorization. Must match the Redirect URL set for your OAuth client.\n\n\nstate\n\nA random string to protect against Cross Site Request Forgery.\n\n\nscope\n\nA list of space separated scope identifiers you request access for. Must match the scopes set for your OAuth client.\n\n\n\nhttps:\/\/{ADYEN_ENVIRONMENT_URL}\/ca\/ca\/oauth\/connect.shtml?client_id={CLIENT_ID}\n&amp;code_challenge_method={CODE_CHALLENGE_METHOD}\n&amp;code_challenge={CODE_CHALLENGE}\n&amp;response_type={RESPONSE_TYPE}\n&amp;redirect_uri={REDIRECT_URI}\n&amp;state={STATE}\n&amp;scope={SCOPE}\nCode challenge\nDuring the OAuth flow, we use Proof Key for Code Exchange (PKCE) to add a layer of security on top of the client secret. PKCE works as follows:\n\nFor every access request, you create and supply a unique code_challenge, also known as a PKCE secret.\nWhen you exchange the authorization code for the access token, you supply the associated code_verifier.\n\nIf the authorization code is intercepted, it cannot be used without the PKCE secret.\n\nTo create your code_verifier, generate a random string with the following properties:\n\nThe string has a minimum length of 43 characters and a maximum length of 128 characters.\nAllowed characters are [A-Z] \/ [a-z] \/ [0-9] \/ \"-\" \/ \".\" \/ \"_\" \/ \"~\".\n\nTo create your code_challenge, create a base64url-encoded SHA256 hash of the code_verifier.\n\nExample\n\nTo create your code_verifier, generate a random URL-safe string: dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk.\nTo create your code_challenge, base64 URL-encode the SHA256 hash of the code_verifier: E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM.\n\nHandle the redirect\nWhether the authorization was successful or failed, your customer is redirected to your redirect_uri.\nSuccessful authorization\nAfter successful authorization, your customer is redirected to:\nhttps:\/\/{REDIRECT_URI}?code={CODE}&amp;state={STATE}\n\n\n\nParameter name\nDescription\n\n\n\n\nREDIRECT_URI\nThe URI that you have set when requesting access.\n\n\nCODE\nThe short-lived authorization code. Exchange this code for an access token.\n\n\nSTATE\nThe same string as you provided for state in the access request. Used to protect against Cross Site Request Forgery.\n\n\n\nIn the next step, you will use the CODE to request access and refresh tokens.\nFailed authorization\nAfter failed authorization, your customer is redirected to:\nhttps:\/\/{REDIRECT_URI}?error={ERROR}\n\n\n\nParameter name\nDescription\n\n\n\n\nREDIRECT_URI\nThe URI that you have set when requesting access.\n\n\nERROR\nThe relevant OAuth error code.\n\n\n\nStep 2.2: Redirect your customer\nAdd a button labeled Connect with Adyen to your application for your customers to initiate the access delegation.\nWhen your customer clicks the button, redirect them to the URL you constructed in the previous step, which points to an Adyen login screen where your customer authenticates and authorizes your request.\n&lt;a href=\"\" class=\"adyen-connect\" target=\"_blank\"&gt;Connect with Adyen&lt;\/a&gt;\n&lt;!-- Set the value of the href attribute to the URL created in step 2.1 --&gt;\nThen, style the button:\n.adyen-connect {\n     display: inline-block;\n     padding: 10px 12px 8px;\n     background-color: #0ABF53;\n     color: #FFFFFF;\n     cursor: pointer;\n     font-family: Fakt, \"Helvetica Neue\", Arial, sans-serif;\n     font-weight: bold;\n     font-size: 15px;\n     text-decoration: none;\n     border: 1px solid #0ABF53;\n     box-sizing: border-box;\n     border-radius: 6px;\n     transition: all .2s\n}\n .adyen-connect:hover {\n     background-color: #0BD25B;\n     border-color: #0BD25B;\n}\n .adyen-connect:active {\n     background-color: #09AF4C;\n     border-color: #09AF4C;\n}\n .adyen-connect::before {\n     padding: 0 8px;\n     margin-right: 8px;\n     content: \"\";\n     background-repeat: no-repeat;\n     background-image: url(\"data:image\/svg+xml,%3Csvg%20width%3D%2215%22%20height%3D%2215%22%20viewBox%3D%220%200%2015%2015%22%20fill%3D%22none%22%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%3E%0A%3Cpath%20d%3D%22M11.748%20-0.0195312H0.212988V3.72347H7.72699C8.18999%203.72347%208.56999%204.11347%208.56999%204.58547V11.2285H6.96699C6.85501%2011.2273%206.74437%2011.2041%206.64139%2011.1601C6.5384%2011.1161%206.44509%2011.0523%206.3668%2010.9722C6.2885%2010.8922%206.22676%2010.7975%206.1851%2010.6935C6.14343%2010.5896%206.12267%2010.4784%206.12399%2010.3665V5.60447H2.94599C2.55467%205.60812%202.16791%205.68897%201.8079%205.84238C1.44788%205.9958%201.12168%206.21875%200.848001%206.49847C0.574318%206.77819%200.358532%207.10918%200.213013%207.47246C0.0674935%207.83573%20-0.00489811%208.22416%20-1.23367e-05%208.61547V11.9695C-1.23367e-05%2013.6375%201.31599%2014.9805%202.94599%2014.9805H14.694V2.98247C14.6989%202.59159%2014.6264%202.2036%2014.4808%201.84083C14.3352%201.47807%2014.1192%201.14767%2013.8454%200.868669C13.5716%200.589665%2013.2454%200.367556%2012.8854%200.215124C12.5254%200.062691%2012.1389%20-0.0170568%2011.748%20-0.0195312Z%22%20fill%3D%22white%22%2F%3E%0A%3C%2Fsvg%3E%0A\");\n}\nStep 3: Get your access and refresh tokens\nMake a POST request to the \/token endpoint to exchange your authorization code for:\n\nA short-lived (24 hours by default) access token, to make API requests on behalf of your customer.\nA one-time-use refresh token, to get a new access token after your previous expired.\n\nTo get your access and refresh tokens, make an HTTP POST request to:\ncurl --request POST 'https:\/\/{ADYEN_OAUTH_BASE_URL}\/v1\/token' \\\n--header 'Authorization: Basic {BASIC_AUTH_HEADER}' \\\n--header 'Content-Type: application\/x-www-form-urlencoded' \\\n--data-urlencode 'grant_type=authorization_code' \\\n--data-urlencode 'code={CODE}' \\\n--data-urlencode 'code_verifier={CODE_VERIFIER}' \\\n--data-urlencode 'redirect_uri={REDIRECT_URI}'\nAll the parameters in the request body are x-www-form-urlencoded.\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nADYEN_OAUTH_BASE_URL\n\nThe base URL of the Adyen OAuth API:  For test environment, set to oauth-test.adyen.com.For live environment, set to oauth-live.adyen.com.\n\n\nBASIC_AUTH_HEADER\n\nA combination of your OAuth client ID and secret.To create your basic access authentication value:Concatenate your client ID, a colon : and your client secret.Base64 encode the result of the previous step.\n\n\ngrant_type\n\nThe type of grant. Set to authorization_code.\n\n\ncode\n\nThe authorization code returned after successful authorization.\n\n\ncode_verifier\n\nThe code_verifier that you created for this authorization.\n\n\nredirect_uri\n\nThe URL where your customer is redirected after successful authorization. Must match the Redirect URL set for your OAuth client.\n\n\n\nHandle the response\nThe response body depends on whether your request was successful or unsuccessful.\nSuccessful response\n\n\n\nParameter name\nDescription\n\n\n\n\ntoken_type\nThe token type. This value is set to bearer.\n\n\nexpires_in\nThe time in seconds after which the access token expires. By default, this value is set to 86400 (24 hours).\n\n\naccess_token\nThe access token, used to authenticate API requests on behalf of your merchant.\n\n\nrefresh_token\nThe refresh token, used to get a new access token once the previous has expired.\n\n\nscope\nThe scope of access that the access_token provides.\n\n\naccounts\nThe merchant accounts that the access_token provides access to.\n\n\n\nUnsuccessful response\n\n\n\nParameter name\nDescription\n\n\n\n\nerror\nThe relevant OAuth error code.\n\n\nerror_description\nA description of the error.\n\n\n\nStep 4: Use your access token\nAuthorize API requests with your access token as bearer token:\ncurl --request {HTTP-METHOD} '{RESOURCE_API}' \\\n  --header 'Authorization: Bearer {ACCESS_TOKEN}'\nStep 5: Refresh your access token\nYour access token is valid until the expiry period has elapsed. Find the expiry period in the response of the \/token request.\nYour refresh token expires only upon its usage. A short grace period is provided to allow for retries in the event of network errors or similar issues.\nTo get a new access token, make an HTTP POST request to:\ncurl --request POST 'https:\/\/{ADYEN_BASE_URL}\/v1\/token' \\\n--header 'Authorization: Basic {BASIC_AUTH_HEADER}' \\\n--header 'Content-Type: application\/x-www-form-urlencoded' \\\n--data-urlencode 'grant_type={GRANT_TYPE}' \\\n--data-urlencode 'refresh_token={REFRESH_TOKEN}' \\\nAll the parameters in the request body are x-www-form-urlencoded.\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nADYEN_BASE_URL\n\nThe base URL of the Adyen OAuth API:  For test environment, set to oauth-test.adyen.com.For live environment, set to oauth-live.adyen.com.\n\n\nBASIC_AUTH_HEADER\n\nA combination of your OAuth client ID and secret.To create your basic access authentication value:Concatenate your client ID, a colon :, and your client secret.Base64 encode the result of the previous step.\n\n\ngrant_type\n\nThe type of grant. Set to refresh_token.\n\n\nrefresh_token\n\nYour refresh token.\n\n\n\nWhen you successfully refresh your access token:\n\nYour previous access_token immediately expires. This ensures there is no more than one valid access_token per authorization at a given point in time.\nYour previous refresh_token expires shortly. This lets you retry the operation if the response was lost, for example during network issues.\n\nSuccessful response\n\n\n\nParameter name\nDescription\n\n\n\n\ntoken_type\nThe token type. This value is set to bearer.\n\n\nexpires_in\nThe time in seconds after which the access token expires. By default, this value is set to 86400 (24 hours).\n\n\naccess_token\nThe access token, used to authenticate API requests on behalf of your merchant.\n\n\nrefresh_token\nThe refresh token, used to get a new access tokens once the previous has expired.\n\n\n\nThe scope of access and merchant accounts that the access_token provides access to remains unchanged from when you got your access and refresh tokens.\nUnsuccessful response\n\n\n\nParameter name\nDescription\n\n\n\n\nerror\nThe relevant OAuth error code.\n\n\nerror_description\nA description of the error.\n\n\n\nGo live\nWhen you are ready to go live, make sure to:\n\nRegister an OAuth client in your live Partner Portal.\nChange all instances of the OAuth client ID, client secret, and client URI to reflect the OAuth client in your live account.\nChange all API endpoints from test to live.\n","type":"page","locale":"pt","boost":17,"hierarchy":{"lvl0":"Home","lvl1":"Partners","lvl2":"OAuth","lvl3":"OAuth integration guide"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/pt","lvl1":"https:\/\/docs.adyen.com\/pt\/partners","lvl2":"https:\/\/docs.adyen.com\/pt\/partners\/oauth","lvl3":"\/pt\/partners\/oauth\/integration"},"levels":4,"category":"","category_color":"","tags":["OAuth","integration","guide"]}}