Authentication

The Cash App Afterpay Online API uses two different authentication options, which are discussed below. With the exception of Ping, all Online API endpoints require that one of these forms of authentication are used. Failure to correctly authenticate an API request will result in a 401 Unauthorized response.

Basic auth

The first authentication method is Basic HTTP Authentication, a simple authentication scheme built into the HTTP protocol, as specified by RFC 7617.

Example request

1
GET /v2/configuration HTTP/1.1
2
Host: global-api-sandbox.afterpay.com
3
Authorization: Basic MzI6YWJjZGVmZ2g=

Consider the following example:

The credentials are joined by a colon character (without any spaces), then base64-encoded.

The Authorization header can then be formed by including the word Basic, followed by a single space character, followed by the base64-encoded credential pair.

Bearer tokens

The Client Credentials Authentication method is another authentication method available to merchants. It is a secure mechanism used to obtain access tokens which is defined in RFC 6749.

When using this method, a client application uses its unique credentials to fetch an access token, which enables it to access Cash App Afterpay’s online APIs.

Token URLs

Tokens are generated using separate URLs from those described in the API environments

Example request

The following examples use the same credentials as the Basic Auth section.

Access token request

1
POST /v2/oauth2/token HTTP/1.1
2
Host: https://merchant-auth-sandbox.afterpay.com
3
Content-Type: application/x-www-form-urlencoded
4
5
grant_type=client_credentials
6
&client_id=32
7
&client_secret=abcdefgh
8
&scope=merchant_api_v2

1
curl -X POST "https://merchant-auth-sandbox.afterpay.com/v2/oauth2/token" \
2
-H "Content-Type: application/x-www-form-urlencoded" \
3
-d "grant_type=client_credentials&client_id=32&client_secret=abcdefgh&scope=merchant_api_v2"

1
const request = require('request');
2
3
const options = {
4
  url: 'https://merchant-auth-sandbox.afterpay.com/v2/oauth2/token',
5
  method: 'POST',
6
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
7
  form: {
8
    grant_type: 'client_credentials',
9
    client_id: '32',
10
    client_secret: 'abcdefgh',
11
    scope: 'merchant_api_v2'
12
  }
13
};
14
15
request(options, function (error, response, body) {
16
  if (error) throw new Error(error);
17
18
  console.log(body);
19
});

1
require 'uri'
2
require 'net/http'
3
4
uri = URI.parse('https://merchant-auth-sandbox.afterpay.com/v2/oauth2/token')
5
6
http = Net::HTTP.new(uri.host, uri.port)
7
http.use_ssl = true
8
9
request = Net::HTTP::Post.new(uri.path, { 'Content-Type' => 'application/x-www-form-urlencoded' })
10
11
request.set_form_data({
12
  'grant_type' => 'client_credentials',
13
  'client_id' => '32',
14
  'client_secret' => 'abcdefgh',
15
  'scope' => 'merchant_api_v2'
16
})
17
18
response = http.request(request)
19
20
puts response.body

1
import requests
2
3
data = {
4
    'grant_type': 'client_credentials',
5
    'client_id': '32',
6
    'client_secret': 'abcdefgh',
7
    'scope': 'merchant_api_v2'
8
}
9
10
response = requests.post('https://merchant-auth-sandbox.afterpay.com/v2/oauth2/token', data=data)
11
print(response.json())

Access token response

The response to a successful authentication request includes the full JWT access_token. In the example below, the token is shortened for brevity.

1
{
2
  "access_token": "eyJraWQiOiIwMzllNDBlMy0wYjM5LTQ3MTktOGFjNS05ZmE0OWRiMjQ3MWMiLCJhbGciOiJSUzI1NiJ9.eyJzd…",
3
  "scope": "merchant_api_v2/read merchant_api_v2/reverse merchant_api_v2/void merchant_api_v2/deferred_capture merchant_api_v2/capture merchant_api_v2/manage merchant_api_v2/initiate merchant_api_v2/cancel_subscription merchant_api_v2/direct_capture merchant_api_v2/refund merchant_api_v2/auth",
4
  "token_type": "Bearer",
5
  "expires_in": 86399
6
} 

API requests with token

See the following example where the access_token field is provided in the Authorization header of the request to access a secure API:

1
GET /v2/configuration HTTP/1.1
2
Host: global-api-sandbox.afterpay.com
3
Authorization: Bearer eyJraWQiOiIwMzllNDBlMy0wYjM5LTQ3MTktOGFjNS05ZmE0OWRiMjQ3MWMiLCJhbGciOiJSUzI1NiJ9.eyJzd…