To apply shopper recognition successfully, you need to know what data generates insights or is important in 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. But you don't receive all identifiers 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 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 Terminal API payment requests, but not yet for Terminal API card acquisition requests. -
Recurring detail reference: the token for making recurring contract 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 reference: a unique reference defined by you and stored on the plataforma de pagamentos da Adyen when creating a recurring contract. 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 and recurring detail references to the same shopper through their email address. The shopper reference is necessary for making recurring contract payments, in addition to the recurring detail reference (the token).
-
Shopper email: the shopper's email address that you collected in some way, and stored on the plataforma de pagamentos da Adyen 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-based identification |
Loyalty | Tax-free shopping |
Recurring payments |
---|---|---|---|---|---|
BIN | ![]() |
||||
Card alias | ![]() |
![]() |
![]() |
||
Funding source | ![]() |
||||
Issuer country | ![]() |
![]() |
|||
Payment Account Reference | ![]() |
![]() |
![]() |
||
Recurring detail reference | ![]() |
||||
Shopper email | ![]() |
||||
Shopper reference | ![]() |
![]() |
Receiving identifiers in Terminal API responses
The following identifiers are returned automatically:
- BIN
- Funding source
The shopper email is returned in the response if you have collected the shopper's email address earlier and stored that with Adyen (through a payment request).
But to get other the identifiers, you need to enable receiving them:
- In your Customer Area, go to Developers > Additional data.
-
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 theAdditionalResponse
. Also returns the two-letter country code (for example, NL) in theAdditionalResponse
.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
.
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.
{
"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 like 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 notification webhooks. You will receive the identifiers as additionalData
included in the notification.
- Set up a Standard notification webhook, if you haven't done so already.
-
In your Customer Area, open the Standard notification 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 -
To receive the PAR, the token variant, or the recurring detail reference in Standard notifications, 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 notification
The following example shows the standard notification webhook for a point-of-sale payment. The identifiers are in the additionalData
object.
{
"live": "false",
"notificationItems": [
{
"NotificationRequestItem": {
"additionalData": {
"alias": "M469509594859802",
"aliasType": "Default",
"authCode": "00",
"cardBin": "541333",
"cardSummary": "9999",
"expiryDate": "02/2028",
"fundingSource": "CREDIT",
"issuerCountry": "GB",
"recurring.shopperReference": "SREF12458",
"shopperEmail": "S.Hopper@example.com",
"shopperIP": "198.51.100.1",
"shopperReference": "SREF12458",
"store": "YOUR_STORE",
"tenderReference": "CYHG001647245627000",
"terminalId": "V400m-346403161"
},
"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.