Search

Are you looking for test card numbers?

Would you like to contact support?

Omnichannel icon

Recognizing customers

Identify your returning customers when they purchase in your online and physical stores.

After you've created a profile for a customer, you will be able to use the data in their profile to recognize them the next time they purchase in any of your sales channels.

In this guide, we'll show you how you can use the shopperEmail and shopperReference to identify a returning customer online or in store.

Recognize returning customers online

Before making their online purchase, your customer will provide you with an email address (for example, when creating an account for your online store, or when using your guest checkout).

To recognize whether they are a returning customer, check if their contact details match a shopperEmail that you have stored in your customer database.

Once you are able to recognize returning customers in your online or in-app checkout, you can learn how to do the same in store.

Showing a saved card in your online checkout

If the customer created an online store account and you have saved and tokenized their card details in a previous in-store payment, you can then offer them a more frictionless online checkout experience by showing their saved card details.

To present a customer's saved card in your online checkout:

  1. Using the customer's email address, fetch their shopperReference and recurringDetailReference from your customer database.

  2. If you are using Drop-in or Components, you can also confirm if the customer has saved card details when you make a POST /paymentMethods call. In this request, additionally include the shopperReference.

    The example below shows how you would do this for a customer with unique shopperReference john_smith:

    Payment methods request
    {
      "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
      "{hint:This is the unique customer reference in your db}shopperReference{/hint}": "john_smith",
      "amount": {
        "currency": "EUR",
        "value": 1099
      }
    }

    You receive a response containing a list of available payment methods, including the customer's stored payment details. You can find the customer's stored card in the storedPaymentMethods array.

    The example below shows what this response would look like if this customer has a stored Visa card. The storedPaymentMethods.id should match the recurringDetailReference that you stored for this customer in your database.

    Payment methods response
    {
      "paymentMethods":[...],
      "storedPaymentMethods":[
        {
          "brand":"visa",
          "expiryMonth":"10",
          "expiryYear":"2020",
          "holderName":"John Smith",
          "{hint: This is the recurringDetailReference}id{/hint}":"7219687191761347",
          "lastFour":"1111",
          "name":"VISA",
          "supportedShopperInteractions":[
            "Ecommerce",
            "ContAuth"
          ],
          "type":"scheme"
        }
      ]
    }
  3. Present your customer's saved card details, and show a CVC/CVV field to collect their card security code.
    • If you're using Drop-in, this integration supports showing saved card details by default. For Components, you can use the stored card component for Web, iOS, or Android. Both Drop-in and Components integration present the saved card details, and collect and encrypt your customer's card security code.
    • If you're using an API-only integration, you need to build your own UI to show the stored card details and to collect your customer's card security code. You can either make a custom card integration or submit raw card data if you're fully PCI compliant.

  4. If the customer chooses to pay with their saved card, continue with the payment by making a POST /payments request. In this request, additionally include:

    • shopperReference: The customer's shopperReference, from your database.
    • shopperInteraction: Set this to ContAuth to indicate that the customer is a returning customer.
    • recurringProcessingModel: Set to CardOnFile to specify a one-off payment.
    • paymentMethod: Object that contains the customer's card details:
      • recurringDetailReference: The customer's tokenized card details.
      • encryptedSecurityCode or cvc: The customer's card security code sent either as encrypted data (returned from Drop-in, Components, or custom card integration) or as raw data (if you're fully PCI compliant).

    The example below shows how you would make a payment for a customer with a shopperReference of john_smith, and a recurringDetailReference of 7219687191761347.

    Online payment request
    {
       "amount":{
          "value":2000,
          "currency":"USD"
       },
       "paymentMethod":{
          "type": "scheme",
          "recurringDetailReference":"7219687191761347",
          "encryptedSecurityCode": "adyen_737x19daxH..."
       },
       "reference":"YOUR_ORDER_NUMBER",
       "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
       "returnUrl":"https://your-company.com/...",
       "shopperReference":"john_smith",
       "shopperInteraction":"ContAuth",
       "recurringProcessingModel": "CardOnFile"
    }

    If the payment is successful you receive a resultCode of Authorised.

    Online payment response
    {
       "pspReference": "881532984281546H",
       "resultCode": "Authorised"
    }

Recognize returning customers in store

When a customer makes an in-store purchase, you can attempt to recognize if they are a returning customer by making a card acquisition request. This request checks whether you stored a shopperReference (unique reference for this customer) in a previous transaction. If you have, Adyen returns the shopperReference in the response.

To recognize a customer when they make an in-store purchase:

  1. Make a card acquisition request.

    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.
  3. Continue with the transaction by making a payment request from your cash register, containing data returned in the card acquisition response.

    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":"4rVu001575460969123",
                        "TimeStamp":"2019-12-04T12:02:49.000Z"
                    }
                }
            }
        }
    }

    If the request is successful, you receive a response containing:

    • POIData.POITransactionID.TransactionID: Transaction identifier for the payment.
    • PaymentResponse.Response.Result: Success

    The example result below indicates that the payment was successful. The transaction identifier for this payment is oLkO0012498220087000.981517998282382C.

    Payment response
    {
      "SaleToPOIResponse":{
        "MessageHeader":{...},
        "PaymentResponse":{
          "POIData":{
            "POITransactionID":{
              "TransactionID": "oLkO0012498220087000.981517998282382C"
            },
            ...
          },
          "Response":{
            "Result":"Success"
          },
          ...
        },
        "PaymentReceipt":{...}
      }
    }

Next steps

Now that both your sales channels are able to create and recognize customers, you are able to offer these customers with better purchasing experiences.