Point-of-sale icon

Receive card and shopper identifiers

Understand the data you may want to collect in shopper recognition use cases.

The payment data that you receive from Adyen offer a unique opportunity to connect payments with insights into your customers, and to implement specific customer journeys like the card acquisition scenarios. We refer to these data as card and shopper identifiers.

The identifiers are returned in Terminal API card acquisition and payment responses, and also asynchronously in webhooks. However, you don't receive all of them automatically. There are some identifiers that you need to enable in your Customer Area, and some that you first need to collect or create yourself.

Using card and shopper identifiers is even more powerful across channels. See our Unified commerce documentation.

General requirements

To use card and shopper identifiers, you need to:

  • Know what data you will be handling. Refer to the overview to learn more.
  • Understand and manage the privacy implications of using such data.
  • Have your own back-end system for storing shopper identifiers and purchase data, like a Customer Relationship Management System (CRM) or other database.
  • Implement business logic to get the desired result from this data. For example, to combine data in a way that answers questions about your shoppers.

Manage customer data and privacy

Before storing any customer data, including payment data, you need to consider data privacy.

  • Consult your legal department or an accredited third-party company to understand the data privacy regulations of the countries that you operate in.
  • Ask for your customer's explicit permission to store their data, and be clear about what you intend to use it for. For this, you could use the Terms and Conditions on your website, or you can use the payment terminal to interact with the customer.

If the customer asks to remove their information, you can use our Data Protection API to remove any customer-related data that you have stored with Adyen. The API also enables you to comply with the General Data Protection Regulation (GDPR) right to erasure.

Overview of card and shopper identifiers

Specific use cases or customer journeys can involve one or more of the following identifiers:

  • BIN: the Bank Identification Number of the shopper's card.

  • Card 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 and identify if they are returning customers. You can't use the card alias for making payments. For NFC wallet transactions, there's no card alias because the PAN is not available.

  • Funding source: funding source of the card, for example debit, credit, or prepaid.

  • Issuer country: the two-letter country code and the numeric country code of the country where the card was issued. This is a good indicator of the shopper's country of residence.

  • Payment Account Reference (PAR): the PAR is an identifier behind the card or NFC wallet. It represents the payment account that the card and/or NFC wallet is linked to. It solves the issue with the PAN not being available for NFC wallet transactions. You can use the PAR to identify the shopper.

Card schemes are starting to adopt the PAR. Currently, we return it for Visa and MasterCard transactions, when available. The PAR can be returned for ecommerce transactions and for Terminal API payment and card acquisition requests.

  • Recurring detail reference: the token for making recurring contract payments. The token is generated on the Adyen payments platform and returned in the response for the initial payment. In the recurring payments you use this token instead of actual card details.

  • Shopper reference: a unique reference defined by you and stored on the Adyen payments platform. With the shopper reference, you can recognize the shopper who makes the purchase. If you collect the shopper's email address, you can link multiple card aliases, shopper references, and recurring detail references (tokens) to the same shopper through their email address. The shopper reference and the recurring detail reference are necessary for making recurring contract payments.

  • Shopper email: the shopper's email address that you collected in some way, and stored on the Adyen payments platform when creating a recurring contract.

  • Token variant: the type of NFC wallet, like Apple Pay, used in the transaction. Note that this is not the kind of token you can use for making payments. Example value: mc_applepay.

The importance of these identifiers depends on your scenario. The following table shows the connection between identifiers and use case examples.

Identifier Insights Card recognition Loyalty Tax-free
BIN -white_check_mark-
Card alias -white_check_mark- -white_check_mark- -white_check_mark-
Funding source -white_check_mark-
Issuer country -white_check_mark- -white_check_mark-
Payment Account Reference -white_check_mark- -white_check_mark- -white_check_mark-
Recurring detail reference -white_check_mark-
Shopper email -white_check_mark-
Shopper reference -white_check_mark- -white_check_mark-

Receiving identifiers in Terminal API responses

The following identifiers are returned automatically:

  • Funding source
  • Card BIN

The shopper email is only returned in the response if you have previously collected the email from the shopper and stored the email with Adyen (through a payment request).

