Connecting/Disconnecting to your Pay Advantage App

Connecting Merchants To You 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.

 

Creating the initial Authorization Url

 

Live URL

https://secure.payadvantage.com.au/authorize

Test URL

https://test.payadvantage.com.au/authorize

 

The URL will have the following parameters appended.

 

Parameter	Description
client_id	Required. This uniquely identifies your app and will be provided during the registration of your app.
redirect_uri	Required The URI that the browser will be directed to once the OAuth process is complete.
state	Recommended. Data that will be sent back to you in the response.
response_mode	Recommended Controls how the response will be sent back to the redirect_uri. Must be one of form_post fragment query (Default)
response_type	Required. For now, we only accept “code”.
login_hint	Optional. The email address that the user should log into Pay Advantage as.
code_challenge	Optional See Code Challenge (PKCE) below.
code_challenge_method	Optional The method used to verify the code_challenge S256 Plain (Not Accepted, deprecated)
grant_type	Required For now, we only accept “authorization_code”
instance_id	Optional Identifies the instance of the app that this is for.
instance_name	Optional 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.

 

 

Example Requests

 

Request

https://secure.payadvantage.com.au/authorize?client_id=800d8763d38c4661859ea5d603d989a2&redirect_uri=https%3A%2F%2Fexample.com%2Foauth_callback&state=eyJpZCI6Mjc4fQ%3D%3D&response_mode=form_post&response_type=code&grant_type=authorization_code

 

PKCE Request

https://secure.payadvantage.com.au/authorize?client_id=800d8763d38c4661859ea5d603d989a2&redirect_uri=https%3A%2F%2Fexample.com%2Foauth_callback&state=eyJpZCI6Mjc4fQ%3D%3D&response_mode=form_post&response_type=code&code_challenge=qjgVB69kA8jJV2KjOSRAntTng3Jd5n5OI3y5wB4HFIE=&code_challenge_mode=S256&grant_type=authorization_code

 

Example Responses

 

Successful Response when response_mode is form_post

URL: https://example.com/oauth_callback
Method: POST
Content-Type: application/x-www-form-urlencoded

code=eyJhbGciOiJFUz...&state=eyJpZCI6Mjc4fQ%3D%3D

 

Failed Response when response_mode is form_post

URL: https://example.com/oauth_callback
Method: POST
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=The%20user%20denied%20the%20request.&state=eyJpZCI6Mjc4fQ%3D%3D

 

Successful Response when response_mode is query

https://example.com/oauth_callback?code=eyJhbGciOiJFUz...&state=eyJpZCI6Mjc4fQ%3D%3D

 

Failed Response when response_mode is query

https://example.com/oauth_callback?error=access_denied&error_description=The%20user%20denied%20the%20request&state=eyJpZCI6Mjc4fQ%3D%3D

 

Successful Response when response_mode is fragment

https://example.com/oauth_callback#code=eyJhbGciOiJFUz...&state=eyJpZCI6Mjc4fQ%3D%3D

 

Failed Response when response_mode is fragment

https://example.com/oauth_callback#error=access_denied&error_description=The%20user%20denied%20the%20request.&state=eyJpZCI6Mjc4fQ%3D%3D

 

Code Challenge (PKCE)

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.