Authentication

The Payment API uses Basic HTTP Authentication, a simple authentication scheme built into the HTTP protocol, as specified by RFC 7617.

All Payment API endpoints require this form of authentication. Failure to correctly authenticate an API request will result in a "401 Unauthorized" response.

Following OAuth 2.0 industry standards, Afterpay provides the merchant a Client ID that uniquely identifies the merchant as the entity initiating a transaction. Afterpay also provides a private Client Secret, a character string known only to the Afterpay and the respective merchant. There will be separate credentials to identify the request from the client app, web and backend.

These credentials will be different for each merchant.

Submit client credentials and receive temporary access-oauth-token details.

The access token generated will be valid until it is expired.

As is standard with OAuth 2.0 the HTTP header for this request defines Content-Type as application/x-www-form-urlencoded.

HTTP Request

POST https://<hostname>/oauth2/token

Request body

Name	Type	Mandatory	Description	Comment
grant_type	string	yes	scope of access	must be client_credentials

Request headers

Parameter	Description
Content-Type	application/x-www-form-urlencoded
Accept	application/json
Authorization	Basic Base64(clientId:clientSecret); clientId:clientSecret has to be encoded using Base64

Consider the following example

clientId	clientSecret
afterpay	merchantABC

📘
In conventional HTTP terms, "clientId" is the username and clientSecret" is the password. Each merchant account has unique API credentials.`

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

PLAIN TEXT	BASE64 ENCODED
afterpay:merchantABC	YWZ0ZXJwYXk6bWVyY2hhbnRBQkM=

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.

Final Header Authorization: Basic YWZ0ZXJwYXk6bWVyY2hhbnRBQkM=

📘
Security Notice Please note that the base64-encoding of the Authorization header is unrelated to security. All HTTP headers and bodies (for both requests and responses) between the Merchant and Afterpay are encrypted with TLS. The reason for base64-encoding is solely to comply with the RFC 7617 standard, which allows non-HTTP characters and multibyte strings to be used for Basic HTTP Authentication.

Sample Example

curl --location --request POST https://auth-uat.paynow-prod.afterpay.com/oauth2/token \
   -H "Content-Type: application/x-www-form-urlencoded" \
   -H "Accept: application/json" \
   -H "Authorization: Basic YWZ0ZXJwYXk6bWVyY2hhbnRBQkM="\ 
   -d "grant_type=client_credentials"

Response body

Name	Type	Mandatory	Description	Comment
access_token	string	yes	The token authorising access to secure API endpoints	In the example "access_token" is eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
expires_in	number	yes	The amount of time in seconds for which the oauth token is valid	In the example 3600 seconds is 1 hour
token_type	string	yes	The type of access token	In this case "Bearer"

Sample Example:

Status: 200 OK

{
    "access_token": "eyJraWQiOiJManp0Z0RCQ1BlVmhBZU1sQnkrYlNTSjQrN1BxTXRxd1F2UStVbW9VVGRrPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiI0dWhtbmY2bzQzZGk2OXAwODc1bHY5MjduOSIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoicGF5bm93LXVhdC5hZnRlcnBheS5jb21cL3YxXC9jYXJkc1wvdmVyaWZ5IiwiYXV0aF90aW1lIjoxNjkxMzg0Njc3LCJpc3MiOiJodHRwczpcL1wvY29nbml0by1pZHAuYXAtc291dGhlYXN0LTIuYW1hem9uYXdzLmNvbVwvYXAtc291dGhlYXN0LTJfeDA1RUxNYUFpIiwiZXhwIjoxNjkxMzg4Mjc3LCJpYXQiOjE2OTEzODQ2NzcsInZlcnNpb24iOjIsImp0aSI6IjRhNGY2OWZmLTEzZDktNDU0YS05MDNiLWUwZmQxMDdjMmRlYiIsImNsaWVudF9pZCI6IjR1aG1uZjZvNDNkaTY5cDA4NzVsdjkyN245In0.Dywr4_0f1wA3wkcVqlMlAtplG8QKW2FDFPWJl1ICL04CTcFsd1tk1UAIp4lsZqT1-QqOvqeh8x2B6HqEmBDeNc6L_SLcScXBl_4yjc_fwMdxmN1cf00EeiJa7Ph4S8uWAGn1GNv11w9QHeIxI44WaUYiY_4Mf8T4lleBXCZvvsU92B7cY5RHSBk12ksS6TdkNidaIE1dstyiRxVf8yJPOmKN__qgPV0MmVWXi0a9cvWN9SEKhpr_FUfQ1PRx8Sl2EIFs1hotD62S0cv1sb4-qdB0qVGnyStgLGkE0DVHQneM2CYcrmfUHb8hIfqmgA3ehN6gFaMtoSMXlcU8pfIuEA",
    "expires_in": 3600,
    "token_type": "Bearer"
}

Response headers

Parameter	Description
Content-Type	application/json; charset=UTF-8

Errors

Can return the following specific error responses

Status Code	Type	Description
400	Bad Request	will be returned if the Authorization is invalid (clientId:clientSecret encoded using Base64 is invalid)

Status: 400 BAD REQUEST

{
    "error": "invalid_client"
}

Categories of Access oauth tokens

There are 3 types of access oauth tokens

Access-card-oauth-token - to be used in Card Verification & Tokenisation API.
Access-admin-oauth-token - to be used in all API requests from merchant backend.
Access-web-oauth-token - to be used in pre-built UI (iframe)

📘
The client credentials (clientId and clientSecret) are different to generate each of the above access oauth token