Card 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 Card Verification message from your ePOS system to carry out a validity check for a customer's card or account before a customer uses it to pay. As part of the validity check we perform a zero value authorization against the card to ensure it isn't fraudulent, denylisted, expired or blocked. Essentially it checks whether the card and account are in good standing and available to make payment. As part of verifying a card, 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", zero Payment Amount, and PaymentInstrumentType set to "Card" (if card on file); otherwise card details are obtained on terminal

Sample Workflow

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

Card VerificationCard Verification

Sample Card Verification Request Body payload

Below is an example of a nexo Card Verification Request payload (body only). In this example the cardholder has their card at the payment terminal and the cashier is carrying out a validity check and requesting a token for the card/PAN.

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"
  • RequestedAmount must be set as 0 to trigger a Card Verification
  • TokenRequestedType is set to "Customer" to request token generation as part of the transaction and transfer the acquirer token back to the ePOS system
{
  "SaleToPOIRequest": {
    "MessageHeader": {
      "MessageClass": "Service",
      "MessageCategory": "Payment",
      "MessageType": "Request",
      "ServiceID": "1731207545",
      "SaleID": "Salesystem-00000001",
      "POIID": "AUTO"
    },
    "PaymentRequest": {
      "SaleData": {
        "OperatorID": "Operator01",
        "SaleTransactionID": {
          "TransactionID": "002285",
          "TimeStamp": "2020-11-11T10:11:79+01:00"
        },
        "TokenRequestedType": "Customer"
      },
      "PaymentTransaction": {
        "AmountsReq": {
          "Currency": "EUR",
          "RequestedAmount": "0"
        }
      },
      "PaymentData": {
        "PaymentType": "Normal"
      }
    }
  }
}

Sample Card Verification Response Body payload

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

It is worth noting the following:

  • Result is "Success"
  • TokenValue holds the token for the card being verified
{
  "SaleToPOIResponse": {
    "MessageHeader": {
      "MessageCategory": "Payment",
      "MessageClass": "Service",
      "MessageType": "Response",
      "POIID": "54094601",
      "ProtocolVersion": "3.1",
      "SaleID": "Salesystem-00000001",
      "ServiceID": "1731207545"
    },
    "PaymentResponse": {
      "POIData": {
        "POITransactionID": {
          "TimeStamp": "2020-11-11T10:22:51.053",
          "TransactionID": "770235346626"
        }
      },
      "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": "11.11.2020            10:22:40"
              },
              {
                "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: MasterCard"
              },
              {
                "EndOfLineFlag": true,
                "Text": "      CARD VALIDITY CHECK"
              },
              {
                "EndOfLineFlag": true,
                "Text": "EMV CHIP"
              },
              {
                "EndOfLineFlag": true,
                "Text": "REFERENCE: 7704"
              },
              {
                "EndOfLineFlag": true,
                "Text": "AMOUNT: EUR 0,00"
              },
              {
                "EndOfLineFlag": true,
                "Text": "AUTHORISATION CODE: 016441"
              },
              {
                "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": "11.11.2020            10:22:40"
              },
              {
                "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: MasterCard"
              },
              {
                "EndOfLineFlag": true,
                "Text": "      CARD VALIDITY CHECK"
              },
              {
                "EndOfLineFlag": true,
                "Text": "EMV CHIP"
              },
              {
                "EndOfLineFlag": true,
                "Text": "REFERENCE: 7704"
              },
              {
                "EndOfLineFlag": true,
                "Text": "AMOUNT: EUR 0,00"
              },
              {
                "EndOfLineFlag": true,
                "Text": "AUTHORISATION CODE: 016441"
              },
              {
                "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": "0",
          "Currency": "EUR"
        },
        "PaymentAcquirerData": {
          "AcquirerID": "1",
          "AcquirerPOIID": "54094601",
          "ApprovalCode": "016441",
          "MerchantID": "123456"
        },
        "PaymentInstrumentData": {
          "CardData": {
            "EntryMode": "ICC",
            "MaskedPAN": "XXXXXXXXXXXX0582",
            "PaymentBrand": "Mastercard",
            "PaymentToken": {
              "TokenRequestedType": "Customer",
              "TokenValue": "0946536169790582"
            },
            "SensitiveCardData": {
              "ExpiryDate": "1225"
            }
          },
          "PaymentInstrumentType": "Card"
        },
        "PaymentType": "Normal"
      },
      "Response": {
        "Result": "Success"
      },
      "SaleData": {
        "SaleTransactionID": {
          "TimeStamp": "2020-11-11T10:11:79+01:00",
          "TransactionID": "002285"
        }
      }
    }
  }
}

Did this page help you?