Overview

Pay Advantage provides an API for simpler integration into existing systems and applications; perfect for clients who need to automate the process of direct debiting or automate their customer and BPAY facilities.

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/v2

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

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 seperate 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 Lower Limit Upper Limit*
Rate Limit 20 requests per 60 seconds 40 request per 60 seconds
Selecting Records 1,000** 1,000**
Submitting Records 1,000** 1,000**
Create Customer 5,000 per day 20,000 per day
Create BPAY CRNs 5,000 per day 20,000 per day
Create Debit Batches 5 per day 10 per day
Create Debit Instructions 5,000 per day 20,000 per day
Max Instructions per Batch 5,000 9,999

 

* Increases to the upper limit are made on a case by case basis.

** If you need to select or submit more than 1,000 records you should separate into multiple requests.

 

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)

 

 

Sandbox Environment & Transaction Simulation 

A fully functioning Sandbox environment is available for testing which consists of a

  1. test web panel
  2. test API and pre-filled test data.

To create your sandbox account you will need to login to the live client portal, go to sandbox and create your sandbox account. Once created you need to login to the sandbox web client (using the same username/password as live) to generate a set of sandbox API keys.

 

 

Special Handling for Batch Debits

To assist with testing, the sandbox environment simulates various inter-bank processing tasks including processing of debit batches and dishonouring debit instructions.

See Direct Debit Settlement & Clearance Times for information relating to actual processing times for the live environment.

The simulation system will mark debit batches as "Processed" approximately every 10 minutes.

Dishonours are simulated by mapping a fail code to the debit instruction amount decimal value. This process occurs automatically after a debit batch is processed.

Amounts ending in "0" never fail.

Amounts ending with "1" to "9" will dishonour based on the industry wide failure codes (see Payment Dishonour Codes/Reasons).

 

For example:

An instruction with an amount of $10.00 will not fail

An instruction with an amount of $10.05 will fail with the dishonour code 5 (No account or incorrect account number)

 

Special Handling for Credit Cards

To assist with testing, the sandbox environment accepts a number of test credit cards which will return a specific result. Please refer to the test credit card article for more information.

 

 

 

Have more questions? Submit a request

Comments