Registering an App (Enabling OAuth)

Introduction

OAuth allows you to access a Pay Advantage Merchant’s information and perform actions on their behalf using our API. You must first register your application with Pay Advantage and include information about what permissions your application requires, what it does, and what you do with their information. The Merchant will read this information and decide if they wish to give your App access to their account.

Information on what you can do with the API as an app can be found here.

Registering an App

This is not available to end users and must be done by emailing a request to our support team with the information requested below to [email protected]

AttributeDescription
NameThe name of your app.
DescriptionA brief description of your app.
Privacy URLThe URL to your app’s Terms & Conditions / Privacy Statement. It should clearly describe what you will be using the Merchant’s information for and what functions you will be performing on behalf of the Merchant.
AppUrlThe URL of your app.
RedirectUrlThe URL to direct users to once they have authorised your app. This will need to process the OAuth response and should look something like https://myapp.com/pay-advantage-oauth-callback

For multi instance apps, this should exclude the protocol and domain. The system will return the user to the origin domain with the redirectUrl appended to it.
IconAn icon that will be shown alongside your app name. Both an SVG and a PNG is required.
Enable PKCEEnables PKCE authorisation flow.
See Client Secret and PKCE Flows below.

Note: PKCE and/or Client Secret must be enabled.
Enable Client SecretEnabled Client Secret authorisation flow.
See Client Secret and PKCE Flows below.
Note: PKCE and/or Client Secret must be enabled.

Permissions

The permissions that your app needs to function. See below.

Permission NameDescription
customer_readAbility to read the merchant’s customers.
customer_writeAbility to create, update and delete the merchants customers.
direct_debit_readAbility to read the merchant’s direct debits.
direct_debit_writeAbility to create, update and delete the merchants direct debits.
payment_readAbility to read the payments and refunds.
payment_writeAbility to create payments.
refund_writeAbility to refund payments.

📘

Note: When a merchant authorises an app, they must accept all permissions that the app requests. If the app requires additional permissions in the future, you must get the merchant to re-authorise the app.

Client Secret and PKCE Flows

Client Secrets and PKCE are methods of ensuring that the caller resolving an authorisation code is legitimate. We require that apps have Client Secret and / or PKCE enabled.

If you cannot guarantee the safety of the Client Secret, then you must use PKCE. The Client Secret should NEVER reside in “public” code that could be accessed by consumers of your app (javascript, device apps). It is intended for server to server communication.

The PKCE flow creates a verifier on the public app when it is needed. A hash of the verifier is sent during the initial request and the un-hashed verifier is sent for validation when resolving the authorisation code.

Note: PKCE and Client Secrets can be used together.