Card and shopper identifiers for loyalty use cases

To personalize the shopping experience, recognize shoppers based on card data and other identifiers.

Implementation examples
.NET

You can use the card alias to recognize the shopper's card. But for shopper loyalty use cases you can also go one step further and create your own identifiers to be returned in card acquisition and payment responses. That enables you to identify an individual instead of just their payment card, and make the shopping experience more personal.

To use this method, you need to create customer profiles in your back-end system.

Requirements

Before you begin, take into account the following requirements and preparations.

Requirement	Description
Integration type	A Terminal API integration with payment terminals.
Setup steps	Before you begin: Ask our Support Team to check that your account is correctly configured for your loyalty use case. For the synchronous flow, enable receiving identifiers in Terminal API responses

Identifiers to save

To be able to personalize the shopper experience, save the following identifiers in the shopper profiles that you create in your back-end system:

Card alias (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 cannot use the card alias for making payments. You receive the card alias in the AdditionalResponse.
Shopper reference (shopperReference): Your reference to identify the shopper. You submit it with a payment, and receive it back in the AdditionalResponse for that payment and also in any later card acquisition and payment responses.

To get the shopper reference, you need to enable receiving this identifier.
Shopper email (shopperEmail): You collect the shopper's email address in some way, and submit it with a payment. You receive it back in the AdditionalResponse for that payment and also in any later card acquisition and payment responses.

Shopper consent and PIN entry

To save a shopper profile in your back-end system and to submit the shopper reference and email with your payment requests to our platform, you need to ask the shopper for their consent.

We can only return the shopper reference and email if your initial request also contains the recurringProcessingModel flag. This flag triggers the terminal to ask the shopper to authenticate by entering their PIN. Because there are still cards being used that do not have a PIN, our Support Team can disable asking for a PIN when the recurringProcessingModel flag is set. However, it goes against best practices to set this flag for every transaction.

Synchronous flow

The synchronous flow allows you to actively engage the shopper on the spot. For example, if you recognize the shopper from a card acquisition, you can apply a discount or offer to redeem loyalty points before making the payment.

Make a card acquisition request to check whether the shopper is recognized.
If the card acquisition response indicates the shopper is not known yet, create a new customer profile and make a payment. To ask the shopper's consent and gather the data for the customer profile, you can make input requests.
If the card acquisition response indicates the shopper is already known, optionally make input requests to communicate with the shopper, and then make a payment for a recognized shopper.

Check whether the shopper is recognized

When the shopper makes a purchase, first check if you already know the shopper.

If you are in Estonia, choose the Estonian ID card check tab below to learn how to identify the shopper with their national ID card.

Create a new customer profile and make a payment

When the card acquisition response shows the shopper is not known yet, you continue with a payment request that:

Refers to the card acquisition request.
Creates shopper identifiers to save in your back-end system.

Collect details from the shopper as needed for your use case, and ask the shopper's consent to save those details.
You can let your staff enter the information in your POS app, but you can also make input requests to let the shopper enter the information on the terminal. For example:
- Make a confirmation input request or a signature input request to ask the shopper's consent.
- Make text input requests to collect the shopper's name and email address, and a digit input request to collect their phone number.
- Make a display request with a QR code containing a URL to join your loyalty program or to download an app.

Make a payment request with:

Parameter	Required	Description
`PaymentData.CardAcquisitionReference`		An object referencing the card acquisition: `TimeStamp`: The time stamp returned in the `POIData.POITransactionID` of the card acquisition response. `TransactionID`: The transaction ID returned in the `POIData.POITransactionID` of the card acquisition response.
`SaleData.TokenRequestedType`		Customer. Returns the card alias in the `TokenValue` field of the response. Note that the card alias is always returned in the `AdditionalResponse`.
`SaleData.SaleToAcquirerData`		Data to create shopper identifiers. See the instructions below.

In SaleData.SaleToAcquirerData include:

shopperReference: Your unique reference for this shopper. Minimum length: three characters. Note that the value is case-sensitive. Do not include personally identifiable information (PII), such as name or email address.
shopperEmail: Optional. The shopper's email address, if you collected that in the first step.
recurringProcessingModel: CardOnFile. This triggers us to return the shopper reference and email in future card acquisition and payment responses.

Pass the SaleToAcquirerData value in one of the following formats:

Option 1: a JSON object converted to a Base64 encoded string. Refer to Add information to a payment.
Option 2: form-encoded key-value pairs (using & as a separator). For example:
shopperReference=12345&shopperEmail=S.Hopper@example.com&recurringProcessingModel=CardOnFile

The format that you use here, will also be the format of the AdditionalResponse that you receive.

When you receive the PaymentResponse, keep the following identifiers from the AdditionalResponse. You may need to Base64-decode the string first.
- alias: The card alias.
  If you specified a TokenRequestedType of Customer in the request, the card alias is also returned in PaymentToken.TokenValue.
- PaymentAccountReference: A value that represents the shopper's payment account that their card and/or NFC wallet is linked to. For NFC wallet transactions, a PAN is not available and thus there is no card alias.
- shopperReference: Your unique reference for this shopper that you specified in the request.
- shopperEmail: The shopper's email address that you specified in the request.
From now on the identifiers for this shopper are returned in card acquisition and payment responses.
In your system, create a customer profile for the shopper and save the shopper identifiers that you received in the payment response.
Also save the transaction data with the shopper's customer profile, to start building a transaction history.

Make a payment for a recognized shopper

When the card acquisition response shows the shopper is known already, you follow up with a payment request that refers to the card acquisition.

Using the shopperReference or other identifiers you received in the card acquisition response, find the shopper in your system.
Depending on your business logic, you may want to apply a discount or offer a gift. For example:
- Make a confirmation input request to ask whether the shopper wants to redeem loyalty points.
- Make a display request with a QR code containing a link to a promotional offer.
If necessary, update the final transaction amount. For example, if you applied a discount.

Make a payment request with:

Parameter	Required	Description
`PaymentTransaction.AmountsReq`		An object with: `Currency`: The transaction currency. `RequestedAmount`: The final transaction amount.
`PaymentData.CardAcquisitionReference`		An object containing data from the card acquisition: `TimeStamp`: The time stamp returned in the `POIData.POITransactionID` of the card acquisition response. `TransactionID`: The transaction ID returned in the `POIData.POITransactionID` of the card acquisition response.
`SaleData.TokenRequestedType`		Customer. Returns the card alias in the `TokenValue` field of the response. Note that the card alias is always returned in the `AdditionalResponse`.

When you receive the PaymentResponse, keep the following identifiers from the AdditionalResponse. You may need to Base64-decode the string first.
- alias: The card alias.
  If you specified a TokenRequestedType of Customer in the request, the card alias is also returned in PaymentToken.TokenValue.
- PaymentAccountReference: A value that represents the shopper's payment account that their card and/or NFC wallet is linked to.
- shopperReference: Your unique reference for this shopper, if you specified that when you created the customer profile.
- shopperEmail: The shopper's email address, if you specified that when you created the customer profile.
In your system, store the transaction data with the shopper's customer profile.

Asynchronous flow

The asynchronous flow is a simpler implementation of shopper loyalty, where you rely on webhooks to make loyalty adjustments in your system after the payment. In this flow, you cannot apply discounts or other loyalty benefits on the spot before the payment.

Make sure that you have set up receiving standard webhooks.
Create a customer profile for the shopper in your loyalty system.
Make a payment.
Wait for the AUTHORISATION webhook.
Based on the identifiers in the AUTHORISATION webhook, update the shopper's customer profile in your loyalty system. For example, add loyalty points.
Inform the shopper of the update in your loyalty system.

For more information about this flow, see our omnichannel documentation.