🚧

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 Payment message from your ePOS system to accept a payment from a customer. A Payment message can be sent when a card is present at the payment terminal or when a card is not present (card/token on file). When a card is present at the payment terminal, a customer has the option to pay in their local currency - Dynamic Currency Conversion (DCC). As part of accepting a card payment, 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 "Normal"

Sample Workflow

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

Card Present PaymentCard Present Payment

Sample Payment Request Body payload

Below is an example of a nexo Retailer Payment Request payload (body only). In this example the cardholder has their card at the payment terminal and the cashier is taking a payment of €40 from them.

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 "Normal" for a payment
  • 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 sale amount
{
  "SaleToPOIRequest": {
    "MessageHeader": {
      "MessageClass": "Service",
      "MessageCategory": "Payment",
      "MessageType": "Request",
      "ServiceID": "1731207545",
      "SaleID": "Salesystem-00000001",
      "POIID": "AUTO"
    },
    "PaymentRequest": {
      "SaleData": {
        "SaleTransactionID": {
          "TransactionID": "002285",
          "TimeStamp": "2020-10-14T13:10:43+02:00"
        },
        "TokenRequestedType": "Customer"
      },
      "PaymentTransaction": {
        "AmountsReq": {
          "Currency": "EUR",
          "RequestedAmount": "40"
        }
      },
      "PaymentData": {
        "PaymentType": "Normal"
      }
    }
  }
}

Sample Payment Response Body payload

Below is an example of a successful nexo Payment Response payload (body only). In this example the cardholder has paid €40 using their card at the payment terminal, and the payment approval response has been returned with the authorisation code and the merchant and cardholder receipts.

It is worth noting the following:

  • Result is "Success"
  • POITransactionID TransactionID is the unique identification of the transaction on payment gateway and can be used to void or refund this payment if required
  • PaymentReceipt holds the Customer and/or Merchant payment receipts
  • TokenValue holds the token generated from the PAN
{
  "SaleToPOIResponse": {
    "MessageHeader": {
      "MessageCategory": "Payment",
      "MessageClass": "Service",
      "MessageType": "Response",
      "POIID": "54094601",
      "ProtocolVersion": "3.1",
      "SaleID": "Salesystem-00000001",
      "ServiceID": "1731207545"
    },
    "PaymentResponse": {
      "POIData": {
        "POITransactionID": {
          "TimeStamp": "2020-10-14T13:14:01.789",
          "TransactionID": "770223496031"
        }
      },
      "PaymentReceipt": [
        {
          "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": "14.10.2020            13:13:50"
              },
              {
                "EndOfLineFlag": true,
                "Text": "        MERCHANT RECEIPT"
              },
              {
                "EndOfLineFlag": true,
                "Text": "--------------------------------"
              },
              {
                "EndOfLineFlag": true,
                "Text": "TERMINAL: 54094601"
              },
              {
                "EndOfLineFlag": true,
                "Text": "DEVICE NAME: 54094601"
              },
              {
                "EndOfLineFlag": true,
                "Text": "MERCHANT: 123456"
              },
              {
                "EndOfLineFlag": true,
                "Text": "PAN: XXXXXXXXXXXX0582"
              },
              {
                "EndOfLineFlag": true,
                "Text": "AID: A0000000041010"
              },
              {
                "EndOfLineFlag": true,
                "Text": "CARD TYPE: M"
              },
              {
                "EndOfLineFlag": true,
                "Text": "EMV CHIP"
              },
              {
                "EndOfLineFlag": true,
                "Text": "            PAYMENT"
              },
              {
                "EndOfLineFlag": true,
                "Text": "REFERENCE: 7368"
              },
              {
                "EndOfLineFlag": true,
                "Text": "AMOUNT: EUR 40,00"
              },
              {
                "EndOfLineFlag": true,
                "Text": "AUTHORISATION CODE: 006448"
              },
              {
                "EndOfLineFlag": true,
                "Text": "              (00)"
              },
              {
                "EndOfLineFlag": true,
                "Text": "            APPROVED"
              },
              {
                "EndOfLineFlag": true,
                "Text": "          OFFLINE PIN"
              },
              {
                "EndOfLineFlag": true,
                "Text": " PLEASE RETAIN FOR YOUR RECORDS"
              }
            ]
          },
          "RequiredSignatureFlag": false
        },
        {
          "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": "14.10.2020            13:13:50"
              },
              {
                "EndOfLineFlag": true,
                "Text": "       CARDHOLDER RECEIPT"
              },
              {
                "EndOfLineFlag": true,
                "Text": "--------------------------------"
              },
              {
                "EndOfLineFlag": true,
                "Text": "TERMINAL: 54094601"
              },
              {
                "EndOfLineFlag": true,
                "Text": "DEVICE NAME: 54094601"
              },
              {
                "EndOfLineFlag": true,
                "Text": "MERCHANT: 123456"
              },
              {
                "EndOfLineFlag": true,
                "Text": "PAN: XXXXXXXXXXXX0582"
              },
              {
                "EndOfLineFlag": true,
                "Text": "AID: A0000000041010"
              },
              {
                "EndOfLineFlag": true,
                "Text": "CARD TYPE: M"
              },
              {
                "EndOfLineFlag": true,
                "Text": "EMV CHIP"
              },
              {
                "EndOfLineFlag": true,
                "Text": "            PAYMENT"
              },
              {
                "EndOfLineFlag": true,
                "Text": "REFERENCE: 7368"
              },
              {
                "EndOfLineFlag": true,
                "Text": "AMOUNT: EUR 40,00"
              },
              {
                "EndOfLineFlag": true,
                "Text": "AUTHORISATION CODE: 006448"
              },
              {
                "EndOfLineFlag": true,
                "Text": "              (00)"
              },
              {
                "EndOfLineFlag": true,
                "Text": "            APPROVED"
              },
              {
                "EndOfLineFlag": true,
                "Text": "          OFFLINE PIN"
              },
              {
                "EndOfLineFlag": true,
                "Text": " PLEASE RETAIN FOR YOUR RECORDS"
              }
            ]
          },
          "RequiredSignatureFlag": false
        }
      ],
      "PaymentResult": {
        "AmountsResp": {
          "AuthorizedAmount": 40,
          "Currency": "EUR"
        },
        "PaymentAcquirerData": {
          "AcquirerID": "1",
          "AcquirerPOIID": "54094601",
          "ApprovalCode": "006448",
          "MerchantID": "123456"
        },
        "PaymentInstrumentData": {
          "CardData": {
            "EntryMode": "ICC",
            "MaskedPAN": "XXXXXXXXXXXX0582",
            "PaymentBrand": "M",
            "PaymentToken": {
              "TokenRequestedType": "Customer",
              "TokenValue": "0946536169790582"
            },
            "SensitiveCardData": {
              "ExpiryDate": "1225"
            }
          },
          "PaymentInstrumentType": "Card"
        },
        "PaymentType": "Normal"
      },
      "Response": {
        "Result": "Success"
      },
      "SaleData": {
        "SaleTransactionID": {
          "TimeStamp": "2020-10-14T13:10:43+02:00",
          "TransactionID": "002285"
        }
      }
    }
  }
}

Did this page help you?