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.

Before access to the Live API can be switched you will need to contact Customer Service to discuss your implementation.

 

Hosts

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

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

To access each host you will need to create a set of user credentials from the online portal through "Account & Settings>API", you will need administrator privileges to do this.

Both the live and test hosts have separate client portals and you will need to create a set of credentials in each.

Authorisation to use the API features is controlled via registered IP addresses. You need to add any IP Addresses that will be used to access the API otherwise you will not be able to authenticate.

 

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

{"error":"unsupported_grant_type"}

 

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. 

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