Voids and Returns

Introduction

After a sale is made, a merchant has 2 options for reversing this:

  • A 'void' is performed on a primary transaction to cancel the payment on the same day before any money is actually moved, effectively just cancelling it out
  • A 'return' is performed on a primary transaction to refund the payment on a following day

This section shows an example of how to void or return an existing transaction using the Payment API:

Payments API

1. Initial transaction

Refunds and voids must be performed on an existing primary transaction , by making a request to one of the 'secondary' transaction endpoints using either the transaction id or the order id), here we'll be using the orderId we've generated from the following previous transaction response.

{
  //...
  "ipgTransactionId": "84607424082",
  "orderId": "R-c839c8ab-20fe-4f8c-b0e0-23e46ceaf1b8",
  // ...
}

2. Secondary transaction

Using the orderId we have and POSTing the following ReturnTransaction requestType (or in the case of a same day void, VoidTransaction) against the orders/:orderId endpoint, we can issue the refund for the given amount.

// POST /orders/R-c839c8ab-20fe-4f8c-b0e0-23e46ceaf1b8
{
  "requestType": "ReturnTransaction",
  "transactionAmount": {
    "total": "12.99",
    "currency": "EUR"
  }
}
// POST /orders/R-c839c8ab-20fe-4f8c-b0e0-23e46ceaf1b8
{
  "requestType": "VoidTransaction",
  "transactionAmount": {
    "total": "12.99",
    "currency": "EUR"
  }
}
{
  "clientRequestId": "ce9e44d6-3bd1-414e-9077-033723febb69",
  "apiTraceId": "YxswOZ9erPivxfpP6BmqjQAAAJY",
  "responseType": "GatewayDeclined",
  "ipgTransactionId": "84607424380",
  "orderId": "R-28a2e2a9-f44c-476e-a38a-d6e3954245c7",
  "transactionType": "RETURN",
  // ...
  "error": {
    "code": "10601",
    "message": "Total amount passed is more than the Return/Void amount."
  }

πŸ‘

Example complete!

This transaction is now either refunded or voided (depending on the option chosen) and can be considered complete. Note that if the specified total value is higher than the amount of the original transaction, the error message shown in the example above will be returned.


Want a quick overview?