Overview

Pay Advantage provides an API for simpler integration into existing systems and applications; perfect for clients who need to automate their payment processing. 

The API has been written as a RESTful API and classes can be accessed using standard POST, GET, PUT, and DELETE actions. Responses are returned using JSON and examples of responses are included for easy reference.

A fully functioning Sandbox environment is available for testing which consists of a test web panel, test API and pre-filled test data.

 

Accessing Live API

Access to the Live API is restricted. Once you have completed testing your integration please schedule a call with our API on-boarding team who can cover off some security and scheme requirements before taking your application live. Please ensure you read the below section on "Restrictions, Performance & Best Practice" to ensure your integration is suitable.

 

Setup

To setup the API first ensure you are the administrator of the account, then click on the more menu on the left hand side of the client panel and click on API. From here you can create API credentials, register an IP and create a sandbox/test account. Both the live and test hosts have separate client portals and you will need to create a set of credentials and register IP's in each.

 

IP Restriction

For greater security access to the API must be granted by registering the IP address you intend on accessing the API from under the API Setup options. If you do not register the IP you will receive and invalid IP error when attempting to authenticate. If this occurs you must sign in to the web panel and register the IP.

 

Sandbox/Testing

A replica of our live system is available for testing. Please visit the support article Sandbox Environment & Transaction Simulation for information on using this system.  

 

Hosts

Live API https://api.payadvantage.com.au/v3

Test/Sandbox API https://api.test.payadvantage.com.au/v3

 

 

Authorisation and Authentication

A call is made to the endpoint below with form variables “username=[your_username]”, “password=[your_password]” and “grant_type=password". Here is an example of a typical request:

POST https://api.test.payadvantage.com.au/V2/token HTTP/1.1 
Content-Type: application/x-www-form-urlencoded 
Host: api.test.payadvantage.com.au 
Content-Length: 94 
Expect: 100-continue 
Connection: Keep-Alive 
 
grant_type=password&username=506530e9283d7w0e4i7b4t783&password=038264873276ns7980427js4f40611

 

For a successful authentication the result is a JSON object of the form below

{
   "access_token":"token string contents",
   "token_type":"bearer",
   "expires_in":599
}

 

For an unsuccessful authentication the result is a JSON object of the form below

{
"ErrorCode": "invalid_account",
"Messages": ["The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource, or may need an account of some sort."]
}

 

The authorization token returned from a successful authentication must be included in any subsequent requests as an authorisation header called “Bearer”. Authentication tokens have an expiry (in seconds) which is returned in the “expires_in” field as shown above. After this time any request to the API with an expired token will return an unauthorized response (401) and a new token will need to be requested and appended to new requests.

<html>
  <body>
    <form action="https://api.payadvantage.com.au/v2/token" method="post">
      <input name="grant_type" value="password" type="hidden" />
      <input name="username" value="ENTER USERNAME" type="hidden" />
      <input name="password" value="ENTER PASSWORD" type="hidden" />
      <input type="submit" value="Submit">
  </body>
</html>

 

 

Restrictions, Performance & Best Practice

We aim to make our API as fast and accessible for our users as possible. Due to the fact that we have no real control over how you choose to make use of the API we have put in place appropriate restrictions to prevent inefficient and redundant requests to our API. 

Please keep in mind our API should be used for the processing of payments only. Data relating to transactions, customers and payments should be maintained first in your own database with payments simply sent to us for processing and obtaining the outcome. You should not reply on our API as the primary source of your applications data.

 

The following items are returned in each response’s headers:

X-Rate-Limit-Limit - The number of requests allowed in the current period

X-Rate-Limit-Remaining - The number of requests remaining in the current period

X-Rate-Limit-Reset - The number of seconds left in the current period

 

The below limits should be observed and are amended from time to time. 

Item Upper Limit
Request Limit 40 per 60 seconds
Create Customer 20,000 per day
Create BPAY CRNs 20,000 per day
Create Debit Batches 10 per day
Create Debit Instructions 20,000 per day
Debit Instruction Value $1,000,000 per day
Max Instructions per Batch 9,999

If one of the above limits is reached you will receive a response code with a message similar to the one below and we suggest you retry the request after allowing enough time for the limit to reset.

429 too many requests
{“Message” : “Request limit exceeded” }
 

Recommended processing times

We recommend scheduling batch processing of information to take place between 4am to 4pm AEDST, Monday to Saturday. 

Where possible avoid scheduling batch processing of information between 8pm and 3am to avoid issues with timezone differences, interbank processing of information and interruption of service due to urgent upgrades.

 

Performance

To get the best performance from the API it is advisable to always:

- Use filters to narrow down search results.

- Explicitly state which fields you want returned when selecting records.

- Always create Debit Instructions in batches (up to 1,000 per request).

- Use the controller (/debit_instructions_failed) to obtain debit failures for handling in your local system.

- Acknowledge debit fails in batches (up to 1,000 per request) ie (/debit_instructions/{code},{code}/ackfail)

Have more questions? Submit a request

Comments