Tokenize a payment

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. Tokenization is the process of storing a shopper's payment details. We refer to these saved payment details as tokens.

How it works

1. You ask the cardholder's consent to tokenize their card for specific future payments.
2. You make the initial point-of-sale payment with tokenization parameters.
3. We securely save the shopper's payment details, and in the authorization response send you a token called recurring detail reference. This token represents the shopper's payment details.
4. You make a payment completion request.
5. 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 then use a token for customer authentication. When the initial transaction is a point-of-sale payment, PIN entry is the most common customer authentication method.

Proceed as follows:

1. Verify if SCA is required in your situation:
   • To check if PSD2 SCA applies, see our self-service guide.
   • Check for other regulations that require SCA.
2. If SCA is required, make sure your terminals ask for a PIN when the payment request includes specific tokenization parameter values.

Tokenization parameters

The parameters to use in a payment request for tokenizing the payment details are the same for in-person payments and online payments. These parameters are:

Enable receiving tokenization details

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

• Recurring detail reference: this is the token you need to use in future recurring payments. You receive this under recurringDetails in the response to the initial payment in recurring.recurringDetailReference and tokenization.storedPaymentMethodId.
• Shopper reference (shopperReference): this is your own reference to the shopper. You submit it with the initial payment, and receive it back under recurringDetails in the response . 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 recurringDetails field .
   Shopper reference	Select Payment > Recurring details	Returns the recurring detail reference and the shopper reference in the recurringDetails field .
   Card alias	Select Payment > Include alias info	Returns the alias in the recurringDetails field .
   Payment account reference (PAR)	Select Acquirer > Payment account reference	Returns the PAR, if available.

Make the initial payment

To create a token from a host-to host 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.

2. Make a POST /hosttohostpaymentgateway/v#/payments authorization request. In the body of the request include a recurring object with the following parameters.

   Field	Required	Type	Description
   shopperReference		string	Your reference to uniquely identify this shopper, for example user ID or account ID. Do not use personally identifiable information. Minimum length: three characters.
   recurringProcessingModel		string	Creates a recurring contract. Possible values are: 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.
   shopperEmail		string	Your unique reference for the transaction. Max. 80 characters.

3. When you receive the PaymentResponse, save the following data in your back-end system:

   • recurringDetailReference: the token representing the shopper's payment method, for use in online recurring payments.
   • 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, if enabled.
   • PaymentAccountReference: a reference to the payment account that is linked to the shopper's card and/or NFC wallet.

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

4. Make a payment completion request by sending a POST request to the /hosttohostpaymentgateway/v#/payments/{paymentPspsReference}/completions endpoint. In the URL, {paymentPspReference} is the pspReference of the authorization response.

5. Wait for an AUTHORISATION webhook to learn the result of the payment after authorization and completion.

If completion of the authorization succeeded, the transaction has the status Authorised in your Customer Area.

Make a recurring online payment

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, or storedPaymentMethodId, returned in the Terminal API payment response for the initial point-of-sale payment. This is the token.
   • shopperReference: your unique identifier for the shopper, 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.
• For instructions, see Manage tokens.

See also