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

This will return a single record of a payment specified by the code.

GET: /payments/{code}

An example of a payment record is shown below;

{
    "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

This returns an array of multiple payment records. Payment records 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 in our article on Retrieving and Filtering lists.

GET: /payments

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. 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.