Refunding Payments

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. However, 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 returned as "Failed", and then a non-failed status and back again any number of times. This is due to the possibility of re-attempts. 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 then looking at the record marked as “IsCurrent”. If a refund is re-attempted 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 as false. Please note that you cannot modify these refunds.


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 “DateCreated” 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


Create a Refund - POST: /refunds

This request must include the "Payment Code", "Amount", and "Reason" fields. At the moment, the amount must match the amount of the payment. Eventually partial refunds will allow for different amounts. 

An example request is shown below:

  "Amount": 123.00,
"Reason": "Product return", "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. For example, once a refund has been processed it can not be cancelled.

To cancel a refund you must provide a cancel reason in the request body as shown:

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

If you receive the fail response it should appear as shown:

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



Have more questions? Submit a request