Pesquisar

Are you looking for test card numbers?

Would you like to contact support?

Atenção, esta página não se encontra disponível em Português
Point-of-sale icon

Card and shopper identifiers

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

To apply shopper recognition successfully, you need to know what data can lead to insights or play a part in various use cases — like card-based identification, shopper loyalty and engagement, and recurring contract payments. 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 notification 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.

Overview of card and shopper identifiers

Shopper recognition use cases 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. 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: Country code of the country where the card was issued. This is usually a good indicator of the shopper's country of residence.

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

  • Shopper email: The shopper's email address that you collected in some way.

  • Shopper reference: A unique reference defined by you. With this, you can recognize the shopper who makes a purchase. If you collect the shopper's email address, you can link multiple card aliases and recurring detail references to the same shopper through their email address. The shopper reference is also necessary for making recurring contract payments.

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

Identifier Insights Card-based
identification
Loyalty Tax-free
shopping
Recurring
payments
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-
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
  • Card alias

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 issuer country, the shopper reference, and the recurring detail reference, you need to enable receiving them:

  1. In your Customer Area, go to Account > API URLs.
  2. On the Additional data settings tab, select options:

    Additional data setting Description
    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.
    Recurring details Returns the shopper reference and the recurring detail reference in the AdditionalResponse.

Example

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.

Identifiers in a payment response
{
    "SaleToPOIResponse": {
        "MessageHeader": {...},
        "PaymentResponse": {...},
            "PaymentReceipt": [...],
            "PaymentResult": {
                ...
                "PaymentInstrumentData": {
                    "CardData": {
                        "{hint:Included if you enabled receiving the issuer country}CardCountryCode{/hint}": "826",
                        ...
                        "PaymentToken": {
                            "TokenRequestedType": "Customer",
                            "{hint:The card alias, returned if the request includes TokenRequestedType}TokenValue": "M469509594859802{/hint}"
                        },
                    },
                    "PaymentInstrumentType": "Card"
                }
            },
            "Response": {
                "{hint:Includes identifiers and transaction details}AdditionalResponse{/hint}": "...&alias=M469509594859802....&recurring.shopperReference=SREF12458...&shopperReference=SREF12458&shopperEmail=S.Hopper%40example.com...&cardIssuerCountryId=826...&fundingSource=CREDIT&issuerCountry=GB...&cardBin=541333...",
                "Result": "Success"
            },
            "SaleData": {...}
        }
    }
}

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": "8825408195409505",
        "recurring.shopperReference": "SREF12458",
        "shopperEmail": "S.Hopper@example.com",
        "shopperReference": "SREF12458",
        "startMonth": "01",
        "startYear": "2017",
        "tc": "23733CAF5C7F70B2",
        "tid": "47069832",
        "transactionLanguage": "en",
        "transactionReferenceNumber": "8825408195409505",
        "transactionType": "GOODS_SERVICES",
        "txdate": "14-04-2021",
        "txtime": "15:06:39"
    },
    "store": "YOUR_STORE"
}

Receiving identifiers in webhooks

Especially for gaining insights across channels, you may want to gather identifiers from Standard Notification webhooks.

  1. Set up Standard Notification webhooks.
  2. Enable additional settings for the identifiers that you want to receive. The fields are returned in the additionalData of the webhook. Some of the settings you may want to enable, are:

    Additional setting Description
    Include Alias Info Returns alias and aliasType
    Include Card Bin Returns the cardBin
    Include Funding Source Returns the fundingSource
    Include Issuer Country Returns the issuerCountry
    Include Shopper Details Returns the shopperEmail and shopperReference

Example

In the notification, the identifiers are in the additionalData object.

Identifiers in a Standard Notification webhook
{
    "live": "false",
    "notificationItems": [
        {
            "NotificationRequestItem": {
                "additionalData": {
                    "authCode": "00",
                    "cardSummary": "9999",
                    "shopperEmail": "S.Hopper@example.com",
                    "shopperIP": "198.51.100.1",
                    "expiryDate": "02/2028",
                    "issuerCountry": "GB",
                    "cardBin": "541333",
                    "aliasType": "Default",
                    "alias": "M469509594859802",
                    "recurring.shopperReference": "SREF12458",
                    "fundingSource": "CREDIT",
                    "shopperReference": "SREF12458"
                },
                "amount": {
                    "currency": "EUR",
                    "value": 12098
                },
                "eventCode": "AUTHORISATION",
                "eventDate": "2021-04-14T15:30:14+02:00",
                "merchantAccountCode": "YOUR_MERCHANT_ACCOUNT",
                "merchantReference": "902",
                "operations": [
                    "CANCEL",
                    "CAPTURE",
                    "REFUND"
                ],
                "paymentMethod": "mc",
                "pspReference": "8825408195409505",
                "reason": "00:9999:02/2028",
                "success": "true"
            }
        }
    ]
}

What do you want to do?

Now that you understand the data involved in shopper recognition, select the topic that you want to know more about.