Pre-Authorisation Increment

🚧

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 Increment from your ePOS system to top-up the amount of an existing reservation by increasing the money being held for payment on the cardholder’s account. This reduces their spending limit until the sale is completed or the authorization is released. Pre-Authorization Increment 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 "UpdateReservation"

Sample Workflow

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

Card Not Present Pre-Authorization IncrementCard Not Present Pre-Authorization Increment

Sample Pre-Authorization Increment Request Body payload

Below is an example of a nexo Pre-Authorization Increment Request payload (body only). In this example the cashier is requesting to increase the amount being held on a cardholder’s account by €12, using a payment token, and 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 "UpdateReservation"
  • SaleReferenceID must be set to the identifier for the whole reservation transaction, as returned in the initial pre-authorization initialization response
  • RequestedAmount must be set to top-up amount
{
  "SaleToPOIRequest": {
    "MessageHeader": {
      "MessageClass": "Service",
      "MessageCategory": "Payment",
      "MessageType": "Request",
      "ServiceID": "1731207545",
      "SaleID": "Salesystem-00000001",
      "POIID": "CAP"
    },
    "PaymentRequest": {
      "SaleData": {
        "SaleTransactionID": {
          "TransactionID": "002281",
          "TimeStamp": "2020-10-07T15:49:36-05:00"
        },
        "SaleReferenceID": "770235347164"
      },
      "PaymentTransaction": {
        "AmountsReq": {
          "Currency": "EUR",
          "RequestedAmount": "12"
        }
      },
      "PaymentData": {
        "PaymentType": "UpdateReservation",
        "PaymentInstrumentData": {
          "PaymentInstrumentType": "Token",
          "CardData": {
            "EntryMode": "File",
            "SensitiveCardData": {
              "PAN": "0433464960001732"
            }
          }
        }
      }
    }
  }
}

Sample Pre-Authorization Increment Response Body payload

Below is an example of a successful nexo Pre-Authorization Increment Response payload (body only). In this example there has been approval of the request for an additional €12 to be 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": {
      "MessageClass": "Service",
      "MessageCategory": "Payment",
      "MessageType": "Response",
      "ServiceID": "1731207545",
      "SaleID": "Salesystem-00000001",
      "POIID": "CAP"
    },
    "PaymentResponse": {
       "POIData": {
        "POITransactionID": {
          "TransactionID": "97094594",
          "TimeStamp": "2020-10-07T09:31:36"
        }
      },
      "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": "07.10.20                   15:50"
              },
              {
                "EndOfLineFlag": true,
                "Text": "     CARDHOLDER RECEIPT         "
              },
              {
                "EndOfLineFlag": true,
                "Text": "--------------------------------"
              },
              {
                "EndOfLineFlag": true,
                "Text": "TERMINAL: 1234567               "
              },
              {
                "EndOfLineFlag": true,
                "Text": "MERCHANT: 123456                "
              },
              {
                "EndOfLineFlag": true,
                "Text": "PAN: XXXXXXXXXXXX1732           "
              },
              {
                "EndOfLineFlag": true,
                "Text": "CARD TYPE: Mastercard           "
              },
              {
                "EndOfLineFlag": true,
                "Text": "UPDATE RESERVATION              "
              },
              {
                "EndOfLineFlag": true,
                "Text": "MANUAL ENTRY                    "
              },
              {
                "EndOfLineFlag": true,
                "Text": "AMOUNT:                12,00 EUR"
              },
              {
                "EndOfLineFlag": true,
                "Text": "REFERENCE: 84551070426          "
              },
              {
                "EndOfLineFlag": true,
                "Text": "RESERVATION ID: 770235347164    "
              },
              {
                "EndOfLineFlag": true,
                "Text": "AUTHORISATION CODE: OK7118      "
              },
              {
                "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": "07.11.20                   15:50"
              },
              {
                "EndOfLineFlag": true,
                "Text": "       MERCHANT RECEIPT        "
              },
              {
                "EndOfLineFlag": true,
                "Text": "--------------------------------"
              },
              {
                "EndOfLineFlag": true,
                "Text": "TERMINAL: 1234567               "
              },
              {
                "EndOfLineFlag": true,
                "Text": "MERCHANT: 123456                "
              },
              {
                "EndOfLineFlag": true,
                "Text": "PAN: XXXXXXXXXXXX1732           "
              },
              {
                "EndOfLineFlag": true,
                "Text": "CARD TYPE: Mastercard           "
              },
              {
                "EndOfLineFlag": true,
                "Text": "UPDATE RESERVATION              "
              },
              {
                "EndOfLineFlag": true,
                "Text": "MANUAL ENTRY                    "
              },
              {
                "EndOfLineFlag": true,
                "Text": "AMOUNT:                12,00 EUR"
              },
              {
                "EndOfLineFlag": true,
                "Text": "REFERENCE: 84551070426          "
              },
              {
                "EndOfLineFlag": true,
                "Text": "RESERVATION ID: 770235347164    "
              },
              {
                "EndOfLineFlag": true,
                "Text": "AUTHORISATION CODE: OK7118      "
              },
              {
                "EndOfLineFlag": true,
                "Text": "              (00)              "
              },
              {
                "EndOfLineFlag": true,
                "Text": "          APPROVED              "
              },
              {
                "EndOfLineFlag": true,
                "Text": "   NO CARDHOLDER VERIFICATION   "
              },
              {
                "EndOfLineFlag": true,
                "Text": " PLEASE RETAIN FOR YOUR RECORDS "
              }
            ]
          },
          "RequiredSignatureFlag": ""
        }
      ],      
      "PaymentResult": {
        "PaymentType": "UpdateReservation",
        "PaymentInstrumentData": {
          "PaymentInstrumentType": "Token",
          "CardData": {
            "PaymentBrand": "",
            "MaskedPAN": "",
            "EntryMode": "File",
            "SensitiveCardData": {
              "ExpiryDate": "1218"
            }
          }
        },
        "AmountsResp": {
          "Currency": "EUR",
          "AuthorizedAmount": "12"
        },
        "OnlineFlag": "True",
        "PaymentAcquirerData": {
          "MerchantID": "123456",
          "AcquirerPOIID": "1234567",
          "ApprovalCode": "OK7118"
        }
      },
     "Response": {
        "Result": "Success"
      },
      "SaleData": {
        "SaleTransactionID": {
          "TransactionID": "002281",
          "TimeStamp": "2020-10-07T15:49:36-05:00"
        },
        "SaleReferenceID": "770235347164"
      },      
    }
  }
}


Did this page help you?