Search

Are you looking for test card numbers?

Would you like to contact support?

Default icon

Customer surveys

Measure customer satisfaction using your Adyen terminal.

Only using Point of sale?

If you only have a POS integration, you can still collect customer surveys using your Adyen terminal.

When your customer is ready to pay, you may want to check whether your service met their expectations. In this tutorial, we'll show you how you can use Adyen terminals to present a survey on the built-in display, and collect a response from the customer. You can use these surveys to assess customer satisfaction, or another metric that you want to measure.

By combining this functionality with customer recognition, you can connect a survey response to a specific customer, store this under their customer record, and follow up with them if needed. Alternatively, you can collect these responses anonymously.

Before you begin

To collect customer surveys, make sure that:

  1. You can create customer profiles and recognize returning customers across your sales channels.
  2. You can store survey responses in your database.

(Optional) Step 1: Recognize customer

Skip to step 2 if you'd prefer to collect survey responses anonymously.

When your customer makes a purchase, attempt to recognize them. This gives you a chance to identify a new customer, and to create a profile for them. If they are a returning customer, you can choose to store their response under their customer profile.

  1. Make a card acquisition request to recognize the customer.

    The example below shows how you would attempt to recognize a customer who is making a 10.99 EUR purchase.

    Card acquisition request
    {
    "SaleToPOIRequest": {
        "MessageHeader":{
            "ProtocolVersion":"3.0",
            "MessageClass":"Service",
            "MessageCategory":"Payment",
            "MessageType":"Request",
            "SaleID":"POSSystemID12345",
            "ServiceID":"0207111104",
            "POIID":"V400m-324688179"
        },
        "CardAcquisitionRequest": {
            "SaleData": {
                "SaleTransactionID": {
                    "TransactionID": "15890",
                    "TimeStamp": "2019-12-04T12:02:49.000Z"
                },
                "TokenRequestedType": "Customer"
            },
            "CardAcquisitionTransaction": {
                "TotalAmount": 10.99
            }
        }
    }
    }

    You receive a response that includes an AdditionalResponse object, with a base64-encoded string that you need to decode to get a JSON object, or a string of form-encoded key-value pairs. In our examples, we use form-encoded key-value pairs.

    The example response below includes an AdditionalResponse object.

    Card acquisition response
    {
    "SaleToPOIResponse": {
        "CardAcquisitionResponse": {
            "POIData": {
                "POITransactionID": {
                    "TimeStamp": "2019-12-04T12:02:49.000Z",
                    "TransactionID": "4rVu001575460969123"
                },
                "POIReconciliationID": "1000"
            },
            "SaleData": {
                "SaleTransactionID": {
                    "TimeStamp": "2019-12-04T12:02:49.000Z",
                    "TransactionID": "15890"
                }
            },
            "PaymentInstrumentData": {...},
            "Response": {
                "Result": "Success",
                "AdditionalResponse":"...shopperReference=john_smith&shopperEmail=john.smith@email.com..."
            }
        },
        "MessageHeader": {...}
    }
    }
  2. Check if the AdditionalResponse object contains a shopperReference.

    • If it contains a shopperReference, they are a returning customer. If you have previously stored the shopperEmail with Adyen, this is also provided in this response.
    • If it does not contain a shopperReference, the customer's card is not recognized.
      This usually means that the customer is new, and has not purchased with you before. However, they could also be a returning customer using a new card.

    To confirm, you can collect their email address, then check whether this matches a shopperEmail stored in your customer database:

    • If the email matches a shopperEmail in your database, they are a returning customer. Ask them if they want to save their new card. If they do, tokenize their new card using their shopperReference from your database when you make a payment.
    • If the email is not your database, they are a new customer. Continue with the transaction, and create a profile for this customer.

Step 2: Make a payment

Continue with the purchase by making a payment request:

  1. Make a POST request from your cash register to initiate the payment. If you are creating a profile for a new customer, also include parameters described in the Create customer profiles documentation.

    Here is how you can make a 10.99 EUR payment for a known customer.

    Terminal API request
    {
        "SaleToPOIRequest":{
            "MessageHeader":{
                "ProtocolVersion":"3.0",
                "MessageClass":"Service",
                "MessageCategory":"Payment",
                "MessageType":"Request",
                "SaleID":"POSSystemID12345",
                "ServiceID":"0207111105",
                "POIID":"V400m-324688179"
            },
            "PaymentRequest":{
                "SaleData":{
                    "SaleTransactionID":{
                        "TransactionID":"15887",
                        "TimeStamp":"2019-12-04T12:02:49.000Z"
                    }
                },
                "PaymentTransaction":{
                    "AmountsReq":{
                        "Currency":"EUR",
                        "RequestedAmount":10.99
                    }
                },
                "PaymentData":{
                    "CardAcquisitionReference":{
                        "TransactionID":"oLkO001528797935000",
                        "TimeStamp":"2019-12-04T12:02:49.000Z"
                    }
                }
            }
        }
    }

    You receive a response that includes an AdditionalResponse object, with a base64-encoded string that you need to decode to get a JSON object, or a string of form-encoded key-value pairs. In our examples, we use form-encoded key-value pairs.

    Payment response
    {
      "SaleToPOIResponse":{
        "MessageHeader":{...},
        "PaymentResponse":{
          "POIData":{
            "POITransactionID":{
              "TransactionID": "oLkO0012498220087567.991517998212382C"
            },
            ...
          },
          "Response":{
            "Result":"Success",
            "AdditionalResponse":"...shopperReference=john_smith&shopperEmail=john.smith@example.com..."
          },
          ...
        },
        "PaymentReceipt":{...}
      }
    }

