Pre-Authorisation Initialisation

🚧

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 Initialization message from your ePOS system to hold money for payment on a cardholder’s account. This reduces the cardholder's spending limit until the sale is completed or the authorization is released. Pre-Authorization Initialization can occur when a card is present at the terminal or when a card is not present (card/token on file). As part of Pre-Authorization Initialization a request for a token value for the card can occur at the same time.

The ePOS Payments API supports this functionality as follows:

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

Sample Workflow

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

Card Not Present Pre-Authorization InitializationCard Not Present Pre-Authorization Initialization

Sample Pre-Authorization Initialization Request Body payload

Below is an example of a nexo Pre-Authorization Initialization Request payload (body only). In this example the cashier is requesting €10 to be held on a cardholder’s account using a payment token.

It is worth noting the following:

  • MessageCategory must be set as "Payment"
  • MessageType must be set as "Request"
  • POIID is set as "AUTO", or could be actual POI ID, if card is present at the payment terminal. Otherwise if card is not present then is set to "CAP"
  • PaymentType must be set as "FirstReservation" to place a hold on a card
  • TokenRequestedType is set to "Customer" to request token generation as part of the transaction and transfer the acquirer token back to the ePOS system
  • RequestedAmount must be set to the authorization amount
{
  "SaleToPOIRequest": {
    "MessageHeader": {
      "MessageClass": "Service",
      "MessageCategory": "Payment",
      "MessageType": "Request",
      "ServiceID": "1731207545",
      "SaleID": "Salesystem-00000001",
      "POIID": "CAP"
    },
    "PaymentRequest": {
      "SaleData": {
        "OperatorID": "Operator01",
        "SaleTransactionID": {
          "TransactionID": "002285",
          "TimeStamp": "2020-11-11T09:30:36-05:00"
        }
      },
      "PaymentTransaction": {
        "AmountsReq": {
          "Currency": "EUR",
          "RequestedAmount": "10"
        }
      },
      "PaymentData": {
        "PaymentType": "FirstReservation",
        "PaymentInstrumentData": {
          "PaymentInstrumentType": "Token",
          "CardData": {
            "EntryMode": "File",
            "SensitiveCardData": {
              "PAN": "0433464960001732"
            }
          }
        }
      }
    }
  }
}

Sample Pre-Authorization Initialization Response Body payload

Below is an example of a successful nexo Pre-Authorization Initialization Response payload (body only). In this example there has been approval of the request for €10 to be held on a cardholder’s account, with the response including the authorization code, the sale reference identifier for the whole reservation/authorization, and the merchant and cardholder receipts.

It is worth noting the following:

  • Result is "Success"
  • SaleReferenceID holds the identifier for the whole reservation/authorization. Used in any subsequent requests related to post auths, such as, pre-authorization increment/top-up, pre-authorization cancellation, pre-authorization completion
  • PaymentReceipt holds the Customer and/or Merchant payment receipts
{
  "SaleToPOIResponse": {
    "MessageHeader": {
      "MessageCategory": "Payment",
      "MessageClass": "Service",
      "MessageType": "Response",
      "POIID": "CAP",
      "SaleID": "Salesystem-00000001",
      "ServiceID": "1731207545"
    },
    "PaymentResponse": {
      "POIData": {
        "POITransactionID": {
          "TimeStamp": "2020-11-11T09:31:35",
          "TransactionID": "84551070425"
        }
      },
      "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": "RESERVATION                     "
              },
              {
                "EndOfLineFlag": true,
                "Text": "MANUAL ENTRY                    "
              },
              {
                "EndOfLineFlag": true,
                "Text": "PLANNED AMOUNT:        10,00 EUR"
              },
              {
                "EndOfLineFlag": true,
                "Text": "REFERENCE: 84551070425          "
              },
              {
                "EndOfLineFlag": true,
                "Text": "RESERVATION ID: 770235347164    "
              },
              {
                "EndOfLineFlag": true,
                "Text": "RESERV. EXPIRY DATE: 11.12.20   "
              },
              {
                "EndOfLineFlag": true,
                "Text": "AUTHORISATION CODE: 228933      "
              },
              {
                "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": "RESERVATION                     "
              },
              {
                "EndOfLineFlag": true,
                "Text": "MANUAL ENTRY                    "
              },
              {
                "EndOfLineFlag": true,
                "Text": "PLANNED AMOUNT:        10,00 EUR"
              },
              {
                "EndOfLineFlag": true,
                "Text": "REFERENCE: 84551070425          "
              },
              {
                "EndOfLineFlag": true,
                "Text": "RESERVATION ID: 770235347164    "
              },
              {
                "EndOfLineFlag": true,
                "Text": "RESERV. EXPIRY DATE: 11.12.20   "
              },
              {
                "EndOfLineFlag": true,
                "Text": "AUTHORISATION CODE: 228933      "
              },
              {
                "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"
        },
        "OnlineFlag": "True",
        "PaymentAcquirerData": {
          "AcquirerPOIID": "12345",
          "ApprovalCode": "228933",
          "MerchantID": "123456"
        },
        "PaymentInstrumentData": {
          "CardData": {
            "EntryMode": "File",
            "MaskedPAN": "XXXXXXXXXXXX1732",
            "PaymentBrand": "M",
            "SensitiveCardData": {
              "ExpiryDate": "1225"
            }
          },
          "PaymentInstrumentType": "Token"
        },
        "PaymentType": "FirstReservation",
        "ValidityDate": ""
      },
      "Response": {
        "Result": "Success"
      },
      "SaleData": {
        "SaleReferenceID": "770235347164",
        "SaleTransactionID": {
          "TimeStamp": "2020-11-11T09:30:36-05:00",
          "TransactionID": "002285"
        }
      }
    }
  }
}

Did this page help you?