But to get the card alias, issuer country, PAR, shopper reference, and recurring detail reference, you need to enable receiving this data:

  1. In your Customer Area, go to Developers > Additional data.
  2. Select options:

    Identifier Instruction Result
    Card alias Select Payment > Include alias info Returns the alias in the AdditionalResponse.
    Issuer country Select Card > Issuer country Returns the numeric country code (for example, 528), both in the CardData and in the AdditionalResponse. Also returns the two-letter country code (for example, NL) in the AdditionalResponse.
    PAR Select Acquirer > Payment account reference Returns the PAR, if available
    Recurring detail reference Select Payment > Recurring details Returns the recurring detail reference and the shopper reference in the AdditionalResponse.
    Shopper reference Select Payment > Recurring details Returns the recurring detail reference and the shopper reference in the AdditionalResponse.


In the Terminal API response, the identifiers are in the AdditionalResponse. Some identifiers are also returned in other fields. We return the AdditionalResponse either as key-value pairs separated by an ampersand &, or as a Base64-encoded string that you need to decode to get a JSON object.

If the AdditionalResponse is returned as a Base64-encoded string, you get a JSON object similar to the following when you Base64-decode the string:

    "additionalData": {
        "AID": "A000000004101001",
        "adjustAuthorisationData": "BQABAQA20...oyMyv",
        "alias": "M469509594859802",
        "aliasType": "Default",
        "applicationPreferredName": "mc en gbr gbp",
        "backendGiftcardIndicator": "false",
        "batteryLevel": "40%",
        "cardBin": "541333",
        "cardHolderVerificationMethodResults": "420300",
        "cardIssueNumber": "33",
        "cardIssuerCountryId": "826",
        "cardScheme": "mc",
        "cardSummary": "9999",
        "cardType": "mc",
        "expiryMonth": "02",
        "expiryYear": "2028",
        "fundingSource": "CREDIT",
        "giftcardIndicator": "false",
        "iso8601TxDate": "2021-04-14T13:06:39.0000000+0000",
        "issuerCountry": "GB",
        "merchantReference": "818",
        "mid": "1000",
        "offline": "false",
        "paymentMethod": "mc",
        "paymentMethodVariant": "mc",
        "posAmountCashbackValue": "0",
        "posAmountGratuityValue": "0",
        "posAuthAmountCurrency": "EUR",
        "posAuthAmountValue": "12098",
        "posEntryMode": "CLESS_CHIP",
        "posOriginalAmountValue": "12098",
        "posadditionalamounts.originalAmountCurrency": "EUR",
        "posadditionalamounts.originalAmountValue": "12098",
        "pspReference": "NC6HT9CRT65ZGN82",
        "recurring.shopperReference": "SREF12458",
        "shopperEmail": "S.Hopper@example.com",
        "shopperReference": "SREF12458",
        "startMonth": "01",
        "startYear": "2017",
        "tc": "23733CAF5C7F70B2",
        "tid": "47069832",
        "transactionLanguage": "en",
        "transactionReferenceNumber": "NC6HT9CRT65ZGN82",
        "transactionType": "GOODS_SERVICES",
        "txdate": "14-04-2021",
        "txtime": "15:06:39"
    "store": "YOUR_STORE"

Receiving identifiers in webhooks

In particular for gaining insights across channels, you may want to gather identifiers from standard webhooks. You will receive the identifiers as additionalData included in the webhook.

  1. Set up a standard webhook, if you haven't done so already.

  2. In your Customer Area, open the Standard webhook you set up and select the additional settings you want to receive.

    Some of the settings you may want to enable, are:

    Identifier Additional setting to select
    Card alias Include Alias Info
    Funding source Include Funding Source
    Issuer country Include Issuer Country
    PAR Add Payment Account Reference
    Must be enabled under Developers > Additional data too.
    Recurring detail reference
    Can't be enabled in the webhook settings. Must be enabled under Developers > Additional data.
    Shopper email, shopper reference Include Shopper Details
    Token variant Include tokenTxVariant
    Must be enabled under Developers > Additional data too.
    BIN Include Card Bin
    POIID Include POS TerminalInfo
    Store name Include Store
    Tender reference, POIID Include POS Details
  3. To receive the PAR, the token variant, or the recurring detail reference in standard webhooks, go to Developers > Additional data and enable these identifiers:

    Identifier Additional data to select
    PAR Under Acquirer, select Payment account reference
    Token variant Under Card, select Token information for digital wallets
    Recurring detail reference Under Payment, select Recurring details

    When you enable identifiers under Developers > Additional data you also receive these identifiers in your API responses.

Example standard webhook

The following example shows the standard webhook for a point-of-sale payment. The identifiers are in the additionalData object.

See also