Tokenization

For certain business models you need to be able to make later charges after the shopper's initial point-of-sale transaction. For example:

• Subscriptions: cross-sell products that require regular payments, such as an insurance policy for a product that the shopper bought in your store.
• Hospitality: charge no-shows, or charge guests for additional services or damages.
• Autonomous stores: charge the shopper for the groceries they walked out with, if the payment failed at first. Using the token the payment can be retried later.
• Omnichannel: complete part of the sale in-store, and complete another part of the sale after goods are delivered to the shopper.

For these situations you can use tokenization to create a so-called recurring contract:

1. You ask the shopper's consent to tokenize their card for specific future payments.
2. You make an initial point-of-sale payment with tokenization parameters.
3. We securely save the shopper's payment details, and generate and send you a token called recurring detail reference. This token represents the shopper's payment details.
4. You use the token to make a later online payment with saved payment details.

To sum it up: if you tokenize the customer's payment details when they make a payment at the point of sale, you can use that token in a later online payment.

Cardholder consent and authentication

Tokenization should always be an opt-in process. Without the shopper's consent, there is an increased chance of chargebacks for payments made using saved card details.

Under PSD2 regulations, the tokenization process also requires Strong Customer Authentication (SCA) on the initial transaction. The later transactions are then exempted from customer authentication and can be made using a token. When the initial transaction is a point-of-sale payment, the customer authentication is usually done through PIN entry. However, the terminal will not prompt for a PIN in case of:

• A payment with a digital wallet that has built-in password or biometric authentication.
• A contactless payment below the CVM limit.

To check if PSD2 SCA applies to you, see our self-service guide. There are also other regulations that may apply.

Tokenization parameters

From software version 1.85, the parameters to use in a payment request for tokenizing the payment details are the same for online payments and in-person payments. These parameters are:

Parameter	Value	Description
recurringProcessingModel	CardOnFile	Creates a recurring contract for one-off transactions where a shopper can either store their payment details or pay in your website or app at a later time using their saved details. Doesn't enforce cardholder authentication.
	Subscription	Creates a recurring contract for transactions that occur on a fixed schedule for a fixed or variable amount. Enforces cardholder authentication (if configured by our Support Team).
	UnscheduledCardOnFile	Creates a recurring contract for transactions that occur on a non-fixed schedule and/or have variable amounts. Enforces cardholder authentication (if configured by our Support Team).
shopperReference	(Your own reference)	Your unique reference, such as user ID or account ID. Also, each shopper reference must have a minimum length of three characters, and should not include personally identifiable information (PII) such as name or email address.

Enable receiving tokenization details

To make later payments using saved payment details, you must keep track of the following identifiers:

• Recurring detail reference (recurringDetailReference): you receive this in the AdditionalResponse to to the initial payment. It is the token for future recurring payments.
• Shopper reference (shopperReference): this is your own reference to the shopper. You submit it with the initial payment, and receive it back in the AdditionalResponse . In a future recurring payment, you submit it again. The shopper reference must have a minimum length of three characters, and should not include personally identifiable information (PII) such as name or email address.

In addition, it can be useful to keep track of other identifiers like the card alias and the payment account reference (PAR).

To enable receiving these identifiers in API responses:

1. In your Customer Area, go to Developers > Additional data.

2. Select options:

   Identifier	Instruction	Result
   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 .
   Card alias	Select Payment > Include alias info	Returns the alias in the AdditionalResponse .
   Payment account reference (PAR)	Select Acquirer > Payment account reference	Returns the PAR, if available.

Make the initial payment

To create a token from a point-of-sale transaction:

1. Get the shopper's consent to save their payment details for future online payments, and collect any contact details you need.
   You can let your staff enter the information in your POS app, but you can also make input requests to collect the information on the terminal. For example:

   • A confirmation input request or signature input request to ask the shopper's consent.

   • Text input requests and a phone number input request to collect the shopper's contact details.

2. Make a PaymentRequest with:

   Parameter	Required	Description
   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 the token and shopper identifiers (see 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, Subscription, or UnscheduledCardOnFile. We will create a token for later payments, and save the shopper reference and shopper email on our platform. See Tokenization parameters.

   Pass the SaleToAcquirerData value in one of the following formats (refer to Add information to a payment):

   • Option 1: a JSON object converted to a Base64 encoded string. For example:

   • Option 2: form-encoded key-value pairs, using & as a separator. For example:
     recurringProcessingModel=UnscheduledCardOnFile&shopperReference=12345&shopperEmail=S.Hopper@example.com

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

3. When you receive the PaymentResponse, save the following data from the AdditionalResponse (you may need to Base64-decode first) in your back-end system:

   • recurring.recurringDetailReference: the token representing the shopper's payment method, for use in online recurring payments.
   • recurring.shopperReference: your unique reference for this shopper that you specified in the request.

   Optionally also keep the following card and shopper identifiers, for easier shopper recognition:

   • shopperEmail: the shopper's email address, if you specified that in the request.
   • alias: the card alias.
   • PaymentAccountReference: a reference to the payment account that is linked to the shopper's card and/or NFC wallet.

   Note that the PaymentToken object contains the card alias. You cannot use this for making payments. It is intended only for recognizing the card.

The recurring detail reference and the shopper reference are now saved on the Adyen payments platform, as well as the shopper's email address if you specified that in the request.

Make a recurring online payment

For an online payment using saved payment details you make a request to the Adyen back end directly. This is not a Terminal API request to either the terminal itself or the cloud endpoint for the terminal. You need to generate an API key to authenticate your request to the back end.

To make an online payment using a token you created with a point-of-sale payment:

1. Make a POST /payments request including:

   • storedPaymentMethodId: the recurringDetailReference returned in the Terminal API payment response for the initial point-of-sale payment. This is the token.
   • shopperReference your unique shopperReference that you created with the initial point-of-sale payment.
   • For the other parameters and values to use, refer to:
     • One-off payment
     • Subscription payment
     • Auto top-up payment

2. When you receive the response, check that it has a resultCode of Authorised. This means the payment using the saved payment details was successful.

Token management

You can view, update, and remove saved payment details by making API calls to various online payments endpoints.

• To authenticate API calls for token management, you need an API credential. This API credential must have an API key.

  If you are using a Terminal API integration with cloud-based communications, you can use the existing API key that you use for Terminal API requests.

• For instructions, see Manage tokens.

See also