Connecting/Disconnecting to your Pay Advantage App
Connecting Merchants To Your Pay Advantage App
Pay Advantage uses OAuth 2.0 to allow merchants to connect to your app.
An overview of connecting a merchant to your app.
- Your App directs the User’s browser to Pay Advantage’s authorize URL.
- The User logs into Pay Advantage and authorises your app for one of their Merchant Accounts.
- The User’s browser is redirected to your site with a “code”.
- Your App then sends this code to the Pay Advantage API in exchange for an Access Token and a Refresh Token.
- Your App then has scoped access to the authorized Merchant Account using the Access Token.
-
It is your App’s responsibility to ensure that the Refresh Token is kept protected. If a malicious party is able to get the Refresh Token, then they will be able to generate Access Tokens and access the Merchant’s data.
Which Oauth 2.0 option to use?
iOS and Android application authentication solution (PKCE Auth)
This option is ideal for iOS and Android based applications that need to make API calls directly from the application. If the application has a server, it is preferred to pass the access token request to the server as seen in the following two authentication options.
Single page application authentication solution (PKCE Auth)
This option can be implemented using iOS, Android and Single Page Applications. It ensures that the server makes the request for authentication and access is then controlled via server to server communication.
Server stored secret key authentication (Secret Auth)
This option is the simplest to implement. The request to obtain the token is created using a secured secret key. This option relies on the secret kept safe and then provides an easy way to authenticate and complete server to server communication.
Set Up Oauth (Secret Authentication)
Step 1 - Redirect to Pay Advantage
https://secure.payadvantage.com.au/authorize?client_id=800d8763d38c4661859ea5d603d989a2&redirect_uri=https%3A%2F%2Fexample.com%2Foauth_callback&state=eyJpZCI6Mjc4fQ%3D%3D&response_mode=query&response_type=code&grant_type=authorization_codeClientID refers to the code given when you created Oauth details
Redirect URI is the location to redirect on your app, once the user has logged into Pay Advantage
State is data you want to receive on the redirect, incase you need to recall some data about the customer
Response mode: "query" is the most common use case
Response type: Use "code"
Grant type: Use "authorization_code"
Step 2 - Handle the redirect
The assumption that your app is example.com in this scenario. You application will receive the redirect with the authorisation code.
Success
<https://example.com/oauth_callback?code=eyJhbGciOiJFUz...&state=eyJpZCI6Mjc4fQ%3D%3D>Failure
<https://example.com/oauth_callback?error=access_denied&error_description=The%20user%20denied%20the%20request&state=eyJpZCI6Mjc4fQ%3D%3D>Step 3 - Validate the Authorisation Code
Using the received authorisation code, send it via an API request to the https://secure.payadvantage.com.au/authorize endpoint. Details about what can be sent to this endpoint are available: https://docs.payadvantage.com.au/reference/authentications_post-1
You will also send the client secret in this API call, this secret needs to be protected and never shared. This is the reason this API call needs to be made from a backend system that is protected.
Step 4 - Handle the API Reponse
The response from the authorise API will return an Access key and the Refresh Key. The Refresh key is used to obtain new access keys. The Access key allows you to call other API's and it has a expiry. Once expired use the /authorise endpoint to exchange the refresh token for a new access token.
Set Up Oauth (PKCE Authentication)
Step 1 - Redirect to Pay Advantage
https://secure.payadvantage.com.au/authorize?client_id=800d8763d38c4661859ea5d603d989a2&redirect_uri=https%3A%2F%2Fexample.com%2Foauth_callback&state=eyJpZCI6Mjc4fQ%3D%3D&response_mode=query&response_type=code&code_challenge=qjgVB69kA8jJV2KjOSRAntTng3Jd5n5OI3y5wB4HFIE=&code_challenge_mode=S256&grant_type=authorization_codeClientID refers to the code given when you created Oauth details
Redirect URI is the location to redirect on your app, once the user has logged into Pay Advantage
State is data you want to receive on the redirect, incase you need to recall some data about the customer
Response mode: "query" is the most common use case
Response type: Use "code"
Code challenge:
The Code Challenges protects apps by only allowing the initiator the ability to resolve the authorization code.
Before the authorization request is made, the app will create a “code verifier”. This is a cryptographically random string using the characters A-Z, a-z, 0-9, and the punctuation characters -._~ (hyphen, period, underscore, and tilde), between 43 and 128 characters long.
Then the app will then use a BASE64-URL encoded string of the SHA256 hash of the code verifier as the code_challenge, and “S256” as the code_challenge_method.
Code challenge mode: Use "S256"
Grant type: Use "authorization_code"
Step 2 - Handle the redirect
The assumption that your app is example.com in this scenario. You application will receive the redirect with the authorisation code.
Success
<https://example.com/oauth_callback?code=eyJhbGciOiJFUz...&state=eyJpZCI6Mjc4fQ%3D%3D>Failure
<https://example.com/oauth_callback?error=access_denied&error_description=The%20user%20denied%20the%20request&state=eyJpZCI6Mjc4fQ%3D%3D>Step 3 - Validate the Authorisation Code
Using the received authorisation code, send it via an API request to the https://secure.payadvantage.com.au/authorize endpoint. Details about what can be sent to this endpoint are available: https://docs.payadvantage.com.au/reference/authentications_post-1
Pass in the code verifier details to prove your application was the one that send the code challenge
Step 4 - Handle the API Reponse
The response from the authorise API will return an Access key and the Refresh Key. The Refresh key is used to obtain new access keys. The Access key allows you to call other API's and it has a expiry. Once expired use the /authorise endpoint to exchange the refresh token for a new access token.
API Details
Live URL
https://secure.payadvantage.com.au/authorizeTest URL
https://test.payadvantage.com.au/authorizeParameter | Description | Required |
|---|---|---|
client_id | This uniquely identifies your app and will be provided during the registration of your app. | True |
redirect_uri | The URI that the browser will be directed to once the OAuth process is complete. | True |
state | Data that will be sent back to you in the response. | Recommended |
response_mode | Controls how the response will be sent back to the redirect_uri. Must be one of:
| Recommended |
response_type | For now, we only accept “code”. | Required |
login_hint | False | |
code_challenge | See Code Challenge (PKCE) below. | False |
code_challenge_method | The method used to verify the code_challenge:
| False |
grant_type | For now, we only accept “authorization_code” | True |
instance_id | Identifies the instance of the app that this is for. | False |
instance_name | Default display name for the instance of the app. When not supplied, this will default to the referrer’s origin. The user has the ability to rename this to something that makes sense to them. For example “Tim’s iPhone” on a device-based app. | False |
Extra details are located under the Oauth section
Access Tokens
The access token request is made using the following API once the Authorisation Request has been made and the response received. For details on how to call the access token request refer to the following documentation.
https://docs.payadvantage.com.au/reference/authentications_post-1
Updated 14 days ago