Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Card-based identification

Identify a card at start and finish to calculate the amount due.

When you make card acquisition requests, you get data to identify the customer.

For example, in a parking garage you can use the card acquisition data instead of issuing a parking pass:

  1. Upon arrival, you identify the driver and record their time of arrival based on a card acquisition. Then you cancel the card acquisition.
  2. When the driver leaves, you do another card acquisition to recognize the driver.
  3. Then you calculate the amount due based on the arrival and departure times, and make a payment.

A similar scenario could apply to toll booths, using the location of the terminals used in the card acquisition requests to calculate the amount due.

Card identifiers

To be able to identify customers and recognize them later, save the following identifiers:

  • Card alias (alias): A value that uniquely represents the shopper's card number (PAN), for example A37317672402294. With this, you can recognize the card that a shopper is using. You can't use the card alias for making payments. You receive the card alias in the AdditionalResponse.

Depending on your use case, could also save:

  • Other transaction details. For example, transaction date and time.

Identify the customer

When the customer arrives:

  1. Make a card acquisition request without an amount.

    First card acquisition
    {
        "SaleToPOIRequest":{
            "MessageHeader":{
                "ProtocolVersion":"3.0",
                "MessageClass":"Service",
                "MessageCategory":"CardAcquisition",
                "MessageType":"Request",
                "ServiceID":"282",
                "SaleID":"POSSystemID12345",
                "POIID":"P400Plus-347069832"
            },
            "CardAcquisitionRequest":{
                "SaleData":{
                    "SaleTransactionID":{
                        "TransactionID":"375",
                        "TimeStamp":"2021-03-26T15:58:45.000Z"
                    },
                    "{hint:Optional, returns the card alias in TokenValue}TokenRequestedType":"Customer{/hint}"
                },
                "CardAcquisitionTransaction":{
                }
            }
        }
    }
  2. When you receive the response, save the following details:

    From the AdditionalResponse (you'll receive either a string of form-encoded key-value pairs or a Base64 string that you need to decode to get a JSON object):

    • alias: The card alias, to identify the customer based on their card.

    Also save other details that you need for your use case. For example:

    • SaleData.SaleTransactionID.TimeStamp: Date and time when the customer presented their card.
    • MessageHeader.POIID: The payment terminal that processed the request. Useful if you need to know where the customer presented their card.
    Response for the first card acquisition
    {
        "SaleToPOIResponse": {
            "CardAcquisitionResponse": {
                "POIData": {
                    "POIReconciliationID": "1000",
                    "POITransactionID": {
                        "TimeStamp": "2021-03-26T15:58:45.000Z",
                        "TransactionID": "BV0q001616774325000"
                    }
                },
                "PaymentInstrumentData": {
                    "CardData": {
                        "CardCountryCode": "528",
                        "MaskedPan": "541333 **** 9999",
                        "PaymentBrand": "mc",
                        "PaymentToken": {
                            "TokenRequestedType": "Customer",
                            "TokenValue": "{hint:This is the alias. Store it in your back-end system}M469509594859802{/hint}"
                        },
                        "SensitiveCardData": {
                            "ExpiryDate": "0228"
                        }
                    },
                    "PaymentInstrumentType": "Card"
                },
                "Response": {
                    "AdditionalResponse": "tid=47069832&transactionType=GOODS_SERVICES&backendGiftcardIndicator=false&expiryYear=2028&alias=M469509594859802&posAmountGratuityValue=0&giftcardIndicator=false&paymentMethodVariant=mc&txtime=16%3a58%3a45&iso8601TxDate=2021-03-26T15%3a58%3a45.0000000%2b0000&cardType=mc&posOriginalAmountValue=0&aliasType=Default&txdate=26-03-2021&paymentMethod=mc&merchantReference=68&expiryMonth=02&cardSummary=9999&posadditionalamounts.originalAmountCurrency=EUR&posAuthAmountCurrency=EUR&message=CARD_ACQ_COMPLETED&cardIssuerCountryId=528&posAmountCashbackValue=0&posEntryMode=CLESS_CHIP&fundingSource=CREDIT&issuerCountry=NL&cardScheme=mc&cardBin=541333&posAuthAmountValue=0",
                    "Result": "Success"
                },
                "SaleData": {
                    "SaleTransactionID": {
                        "TimeStamp": "2021-03-26T15:58:44.591Z",
                        "TransactionID": "382"
                    }
                }
            },
            "MessageHeader": {
                "MessageCategory": "CardAcquisition",
                "MessageClass": "Service",
                "MessageType": "Response",
                "POIID": "P400Plus-347069832",
                "ProtocolVersion": "3.0",
                "SaleID": "POSSystemID12345",
                "ServiceID": "282"
            }
        }
    }

    Note that if you specified a TokenRequestedType of Customer in the request, the card alias is also provided in PaymentInstrumentData.CardData.PaymentToken.TokenValue.

  3. Create a record in your back-end system to store the data obtained from the card acquisition.

  4. Cancel the card acquisition flow by making an EnableServiceRequest to the same terminal that you sent the card acquisition request to.

    The following example will show Welcome!, an animated green check mark -white_check_mark-, and We logged your arrival time.

    Cancellation using a custom message
    {
       "SaleToPOIRequest":{
          "MessageHeader":{
             "ProtocolVersion":"3.0",
             "MessageClass":"Service",
             "MessageCategory":"EnableService",
             "MessageType":"Request",
             "ServiceID":"3020711110",
             "SaleID":"POSSystemID12345",
             "POIID":"P400Plus-347069832"
          },
          "EnableServiceRequest":{
             "TransactionAction":"AbortTransaction",
             "DisplayOutput":{
                "Device":"CustomerDisplay",
                "InfoQualify":"Display",
                "OutputContent":{
                   "PredefinedContent":{
                      "ReferenceID":"AcceptedAnimated"
                   },
                   "OutputFormat":"Text",
                   "OutputText":[
                      {
                         "Text":"Welcome!"
                      },
                      {
                         "Text":"We logged your arrival time"
                      }
                   ]
                }
             }
          }
       }
    }

    In the example above, we include a DisplayOutput object to show a message to the customer that their arrival time is logged. Otherwise, if you omit the DisplayOutput, the terminal will show Canceled, a red cross , and Transaction canceled. That can be confusing for the customer.

Recognize the customer

When the customer leaves:

  1. Make a card acquisition request without an amount.

    Second card acquisition
    {
        "SaleToPOIRequest":{
            "MessageHeader":{
                "ProtocolVersion":"3.0",
                "MessageClass":"Service",
                "MessageCategory":"CardAcquisition",
                "MessageType":"Request",
                "ServiceID":"112",
                "SaleID":"POSSystemID12345",
                "POIID":"P400Plus-248069832"
            },
            "CardAcquisitionRequest":{
                "SaleData":{
                    "SaleTransactionID":{
                        "TransactionID":"630",
                        "TimeStamp":"2021-03-26T16:49:42.000Z"
                    },
                    "{hint:Optional, returns the card alias in TokenValue}TokenRequestedType":"Customer{/hint}"
                },
                "CardAcquisitionTransaction":{
                }
            }
        }
    }
  2. When you receive the response, save the following details.

    • POIData.POITransactionID.TimeStamp and POIData.POITransactionID.TransactionID: You need these details later in your payment request.

    From the AdditionalResponse (you'll receive either a string of form-encoded key-value pairs or a Base64 string that you need to decode to get a JSON object):

    • alias: The card alias, to recognize the customer based on their card.

    Also save other details that you need for your use case. For example:

    • SaleData.SaleTransactionID.TimeStamp: Date and time when the customer presented their card.
    • MessageHeader.POIID: The payment terminal that processed the request. Useful if you need to know where the customer presented their card.
    Response for the second card acquisition
    {
        "SaleToPOIResponse": {
            "CardAcquisitionResponse": {
                "POIData": {
                    "POIReconciliationID": "1000",
                    "POITransactionID": {
                        "{hint:For use in the CardAcquisitionReference of the payment request}TimeStamp": "2021-03-26T16:49:42.000Z{/hint}",
                        "{hint:For use in the CardAcquisitionReference of the payment request}TransactionID": "BV0q001616777383001{/hint}"
                    }
                },
                "PaymentInstrumentData": {
                    "CardData": {
                        "CardCountryCode": "528",
                        "MaskedPan": "541333 **** 9999",
                        "PaymentBrand": "mc",
                        "PaymentToken": {
                            "TokenRequestedType": "Customer",
                            "TokenValue": "M469509594859802"
                        },
                        "SensitiveCardData": {
                            "ExpiryDate": "0228"
                        }
                    },
                    "PaymentInstrumentType": "Card"
                },
                "Response": {
                    "AdditionalResponse": "tid=47069832&transactionType=GOODS_SERVICES&backendGiftcardIndicator=false&expiryYear=2028&alias=M469509594859802&posAmountGratuityValue=0&giftcardIndicator=false&paymentMethodVariant=mc&txtime=17%3a49%3a42&iso8601TxDate=2021-03-26T16%3a49%3a42.0000000%2b0000&cardType=mc&posOriginalAmountValue=0&aliasType=Default&txdate=26-03-2021&paymentMethod=mc&merchantReference=104&expiryMonth=02&cardSummary=9999&posadditionalamounts.originalAmountCurrency=EUR&posAuthAmountCurrency=EUR&message=CARD_ACQ_COMPLETED&cardIssuerCountryId=528&posAmountCashbackValue=0&posEntryMode=CLESS_CHIP&fundingSource=CREDIT&issuerCountry=NL&cardScheme=mc&cardBin=541333&posAuthAmountValue=0",
                    "Result": "Success"
                },
                "SaleData": {
                    "SaleTransactionID": {
                        "TimeStamp": "2021-03-26T16:49:42.913Z",
                        "TransactionID": "104"
                    }
                }
            },
            "MessageHeader": {
                ...
            }
        }
    }
  3. In your back-end system, use the card alias (or Payment Account Reference) from this second card acquisition to find the record you created when you identified the customer through the first card acquisition.
  4. Add the details obtained with this second card acquisition.

Make a payment

When you have recognized the shopper:

  1. Calculate the amount due based on the details you saved after the first card acquisition (when the customer arrived) and the second card acquisition (when the customer is ready to leave).

  2. Continue with a payment to complete the card acquisition flow, specifying:

    Parameter Required Description
    PaymentTransaction.AmountsReq -white_check_mark- An object with:
    • Currency: The transaction currency.
    • RequestedAmount: The transaction amount you calculated.
    PaymentData.CardAcquisitionReference -white_check_mark- An object referring to the card acquisition:
    • TimeStamp: The timestamp returned in the POIData.POITransactionID of the second card acquisition response.
    • TransactionID: The transaction ID returned in the POIData.POITransactionID of the second card acquisition response.
    Payment after second card acquisition
    {
       "SaleToPOIRequest":{
          "MessageHeader":{
             "ProtocolVersion":"3.0",
             "MessageClass":"Service",
             "MessageCategory":"Payment",
             "MessageType":"Request",
             "SaleID":"POSSystemID12345",
             "ServiceID":"712",
             "POIID":"P400Plus-248069832"
          },
          "PaymentRequest":{
             "SaleData":{
                "SaleTransactionID":{
                   "TransactionID":"899",
                   "TimeStamp":"2021-03-26T16:49:45.810Z"
                }
             },
             "PaymentTransaction":{
                "AmountsReq":{
                   "Currency":"EUR",
                   "RequestedAmount":9.50
                }
             },
             "PaymentData":{
                "CardAcquisitionReference":{
                   "{hint:POITransactionID.TimeStamp from the second card acquisition}TimeStamp{/hint}":"2021-03-26T16:49:42.000Z",
                   "{hint:POITransactionID.TransactionID from the second card acquisition}TransactionID{/hint}":"BV0q001616777383001"
                }
             }
          }
       }
    }

See also