Account Linking (OAuth)

Generate OAuth Client Credentials

In order to use the Afterpay OAuth APIs, we ask that merchants generate an OAuth Client ID and Secret. These needs to be generated for each environment and region that the merchant will operate in.

We ask that credentials be generated for both our sandbox and production environments. For example, if you are operating in the U.S and Australia, we ask that 4 sets of credentials be generated (2 for each sandbox region and 2 for each production region).

Instructions for generating credentials and securely forwarding them to Afterpay will be forwarded to you in a separate document.

Linking A Customer

Visual Flow

Technical Details

1. Create an Afterpay checkout using the v2/checkouts API - Create Checkout

POST /v2/checkouts
Host: api..afterpay.com
Content-Type: application/json
Authorization: Basic xxxxx

{
  ...
} 

2. Initiate an Afterpay checkout using the checkout URL from the checkout creation response (this example shows the production URL):
   a. The token should be the checkout token created using the v2/checkouts API
   b. The client_id should be the OAuth Client ID you generated in the previous step.
   c. The redirect_urlmust match one of the URIs given to Afterpay when generating your credentials above.

https://portal.afterpay.com/au/checkout/?token=002.xxx&state=obtaining_code
&response_type=code&client_id=123456&scope=create_checkout%20read_user_info&https://merchantwebsite.com/

3. When checkout is complete, capture the code from the redirect URL you provided when creating the checkout.

https://merchantwebsite.com/checkout?status=SUCCESS&orderToken=002.xx
&code=xxxxx

4. Use the code from the redirect URL to exchange for an access_token and a refresh_token. Use your OAuth Client ID and Secret to authenticate to this endpoint with Basic authentication. The Authorization header value should be the base 64 encoded version of "clientID:clientSecret".

Example Request

POST /oauth/token
Host: auth.afterpay.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-type: application/x-www-form-urlencoded

grant_type=authorization_code&code=xxxxx&redirect_uri=https://merchantwebsite.com

Example Response

HTTP 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "access_token": "xxxx",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "xxxx"
}

5. Store the refresh_token against the customer account on your system for future use.

Launching Authenticated Checkout

Visual Flow

Technical Details

1. Using the refresh_token stored against the customer's account, retrieve an access_token.

Example request

POST /oauth/token
Host: auth.afterpay.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=xxxxx

Example response

HTTP 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "access_token": "xxxx",
  "token_type": "bearer",
  "expires_in": 3600
}

2. Create the checkout using the access_token as the Bearer value in the Authorization header.

POST /v2/checkouts
Host: api.afterpay.com
Content-Type: application/json
Authorization: Bearer xxxxx

{
  ...
}

3. The customer should now be directed straight to the Afterpay summary screen and not be prompted to log in.

Delinking A Customer

Using the refresh_token stored against the customer's account, POST a request to /oauth/revoke to delink the customer account associated with that token.

Example request

POST /oauth/revoke
Host: auth.afterpay.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-type: application/x-www-form-urlencoded

token=xxxxx

📘

Advanced Flows

Additional information on more advanced flows can be found in the Full Integration Guide, which can be found here.

Testing Environments

OAuth Endpoints

Checkout Endpoints

❗️

OAuth does not currently support the Global API.