Payments

All payments are associated with either a Customer or a Debit Instruction. Once a payment is attempted we allow a small window for any failures to be reported (typically 2-3 business days). If no failure has been reported within this window then it is considered "cleared" and will then be settled to your account. BPAY payments are the only exception as they clear/settle immediately.

All payment types can fail (for a number of reasons) in which case the “DateFailed” and “FailCode” fields will be populated. Be aware that a payment may fail after settlement in the instance of a late failure or charge-back and this could occur many days, months, even years after settlement. It is more correct to consider a payment as "not failed" rather than succeeded; however for most scenarios you can consider a settled payment as a "success". Charge-backs and late dishonours are very rare for most businesses.

View PaymentTypes & FailCodes

Payment Record - GET: /payments/{code}

An example of a payment 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. 

{
    "Code": "our system id",
    "DatePaid": "2015-04-29T00:00:00",
    "DateFailed": null,
    "DateClears": "2015-04-30T00:00:00",
    "DateSettled": "2015-04-30T08:34:33.013",
    "FailCode": null,
    "FailReason": null,
    "Amount": 300,
    "AmountIncFees": 300,
    "ReadyToSettle": true,
    "PaymentType": "bpay_bank_account",
    "ExternalReference": null,
    "BPAYReference": "123456789",
    "SettlementCode": "AABB12"
}

Lists of Payment records - GET: /payments

Payments are sorted by Date Paid (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

{
  "Records":
  [
    {
        "Code": "our system id",
        "DatePaid": "2015-04-29T00:00:00",
        "DateFailed": null,
        "DateClears": "2015-04-30T00:00:00",
        "DateSettled": "2015-04-30T08:34:33.013",
        "FailCode": null,
        "FailReason": null,
        "Amount": 300,
        "AmountIncFees": 300,
        "ReadyToSettle": true,
        "PaymentType": "bpay_bank_account",
        "ExternalReference": null,
        "BPAYReference": "123456789",
        "SettlementCode": "AABB12"
    },
    {…}
  ],
  "Meta": { "page":0, "recs_per_page": 100, "total_recs":594 }
}

Managing Failed Payments

You can get the list of failed payments for a specific date using the following method:

GET: /payments_failed/{ddMMyyyy}

Avoid using today's date as payments can fail at any time during the day and it is best to query failures at least one day in arrears.

View FailCodes

If required you can create more complex filters using the fields available for filtering on payments. For example:

Failed payments for a week.

GET: /payments?datefailedfrom=20042014&datefailedto=26042014

Failed payments after a date of more than a specific amount.

GET: /payments?datefailedfrom=20042014&amountfrom=100

Managing Settled Payments

You can get the list of settled payments for any day using the following method:

GET: /payments_settled/ddMMyyyy

If using “today” as the date, it is recommended to run this as late in the day as possible (6pm - Midnight) so that any settlements that occurred during the day are captured.