Debit Instructions

Debit Instructions are individual instructions to debit an amount from a bank account or a stored/tokenised credit card. With debit instructions we don't manage any scheduling of the debit, we simply process the batch and record the success or failure of each instruction and nothing more.


Debit Batches

Before creating debit instructions you must first create a debit batch container which will be used to control certain functions like the debit date etc for all of the instructions. See debit batches for more information.


On-charging Fees

If you decide to on-charge debit fees directly to your customers then you can make use of the OnchargeFees field to simplify your processing effort and let us manage this for you. Debit Fees will be calculated when the Debit Instruction is processed for payment (typically the DateToDebit from the DebitBatch). The fee will be added to the payment at this point for on-charged debit instructions.


Group Key Feature

Any Debit Instruction may have a Group Key assigned. As the name suggests, this field is used for grouping related instructions together. The same group key may be used across any number of batches over any period of time.

Please be aware that, when using the Group Key and On-charge features together, any on-charged fee that dishonours will be added to the next on-charged debit instruction with a matching group key. This is by design to assist in fee management and recovery. It is only a real concern if on-charging is used and the group key is shared between different customers. One solution in this scenario is to add a unique suffix to group key for each customer in that group (for example “AB001-01”, “AB001-02”) so these can be filtered at a later date using the first n characters.


Debit Instruction Record - GET: /debit_instructions/{code}

An example of a Debit Instruction record is shown below. This is the record that is returned on request of a single record and an array of these records is returned when requesting lists. Greyed fields are fields not readily displayed on Pay Advantage screens, but still useful and necessary information such as identifiers and calculated fields.

  “Code”: “our system id”,
  “DateCreated”: “2014-04-23T11:07:13.322”,
  “IsProcessed”: true,
  “BSBNumber”: “012345”,
  “AccountNumber”: “111111111”,
  “AccountName”: “Test Account”,
  “CreditCardCode”: null,
  “Amount”: 87.50
  “RemitterName”: “XYZ Trading”,
  “OnchargeFees”: true,
  “IsFailAcknowledged”: false,
  “DebitBatch”: {“Code”: “our system id”, “DateToDebit”: “2014-04-25T00:00:00”},  
    “Code”: “our system id”,
    “DatePaid”: “2014-04-26T00:00:00”,
    “DateFailed”: null,
    “FailCode”: null,
    “FailReason”: null,
    “Amount”: 88.45
  “URI”: “/debit_instructions/{code}”


Lists of Debit Instructions - GET: /debit_instructions

Debit Instructions are sorted by DateCreated (descending) by default. The list is paged and will always return the first page of records unless paging parameters are added as described previously. An example of the response is shown below:

      "Code": "999999991111",
      "DateCreated": "2015-01-20T09:14:12.847",
      "IsProcessed": true,
      "BSBNumber": "000999",
      "AccountNumber": "123456",
      "CreditCardCode": null,
      "AccountName": "Low Value Test",
      "Amount": 1.00,
      "Reference": "YOUR_REF",
      "RemitterName": "PAY ADVANTAGE",
      "OnchargeFees": false,
      "IsFailAcknowledged": false


Creating Debit Instructions - POST: /debit_instructions

You can create Debit Instructions one at a time or many at once (up to 1000 at a time). The recommended (most common) way to create debit instructions is many at a time (a batch) as shown below:

    “Code”: “id of debit batch to add instructions to”
      “BSBNumber”: “012345”,
      “AccountNumber”: “67890”,
      “AccountName”: “Test Account”,
      “Amount”: 123.45,
      “Reference”: “Your Ref”,
      “OnchargeFees”: true
      “CreditCardCode”: “CAB231”,
      “Amount”: 85.45,
      “Reference”: “Your Ref”,
      “OnchargeFees”: false
    { … }, { … }, { … }


To add an individual debit instruction, you still use the method above with only a single item listed in the “DebitInstructions” array.


Deleting a Debit Instruction - DELETE: /debit_instructions/{codes}

A debit instruction can be deleted as long as the “DebitBatch” it belongs to is not confirmed, authorised, or processed. You can delete a single instruction or multiple instructions by separating the {code} with a comma up to a maximum of 1,000 codes per delete request.

DELETE: /debit_instructions/{code}
DELETE: /debit_instructions/{code},{code}



Managing Failed Debit Instructions

To simplify the management and handling of debit instructions Pay Advantage provides a helper method to quickly retrieve and “acknowledge” debit instruction failures. In essence as we receive failures on individual debit instructions (which can take several business days for bank accounts) we will combine these across all batches and make them available for handling in your own system.Once acknowledged the failure will then be omitted from results.


Retrieve all failed instructions that have not been acknowledged Recommended Method 

GET: /debit_instructions_failed


Retrieve failed instructions not acknowledged (for specific date)

GET: /debit_instructions_failed/ddMMyyyy


If retrieving using todays date, be aware that instructions can fail at any time during the day and it is best to retrieve these at least one day in arrears or not specify a date at all.


If required you can create more complex filters using the fields available for filtering on debit instructions, for example:

Failed debit instructions for a week that have not been acknowledged


Failed debit instructions for a batch after a date that may or may not have been acknowledged

GET: /debit_instructions?debitbatch.code=xyz&payment.datefailedfrom=27042014


Alternatively you can also query settled payments to only retrieve payments that have cleared and settled to your bank account.


Acknowledging Failures

The API contains a feature to mark failures as acknowledged. This provides a fast method for identification of which records have been dealt with. To acknowledge failed debit instructions you can call the following method:

PUT: /debit_instructions/{code},{code}/ackfail

(Separate code using comma, max 1000 codes)

Have more questions? Submit a request