Pre-Authorisation Completion

🚧

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 Completion message from your ePOS system to complete a previous authorization and take the money from the customer's account. A Pre-Authorization Completion is currently supported as a card not present transaction.

The ePOS Payments API supports this functionality as follows:

  • nexo Retailer PaymentRequest message with PaymentType set as "Completion"

Sample Workflow

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

Card Not Present Pre-Authorization CompletionCard Not Present Pre-Authorization Completion

Sample Pre-Authorization Completion Request Body payload

Below is an example of a nexo Pre-Authorization Completion Request payload (body only). In this example the cashier is requesting to complete a previous authorization and take a payment of €10 from the 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 "Payment"
  • MessageType must be set as "Request"
  • POIID must be set as "CAP"
  • PaymentType must be set as "Completion"
  • SaleReferenceID must be set to the sale identifier for the whole reservation transaction, as returned in the initial pre-authorization initialization response
  • RequestedAmount must be set to sale amount
{
  "SaleToPOIRequest": {
    "MessageHeader": {
      "MessageClass": "Service",
      "MessageCategory": "Payment",
      "MessageType": "Request",
      "ServiceID": "1831207548",
      "SaleID": "Salesystem-00000001",
      "POIID": "CAP"
    },
    "PaymentRequest": {
      "SaleData": {
        "OperatorID": "Operator01",
        "SaleTransactionID": {
          "TransactionID": "002286",
          "TimeStamp": "2020-11-11T09:30:36-05:00"
        },
        "SaleReferenceID": "770235347164"
      },
      "PaymentTransaction": {
        "AmountsReq": {
          "Currency": "EUR",
          "RequestedAmount": "10"
        }
      },
      "PaymentData": {
        "PaymentType": "Completion",
        "PaymentInstrumentData": {
          "PaymentInstrumentType": "Token",
          "CardData": {
            "EntryMode": "File",
            "SensitiveCardData": {
              "PAN": "0433464960001732"
            }
          }
        }
      }
    }
  }
}

Sample Pre-Authorization Completion Response Body payload

Below is an example of a successful nexo Pre-Authorization Completion Response payload (body only). In this example there has been approval of the request for payment of €10 from 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": "Payment",
      "MessageClass": "Service",
      "MessageType": "Response",
      "POIID": "CAP",
      "SaleID": "Salesystem-00000001",
      "ServiceID": "1831207548"
    },
    "PaymentResponse": {
      "POIData": {
        "POITransactionID": {
          "TimeStamp": "2020-11-11T09:31:36",
          "TransactionID": "84551070426"
        }
      },
      "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": "BOOKING                         "
              },
              {
                "EndOfLineFlag": true,
                "Text": "MANUAL ENTRY                    "
              },
              {
                "EndOfLineFlag": true,
                "Text": "FINAL AMOUNT:          10,00 EUR"
              },
              {
                "EndOfLineFlag": true,
                "Text": "REFERENCE: 84551070426          "
              },
              {
                "EndOfLineFlag": true,
                "Text": "RESERVATION ID: 770235347164    "
              },
              {
                "EndOfLineFlag": true,
                "Text": "AUTHORISATION CODE: 832330      "
              },
              {
                "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                   09: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": "BOOKING                         "
              },
              {
                "EndOfLineFlag": true,
                "Text": "MANUAL ENTRY                    "
              },
              {
                "EndOfLineFlag": true,
                "Text": "FINAL AMOUNT:          10,00 EUR"
              },
              {
                "EndOfLineFlag": true,
                "Text": "REFERENCE: 84551070426          "
              },
              {
                "EndOfLineFlag": true,
                "Text": "RESERVATION ID: 770235347164    "
              },
              {
                "EndOfLineFlag": true,
                "Text": "AUTHORISATION CODE: 832330      "
              },
              {
                "EndOfLineFlag": true,
                "Text": "              (00)              "
              },
              {
                "EndOfLineFlag": true,
                "Text": "          APPROVED              "
              },
              {
                "EndOfLineFlag": true,
                "Text": "   NO CARDHOLDER VERIFICATION   "
              },
              {
                "EndOfLineFlag": true,
                "Text": " PLEASE RETAIN FOR YOUR RECORDS "
              }
            ]
          },
          "RequiredSignatureFlag": ""
        }
      ],
      "PaymentResult": {
        "AmountsResp": {
          "AuthorizedAmount": "10",
          "Currency": "EUR"
        },
        "PaymentAcquirerData": {
          "AcquirerPOIID": "12345",
          "ApprovalCode": "832330",
          "MerchantID": "123456"
        },
        "PaymentInstrumentData": {
          "CardData": {
            "EntryMode": "File",
            "MaskedPAN": "XXXXXXXXXXXX1732",
            "PaymentBrand": "M"
          },
          "PaymentInstrumentType": "Token"
        },
        "PaymentType": "Completion"
      },
      "Response": {
        "Result": "Success"
      },
      "SaleData": {
        "SaleReferenceID": "770235347164",
        "SaleTransactionID": {
          "TimeStamp": "2020-11-11T09:30:36-05:00",
          "TransactionID": "002286"
        }
      }
    }
  }
}

Did this page help you?