🚧

Development mode

ePOS Payments is in development. You can find the API specification in development here. If you are interested in gaining access when available then please contact us via our support page

Overview

Send a Reversal message from your ePOS system to void or cancel a transaction when a customer decides against the purchase. The transaction must not be settled by this point, i.e., the void is occurring on the same business day as the original transaction. If the transaction is already settled, then a Refund message must be sent. A void or cancel may also be sent in the scenario where a cashier or receptionist is checking the status of a transaction which is continually in progress and they want to free up the ePOS system. It may also be sent in the scenario where there has been a timeout processing a transaction.

The ePOS Payments API supports this functionality as follows:

  • nexo Retailer ReversalRequest message with OriginalPOITransaction information supplied

Sample Workflow

This sequence diagram maps to the steps in the Reversal sample request and response payloads that follow.

Card Not Present ReversalCard Not Present Reversal

Sample Reversal Request Body payload

Below is an example of a nexo Reversal Request payload (body only). In this example the cashier is requesting to void or cancel a payment based on the POI transaction identifier for that payment.

It is worth noting the following:

  • MessageCategory must be set as "Reversal"
  • MessageType must be set as "Request"
  • POIID is set as "CAP" as reversals are card not present
  • OriginalPOITransaction POITransactionID SaleID is set as the original SaleID for the payment transaction to be voided or reversed
  • OriginalPOITransaction POITransactionID POIID is set as the original POIID for the payment transaction to be voided or reversed
  • OriginalPOITransaction POITransactionID TransactionID is set as the original POITransactionID for the payment transaction to be voided or reversed (as returned in original payment response)
  • OriginalPOITransaction POITransactionID TimeStamp is set as the original TimeStamp for the payment transaction to be voided or reversed (as returned in original payment response)
{
  "SaleToPOIRequest": {
    "MessageHeader": {
      "MessageClass": "Service",
      "MessageCategory": "Reversal",
      "MessageType": "Request",
      "ServiceID": "3031207553",
      "SaleID": "Salesystem-00000001",
      "POIID": "CAP"
    },
    "ReversalRequest": {
      "SaleData": {
        "OperatorID": "Operator01"
      },
      "OriginalPOITransaction": {
        "SaleID": "Salesystem-00000001",
        "POIID": "CAP",
        "POITransactionID": {
          "TransactionID": "84549724783",
          "TimeStamp": "2020-10-19T15:19:14"
        },
        "ReversalReason": "CustCancel"
      }
    }
  }
}

Sample Reversal Response Body payload

Below is an example of a successful nexo Reversal Response payload (body only). In this example there has been approval of the request for voiding/cancelling a payment, with the response including the authorization code, and the merchant and cardholder receipts.

