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]
| Attribute | Description |
|---|---|
| Name | The name of your app. |
| Description | A brief description of your app. |
| Privacy URL | The 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. |
| AppUrl | The URL of your app. |
| RedirectUrl | The 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. |
| Icon | An icon that will be shown alongside your app name. Both an SVG and a PNG is required. |
| Enable PKCE | Enables PKCE authorisation flow. See Client Secret and PKCE Flows below. Note: PKCE and/or Client Secret must be enabled. |
| Enable Client Secret | Enabled 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 Name | Description |
|---|---|
| customer_read | Ability to read the merchant’s customers. |
| customer_write | Ability to create, update and delete the merchants customers. |
| direct_debit_read | Ability to read the merchant’s direct debits. |
| direct_debit_write | Ability to create, update and delete the merchants direct debits. |
| payment_read | Ability to read the payments and refunds. |
| payment_write | Ability to create payments. |
| refund_write | Ability 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.
Updated 6 months ago