Step 3: Request customer input

If the payment is Approved, you can immediately present a customer survey on your terminal.

In the examples below, we show questions used for measuring the Net Promoter Score (NPS). This is a widely used tool for measuring customer loyalty and satisfaction. You can also use your own custom survey questions instead.

  1. Make a MenuButtons input request from your cash register.

    In this request, the OutputContent.OutputText should represent the question you want to ask your customer. The possible responses to this question (for example, Very likely or Not at all likely) should be represented in the MenuEntry.OutputText array.

    The example below would present the message On a scale of zero to ten, how likely are you to recommend us to a friend? on the terminal display, followed by on-screen buttons for the customer to indicate their response.

    MenuButtons input request
    {
       "SaleToPOIRequest":{
          "MessageHeader":{
             ...
          },
          "InputRequest":{
             "DisplayOutput":{
                "Device":"CustomerDisplay",
                "InfoQualify":"Display",
                "OutputContent":{
                   "OutputFormat":"Text",
                   "PredefinedContent":{
                      "ReferenceID":"MenuButtons"
                   },
                   "OutputText":[
                      {"Text":"On a scale of zero to ten, how likely are you to recommend us to a friend?"}
                   ]
                },
                "MenuEntry":[
                   {
                      "OutputFormat":"Text",
                      "OutputText":[
                         {"Text":"10"},
                         {"Text":"Extremely likely"},
                         {"Text":""}
                      ]
                   },
                   {
                      "OutputFormat":"Text",
                      "OutputText":[
                         {"Text":"9"},
                         {"Text":"Very likely"},
                         {"Text":""}
                      ]
                   },
                   ...
                   {
                      "OutputFormat":"Text",
                      "OutputText":[
                         {"Text":"0"},
                         {"Text":"Not at all likely"},
                         {"Text":""}
                      ]
                   }
                ]
             },
             "InputData":{
                "Device":"CustomerInput",
                "InfoQualify":"Input",
                "InputCommand":"GetMenuEntry",
                "MaxInputTime":120
             }
          }
       }
    }

    The survey is presented on the terminal display. The customer can select their survey response using the terminal's built-in touchscreen. If your customer does not want to participate in the survey they can skip ahead to the transaction by pressing the red X button on the terminal.

    When they have completed the survey, you receive a response containing an InputResult. The customer's response is indicated in the Input.MenuEntryNumber array.

    In the example below, the second MenuEntryNumber is 1, indicating that the customer selected the second option presented on the terminal (9 - "Very likely").

    MenuButtons output request
    {
       "SaleToPOIResponse":{
          "InputResponse":{
             "InputResult":{
                "Device":"CustomerInput",
                "InfoQualify":"Input",
                "Response":{
                   "Result":"Success",
                   "AdditionalResponse":"responseData=%7b%20%22unique_id%22%3a%20%22001560869035%22%20%7d"
                },
                "Input":{
                   "MenuEntryNumber":[
                      0,
                      1,
                      ...
                      0
                   ],
                   "InputCommand":"GetMenuEntry"
                }
             },
             "OutputResult":{
                "Device":"CustomerDisplay",
                "InfoQualify":"Display",
                "Response":{
                   "Result":"Success"
                }
             }
          },
          "MessageHeader":{
             "ProtocolVersion":"3.0",
             "SaleID":"POSSystemID12345",
             "MessageClass":"Device",
             "MessageCategory":"Input",
             "ServiceID":"0207111104",
             "POIID":"V400m-324688179",
             "MessageType":"Response"
          }
       }
    }

    If your customer did not participate in the survey, the Response.Result will be set to Failure.

Step 4: Store survey response

Store the survey response in your database. If your customer was recognized, you can store the response under the customer's shopperReference.

Alternatively, you can store their response as anonymized data.

Next steps