Token Verification

🚧

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 Token Verification message from your ePOS system to check a token for a card is available for charging before a customer uses it to pay. As part of the validity check we perform a zero value authorization against the token to ensure it isn't fraudulent, denylisted, expired or blocked. Essentially it checks whether the card related to the token is in good standing and available to make payment.

The ePOS Payments API supports this functionality as follows:

  • nexo Retailer PaymentRequest message with PaymentType set as "Normal", zero Payment Amount, and PaymentInstrumentType set to "Token"

Sample Workflow

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

Token VerificationToken Verification

Sample Token Verification Request Body payload

Below is an example of a nexo Token Verification Request payload (body only). In this example the cashier is carrying out a validity check on a token.

It is worth noting the following:

  • MessageCategory must be set as "Payment"
  • MessageType must be set as "Request"
  • POIID is set as "CAP" - as this is a Token Verification this indicates a card is not present at payment terminal so message is sent directly to payment gateway
  • PaymentType must be set as "Normal"
  • RequestedAmount must be set as 0 to trigger a Token Verification
  • PaymentInstrumentType must be set as "Token" - this is because the token is being sent to be verified
  • PAN must be set to token value - this is because the token is being sent to be verified
{
  "SaleToPOIRequest": {
    "MessageHeader": {
      "MessageClass": "Service",
      "MessageCategory": "Payment",
      "MessageType": "Request",
      "ServiceID": "1231207530",
      "SaleID": "Salesystem-00000001",
      "POIID": "CAP"
    },
    "PaymentRequest": {
      "SaleData": {
        "SaleTransactionID": {
          "TransactionID": "002285",
          "TimeStamp": "2020-10-19T13:17:36-05:00"
        }
      },
      "PaymentTransaction": {
        "AmountsReq": {
          "Currency": "EUR",
          "RequestedAmount": "0"
        }
      },
      "PaymentData": {
        "PaymentType": "Normal",
        "PaymentInstrumentData": {
          "PaymentInstrumentType": "Token",
          "CardData": {
            "EntryMode": "File",
            "SensitiveCardData": {
              "PAN": "0463708868771111"
            }
          }
        }
      }
    }
  }
}

Sample Token Verification Response Body payload

Below is an example of a successful nexo Token Verification Response payload (body only). In this example the token validity check has been successful with the response including the merchant and cardholder receipts.

It is worth noting the following:

  • Result is "Success"
{
  "SaleToPOIResponse": {
    "MessageHeader": {
      "MessageCategory": "Payment",
      "MessageClass": "Service",
      "MessageType": "Response",
      "POIID": "CAP",
      "SaleID": "Salesystem-00000001",
      "ServiceID": "1231207530"
    },
    "PaymentResponse": {
      "POIData": {
        "POITransactionID": {
          "TimeStamp": "2020-10-19T13:18:40.986",
          "TransactionID": "84549724960"
        }
      },
      "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": "        CUSTOMER RECEIPT        "
              },
              {
                "EndOfLineFlag": true,
                "Text": "--------------------------------"
              },
              {
                "EndOfLineFlag": true,
                "Text": "TERMINAL: 12345                 "
              },
              {
                "EndOfLineFlag": true,
                "Text": "MERCHANT: 123456                "
              },
              {
                "EndOfLineFlag": true,
                "Text": "PAN: XXXXXXXXXXXX1111           "
              },
              {
                "EndOfLineFlag": true,
                "Text": "CARD TYPE: Visa                 "
              },
              {
                "EndOfLineFlag": true,
                "Text": "RESERVATION                     "
              },
              {
                "EndOfLineFlag": true,
                "Text": "MANUAL ENTRY                    "
              },
              {
                "EndOfLineFlag": true,
                "Text": "AMOUNT:                 0,00 EUR"
              },
              {
                "EndOfLineFlag": true,
                "Text": "REFERENCE: 770234332334         "
              },
              {
                "EndOfLineFlag": true,
                "Text": "AUTHORISATION CODE: 737252      "
              },
              {
                "EndOfLineFlag": true,
                "Text": "              (00)              "
              },
              {
                "EndOfLineFlag": true,
                "Text": "           APPROVED             "
              },
              {
                "EndOfLineFlag": true,
                "Text": "         OFFLINE PIN            "
              },
              {
                "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: XXXXXXXXXXXX1111           "
              },
              {
                "EndOfLineFlag": true,
                "Text": "CARD TYPE: Visa                 "
              },
              {
                "EndOfLineFlag": true,
                "Text": "RESERVATION                     "
              },
              {
                "EndOfLineFlag": true,
                "Text": "MANUAL ENTRY                    "
              },
              {
                "EndOfLineFlag": true,
                "Text": "AMOUNT:                 0,00 EUR"
              },
              {
                "EndOfLineFlag": true,
                "Text": "REFERENCE: 770234332334         "
              },
              {
                "EndOfLineFlag": true,
                "Text": "AUTHORISATION CODE: 737252      "
              },
              {
                "EndOfLineFlag": true,
                "Text": "              (00)              "
              },
              {
                "EndOfLineFlag": true,
                "Text": "           APPROVED             "
              },
              {
                "EndOfLineFlag": true,
                "Text": "         OFFLINE PIN            "
              },
              {
                "EndOfLineFlag": true,
                "Text": " PLEASE RETAIN FOR YOUR RECORDS "
              }
            ]
          },
          "RequiredSignatureFlag": ""
        }
      ],
      "PaymentResult": {
        "AmountsResp": {
          "AuthorizedAmount": "0",
          "Currency": "EUR"
        },
        "PaymentAcquirerData": {
          "AcquirerPOIID": "12345",
          "ApprovalCode": "737252",
          "MerchantID": "123456"
        },
        "PaymentInstrumentData": {
          "CardData": {
            "EntryMode": "File",
            "MaskedPAN": "XXXXXXXXXXXX1111",
            "PaymentBrand": "V",
            "SensitiveCardData": {}
          },
          "PaymentInstrumentType": "Token"
        },
        "PaymentType": "Normal"
      },
      "Response": {
        "Result": "Success"
      },
      "SaleData": {
        "SaleTransactionID": {
          "TimeStamp": "2020-10-19T13:17:36-05:00",
          "TransactionID": "002285"
        }
      }
    }
  }
}

Did this page help you?