API Authentication

Option 1 - Oauth 2.0 Authentication

This solution is ideal for Pay Advantage partners who need to set up multiple accounts for the merchants they support. For instance, a software provider may require all their clients to receive payments, necessitating each client to sign up with Pay Advantage. To ensure the best customer experience, the OAuth sign-in flow should be used.

Clients will simply log into your application and choose to authenticate with Pay Advantage. The browser will redirect them to sign into their Pay Advantage account. Once this process is complete, your software will store their access token and refresh token.

There are two options available when using the OAuth flow to authenticate your clients.

Secret-based authentication

Secret-based authentication is ideal for systems with a server capable of securely storing the client secret. This secret is used when the code challenge is required to request an access and refresh token. Access tokens expire after 30 minutes and you will need use the refresh token to obtain a new access token.

PKCE-based authentication

PKCE (Proof Key for Code Exchange) authentication is best suited for applications with only a front-end presence. It enhances security by validating that the code shared with the authentication server is part of the request to obtain the access and refresh token. Access tokens expire after 30 minutes and you will need use the refresh token to obtain a new access token.

For detailed information refer to: Connecting merchants to your apps

Option 2 - Password Based Authentication

Your API credentials can be found in the user portal under API in the side menu under Integrations. Your API username and password will be listed here.

To authenticate your API requests an initial call is made to the token endpoint with credentials passed as JSON in the request body.

Open this guide for a step-by-step walkthrough of the authentication API

Your username and password should be used in the parameters username and password respectively. The parameter grant_type should be passed as "password".

An example of an API authentication request. Authentication API details

curl -L -X POST '<https://api.payadvantage.com.au/v3/token'>  
 -H 'Content-Type: application/json'  
 -d '{  
       "grant_type": "password",  
       "username": {your_username},  
       "password": {your_password}  
     }'  

An example of a successful response

STATUS 200 // Successful
{  
  "access_token": nvawklcbawuilfbuwekalbvuewlauewiLNFWELIFUELNF,  
  "token_type": "bearer",  
  "expires_in": 1800  
}

A successful response will return an access_token that must be included in any subsequent requests as an authorisation header called bearer.

These access tokens have an expiry in seconds as shown in the response. After this time any request to the API using an expired token will return a STATUS 401 unauthorised response, and a new token will need to be requested.

📘

Do not call the authentication API for every request if you still have a valid token. The API is rate limited and you account will be temporarily blocked if this endpoint is called too often.

An unsuccessful response will return a STATUS 4NN with an error code such as "invalid account" and a message to give more context to why the error occurred.

An example of the token storage and usage can be found in our public GitHub repository https://github.com/pay-advantage/sample_js_webhook_app

An example of using access token for API calls

curl -L -X POST '<https://api.payadvantage.com.au/v3/...'>  
 -H 'Authorization: Bearer {access_token}'  
 -H 'Content-Type: application/json'  
 -d '{  
       ...  
     }'