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
Details are located under the Oauth section
Example Requests
<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 - Form Post
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
Example Responses - Query
<https://example.com/oauth_callback?code=eyJhbGciOiJFUz...&state=eyJpZCI6Mjc4fQ%3D%3D>
<https://example.com/oauth_callback?error=access_denied&error_description=The%20user%20denied%20the%20request&state=eyJpZCI6Mjc4fQ%3D%3D>
Example Responses - Query
<https://example.com/oauth_callback#code=eyJhbGciOiJFUz...&state=eyJpZCI6Mjc4fQ%3D%3D>
<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.
Updated 25 days ago