Voids and Returns

Introduction

After a "SALE" has been completed, there are two options how to reverse it:

  • 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 after a "SALE" has been settled

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), on the following example the orderId has been used as a referenced transaction:

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

2. Secondary transaction

You can use the orderId and POST it against the orders/{orderId} endpoint to perform a return or a void.

Please note, that in case of a VOID, it is only possible to cancel full transaction amount, partial void is not possible.

// 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"
}
{
  "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.