Refunding Payments

Pay Advantage allows refunding of payments made by Credit Card and Direct Debit (BPAY refunds are not available).

As with payments, a refund is never effectively successful, it just hasn’t failed. There is even the potential for a refund to be sent back at a later date, but this is very unlikely. Changes to refunds can be detected using the “Dateupdate” and “Status” fields. It is also important that a refund may be “failed” and then a non-failed status and back again any number of times. This is due to the possibility of reattempts. Do not assume “failed” is an end condition.

If a refund’s status is set to “Failed” you can identify the date and reason by interrogating the Attempts and looking at the record marked as “IsCurrent”. If a refund is reattempted then a new Attempt record will be created and the status will change to “pending” (even if only for a very short while).

Attempts indicate the refund is going back to the original account used with the payment being refunded. This is identified by the “IsOriginatingAccount” field. It is possible to refund to an alternative bank account, but only via the Pay Advantage application. Refunds that have been forced from chargebacks by external agencies can be detected using the “IsMerchantInitiated” field being set to false. Please note that you cannot modify these refunds.


Create a Refund - POST: /refunds

To process a refund you must supply the reason and the original payment code. You can also supply your own reference number to attach to the refund (this is optional). Once processed the customer will be refunded the entire payment amount including any on-charged fees. You will then be charged a refund fee and any costs associated with the original payment to cover the fees incurred in processing the transaction. Partial refunds are currently not supported.

An example request is shown below:

    "reason": "Changed Mind",
    "payment" : {"code": "AAA000"},
    "ExternalID": "Your ID"


A successful request will return the refund record as per GET using refund code.

Cancelling a Refund - PUT: /refunds/{code}?cancel=true

Not all refunds are able to be cancelled (e.g. once a refund has been processed it cannot be cancelled). To cancel a refund you must provide a cancel reason in the request body as


    "Reason”: “Reason for cancelling”


For a correctly formatted request, you will receive either a 204 success response with no content or a 422 fail response indicating the reason why the refund could not be cancelled:

    "ErrorCode”: “unprocessable”,
    "Messages”: [ “Reason for failure”, ... ]


Refund Statuses

payment_clearing If the payment fails then the refund is not necessary, so the refund waits for the payment to clear
chargeback_clearing If the refunded payment has been settled then a chargeback retrieves this payment from the Merchant (you). The refund to the Customer will not continue until the chargeback clears
pending The refund is ready to be attempted, but has not yet been processed.
processing The refund has been accepted by the payment gateway
processed The refund has been accepted by the payment gateway
failed The refund failed to process
cancelled The refund was cancelled by an intended action or the original payment failed
undetermined A gateway issue has occurred and the refund’s status is not yet known


Refund Record - GET: /refunds/{refundcode}

Retrieves a single refund record matching the code provided..

    "Code": "AAA000",
    "DateCreated": "2019-01-20T11:50:43.235",
    "DateUpdated": "2019-01-21T13:51:42.14",
    "Amount": 49.12,
    "ExternalID": null, // This is your identifier
    "Status": "processing",
    "Payment": { "Code": "AAA111" },
    “IsMerchantInitiated”: true,
    "Attempts": [
        "IsCurrent": true,
        "IsOriginatingAccount": false,
        "DateCreated": "2019-01-21T13:51:41.243",
        "DateFailed": null,
        "FailReason": null,
        "IsCurrent": false,
        "IsOriginatingAccount": true,
        "DateCreated": "2019-01-20T11:50:43.235",
        "DateFailed": null,
        "FailReason": null,


List of Refunds - GET: /refunds

Refunds are automatically sorted by the Date Created column. The data returned will be identical to the above example except returned in an array, along with pagination metadata.

The following fields are filterable: PaymentCode, Amount, DateCreated, DateUpdated, ExternalID


An example response is shown below:

    "Records": [
        { as above },
        { as above }, ...
    "Meta": {
        "page": 0,
        "recs_per_page": 100,
        "total_recs": 1


Have more questions? Submit a request