It is worth noting the following:

  • Result is "Success"
  • PaymentReceipt holds the Customer and/or Merchant payment receipts
{
  "SaleToPOIResponse": {
    "MessageHeader": {
      "MessageCategory": "Reversal",
      "MessageClass": "Service",
      "MessageType": "Response",
      "POIID": "CAP",
      "SaleID": "Salesystem-00000001",
      "ServiceID": "3031207553"
    },
    "ReversalResponse": {
      "POIData": {
        "POITransactionID": {
          "TimeStamp": "2020-11-11T09:31:37",
          "TransactionID": "84551070428"
        }
      },
      "PaymentReceipt": [
        {
          "DocumentQualifier": "CustomerReceipt",
          "OutputContent": {
            "OutputFormat": "Text",
            "OutputText": [
              {
                "EndOfLineFlag": true,
                "Text": "          Test_STORE           "
              },
              {
                "EndOfLineFlag": true,
                "Text": "         Address Line 1          "
              },
              {
                "EndOfLineFlag": true,
                "Text": "       Address Line 2        "
              },
              {
                "EndOfLineFlag": true,
                "Text": "            Country             "
              },
              {
                "EndOfLineFlag": true,
                "Text": "--------------------------------"
              },
              {
                "EndOfLineFlag": true,
                "Text": ""
              },
              {
                "EndOfLineFlag": true,
                "Text": "11.11.20                   09:31"
              },
              {
                "EndOfLineFlag": true,
                "Text": "       CARDHOLDER RECEIPT       "
              },
              {
                "EndOfLineFlag": true,
                "Text": "--------------------------------"
              },
              {
                "EndOfLineFlag": true,
                "Text": "TERMINAL: 12345                 "
              },
              {
                "EndOfLineFlag": true,
                "Text": "MERCHANT: 123456                "
              },
              {
                "EndOfLineFlag": true,
                "Text": "PAN: XXXXXXXXXXXX1732           "
              },
              {
                "EndOfLineFlag": true,
                "Text": "CARD TYPE: Mastercard           "
              },
              {
                "EndOfLineFlag": true,
                "Text": "MANUAL CANCELLATION             "
              },
              {
                "EndOfLineFlag": true,
                "Text": "MANUAL ENTRY                    "
              },
              {
                "EndOfLineFlag": true,
                "Text": "AMOUNT:                10,00 EUR"
              },
              {
                "EndOfLineFlag": true,
                "Text": "REFERENCE: 84551070428          "
              },
              {
                "EndOfLineFlag": true,
                "Text": "RESERVATION ID: 770235347164    "
              },
              {
                "EndOfLineFlag": true,
                "Text": "AUTHORISATION CODE: 252503      "
              },
              {
                "EndOfLineFlag": true,
                "Text": "              (00)              "
              },
              {
                "EndOfLineFlag": true,
                "Text": "        APPROVED                "
              },
              {
                "EndOfLineFlag": true,
                "Text": "   NO CARDHOLDER VERIFICATION   "
              },
              {
                "EndOfLineFlag": true,
                "Text": " PLEASE RETAIN FOR YOUR RECORDS "
              }
            ]
          },
          "RequiredSignatureFlag": ""
        },
        {
          "DocumentQualifier": "CashierReceipt",
          "OutputContent": {
            "OutputFormat": "Text",
            "OutputText": [
              {
                "EndOfLineFlag": true,
                "Text": "          Test_STORE           "
              },
              {
                "EndOfLineFlag": true,
                "Text": "         Address Line 1          "
              },
              {
                "EndOfLineFlag": true,
                "Text": "       Address Line 2        "
              },
              {
                "EndOfLineFlag": true,
                "Text": "            Country             "
              },
              {
                "EndOfLineFlag": true,
                "Text": "--------------------------------"
              },
              {
                "EndOfLineFlag": true,
                "Text": ""
              },
              {
                "EndOfLineFlag": true,
                "Text": "11.11.20                   10:31"
              },
              {
                "EndOfLineFlag": true,
                "Text": "        MERCHANT RECEIPT        "
              },
              {
                "EndOfLineFlag": true,
                "Text": "--------------------------------"
              },
              {
                "EndOfLineFlag": true,
                "Text": "TERMINAL: 12345                 "
              },
              {
                "EndOfLineFlag": true,
                "Text": "MERCHANT: 123456                "
              },
              {
                "EndOfLineFlag": true,
                "Text": "PAN: XXXXXXXXXXXX1732           "
              },
              {
                "EndOfLineFlag": true,
                "Text": "CARD TYPE: Mastercard           "
              },
              {
                "EndOfLineFlag": true,
                "Text": "MANUAL CANCELLATION             "
              },
              {
                "EndOfLineFlag": true,
                "Text": "MANUAL ENTRY                    "
              },
              {
                "EndOfLineFlag": true,
                "Text": "AMOUNT:                10,00 EUR"
              },
              {
                "EndOfLineFlag": true,
                "Text": "REFERENCE: 84551070428          "
              },
              {
                "EndOfLineFlag": true,
                "Text": "RESERVATION ID: 770235347164    "
              },
              {
                "EndOfLineFlag": true,
                "Text": "AUTHORISATION CODE: 252503      "
              },
              {
                "EndOfLineFlag": true,
                "Text": "              (00)              "
              },
              {
                "EndOfLineFlag": true,
                "Text": "        APPROVED                "
              },
              {
                "EndOfLineFlag": true,
                "Text": "   NO CARDHOLDER VERIFICATION   "
              },
              {
                "EndOfLineFlag": true,
                "Text": " PLEASE RETAIN FOR YOUR RECORDS "
              }
            ]
          },
          "RequiredSignatureFlag": ""
        }
      ],
      "Response": {
        "Result": "Success"
      }
    }
  }
}

Did this page help you?