Pre-Authorisation Cancellation

🚧

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 Pre-Authorization Cancellation message from your ePOS system to release or cancel the amount being held on a customer's account as part of an existing authorization. A Pre-Authorization Cancellation is currently supported as a card not present transaction.

The ePOS Payments API supports this functionality as follows:

  • nexo Retailer Reversal message with SaleReferenceID supplied

Sample Workflow

This sequence diagram maps to the steps in the Pre-Authorization Cancellation sample request and response payloads that follow.

Card Not Present Pre-Authorization CancellationCard Not Present Pre-Authorization Cancellation

Sample Pre-Authorization Cancellation Request Body payload

Below is an example of a nexo Pre-Authorization Cancellation Request payload (body only). In this example the cashier is requesting to release €10.24 being held on a cardholder’s account based on the sale reference identifier for the whole reservation/authorization.

It is worth noting the following:

  • MessageCategory must be set as "Reversal"
  • MessageType must be set as "Request"
  • POIID must be set as "CAP"
  • SaleReferenceID must be set to the identifier for the whole reservation transaction, as returned in the initial pre-authorization initialization response
  • ReversalReason is set to reversal cause
{
  "SaleToPOIRequest": {
    "MessageHeader": {
      "MessageClass": "Service",
      "MessageCategory": "Reversal",
      "MessageType": "Request",
      "ServiceID": "2531207673",
      "SaleID": "Salesystem-00000001",
      "POIID": "CAP"
    },
    "ReversalRequest": {
      "SaleData": {
        "OperatorID": "Operator01",
        "SaleReferenceID": "770234332196"
      },
      "ReversalReason": "CustCancel"
    }
  }
}

Sample Pre-Authorization Cancellation Response Body payload

Below is an example of a successful nexo Pre-Authorization Cancellation Response payload (body only). In this example there has been approval of the request for releasing/cancelling €10.24 being held on a cardholder’s account, 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": "2531207673"
    },
    "ReversalResponse": {
      "CustomerOrder": {
        "SaleReferenceID": "770234332196"
      },
      "POIData": {
        "POITransactionID": {
          "TimeStamp": "2020-10-19T15:23:10",
          "TransactionID": "84549724968"
        }
      },
      "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": "19.10.20                   17:23"
              },
              {
                "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,24 EUR"
              },
              {
                "EndOfLineFlag": true,
                "Text": "REFERENCE: 770234332354         "
              },
              {
                "EndOfLineFlag": true,
                "Text": "AUTHORISATION CODE: 121598      "
              },
              {
                "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": "19.10.20                   17:23"
              },
              {
                "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,24 EUR"
              },
              {
                "EndOfLineFlag": true,
                "Text": "REFERENCE: 770234332354         "
              },
              {
                "EndOfLineFlag": true,
                "Text": "AUTHORISATION CODE: 121598      "
              },
              {
                "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?