---
title: "Tokenization"
description: "Tokenize a point-of-sale payment for future card-on-file or recurring payments."
url: "https://docs.adyen.com/point-of-sale/recurring-payments"
source_url: "https://docs.adyen.com/point-of-sale/recurring-payments.md"
canonical: "https://docs.adyen.com/point-of-sale/recurring-payments"
last_modified: "2026-06-01T15:33:14+02:00"
language: "en"
---

# Tokenization

Tokenize a point-of-sale payment for future card-on-file or recurring payments.

[View source](/point-of-sale/recurring-payments.md)

For certain business models, tokenization is necessary to securely capture and store a shopper's card details during an in-person transaction. This process allows you to create a so-called *recurring contract* and 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.

## Requirements

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

| Requirement          | Description                                                                                                                                                                                                                                  |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Integration type** | A [Terminal API](/point-of-sale/design-your-integration/terminal-api) integration with payment terminals.                                                                                                                                    |
| **Limitations**      | Note that while we backward-support the old system, you cannot use both the old and [new parameters (available from software version 1.85)](/point-of-sale/recurring-payments#tokenization-parameters) in the same payment request.          |
| **Setup steps**      | Before you begin, review [additional SCA requirements based on business models](/online-payments/psd2-sca-compliance-and-implementation-guide/business-models-overview) that can apply to you depending on your tokenization implementation. |

## How it works

If you tokenize the shopper's payment details when they make a payment at the point of sale, you can use that token in a later online payment.

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

## 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)](/online-payments/psd2-sca-compliance-and-implementation-guide) 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.

You can ask our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to ensure the terminal asks for a PIN when the payment request includes specific tokenization parameter values.

To check if PSD2 SCA applies to you, see our [self-service guide](/online-payments/psd2-sca-compliance-and-implementation-guide#are-my-payments-affected). There are also [other regulations](/online-payments/3d-secure-for-regulation-compliance#overviewofexistingregulations) 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. |

**

## Migration from old tokenization parameters

Previously, there was a difference in the tokenization parameter and values between ecommerce and point of sale. If you implemented tokenization of in-person payments before software version 1.85, you are using that old system. We backward-support the old system, but encourage you to migrate to the new system.

We do not support using both the old and the new tokenization parameters in the same payment request.

To help you migrate to the new system, see the following table.

| Parameter or value | Old                     | New                                                                                                                   |
| ------------------ | ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
| parameter          | `recurringContract`     | `recurringProcessingModel`                                                                                            |
| value              | **ONECLICK**            | **CardOnFile**                                                                                                        |
| value              | **RECURRING**           | **Subscription** or **UnscheduledCardOnFile**                                                                         |
| value              | **ONECLICK, RECURRING** | Use a single value that best represents your use case: **CardOnFile**, **Subscription**, or **UnscheduledCardOnFile** |

## 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 in the `AdditionalResponse `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 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](/point-of-sale/card-acquisition/identifiers) like the card alias and the payment account reference (PAR).

To enable receiving these identifiers in API responses:

1. In your [Customer Area](https://ca-test.adyen.com/), 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](/point-of-sale/shopper-engagement/shopper-input/confirmation) or [signature input request](/point-of-sale/shopper-engagement/shopper-input/signature) to ask the shopper's consent.

   * [Text input requests](/point-of-sale/shopper-engagement/shopper-input/text) and a [phone number input request](/point-of-sale/shopper-engagement/shopper-input/phone-number) to collect the shopper's contact details.

2. [Make a payment request](/point-of-sale/basic-tapi-integration/make-a-payment) including a [SaleData](https://docs.adyen.com/api-explorer/terminal-api/latest/post/payment#request-SaleData) object 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`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
   | [SaleToAcquirerData](https://docs.adyen.com/api-explorer/terminal-api/latest/post/payment#request-SaleData-SaleToAcquirerData) |          | Data to create the token and shopper identifiers. 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](#tokenization-parameters).
    |

   Pass the `SaleToAcquirerData` value in one of the following formats (refer to [Add information to a payment](/point-of-sale/add-data)):

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

     **JSON object**

     ```json
     {
         "recurringProcessingModel": "UnscheduledCardOnFile",
         "shopperReference": "12345",
         "shopperEmail": "S.Hopper@example.com"
     }
     ```

     **Converted to Base64**

     ```raw
     ewogICAgInJlY3VycmluZ1Byb2Nlc3NpbmdNb2RlbCI6ICJVbnNjaGVkdWxlZENhcmRPbkZpbGUiLAogICAgInNob3BwZXJSZWZlcmVuY2UiOiAiMTIzNDUiLAogICAgInNob3BwZXJFbWFpbCI6ICJTLkhvcHBlckBleGFtcGxlLmNvbSIKfQ==
     ```

   * 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.

   **Tokenization request**

   ```json
   {
      "SaleToPOIRequest":{
         "MessageHeader":{
            "ProtocolVersion":"3.0",
            "MessageClass":"Service",
            "MessageCategory":"Payment",
            "MessageType":"Request",
            "SaleID":"POSSystemID12345",
            "ServiceID":"01142",
            "POIID":"V400m-346403161"
         },
         "PaymentRequest":{
            "SaleData":{
               "SaleTransactionID":{
                  "TransactionID":"12420",
                  "TimeStamp":"2022-12-13T10:18:45.000Z"
               },
               "SaleToAcquirerData":"recurringProcessingModel=UnscheduledCardOnFile&shopperReference=12345&shopperEmail=S.Hopper@example.com",
               "TokenRequestedType":"Customer"
            },
            "PaymentTransaction":{
               "AmountsReq":{
                  "Currency":"EUR",
                  "RequestedAmount":32.76
               }
            }
         }
      }
   }
   ```

3. When you receive the [PaymentResponse](https://docs.adyen.com/api-explorer/terminal-api/latest/post/payment#responses-200), note that the `AdditionalResponse` (you may need to Base64-decode first) contains:

   * `tokenization.store.operationType`: informs you whether a token was successfully created. Possible values: **created**, **alreadyExisting**, **updated**.

   Save the following fields from the `AdditionalResponse` in your back-end system:

   * `recurring.recurringDetailReference` and `tokenization.storedPaymentMethodId`: the token representing the shopper's payment method, for use in online recurring payments.
   * `recurring.shopperReference` and `tokenization.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.

   **Response including the recurring detail reference (token)**

   ```json
   {
       "SaleToPOIResponse": {
           "MessageHeader": {...},
           "PaymentResponse": {
               "POIData": {
                   "POIReconciliationID": "1000",
                   "POITransactionID": {
                       "TimeStamp": "2022-12-13T10:18:47.000Z",
                       "TransactionID": "8ha5001670926727000.SQC78ZN4875ZGN82"
                   }
               },
               "PaymentReceipt": [...],
               "PaymentResult": {
                   ...,
                   "PaymentInstrumentData": {
                       "CardData": {
                           "EntryMode": [
                               "Contactless"
                           ],
                           "MaskedPan": "541333 **** 9999",
                           "PaymentBrand": "mc",
                           "{hint:This is the card alias, not the token for future payments}PaymentToken{/hint}": {
                               "TokenRequestedType": "Customer",
                               "TokenValue": "M469509594859802"
                           },
                           "SensitiveCardData": {...
                           }
                       },
                       "PaymentInstrumentType": "Card"
                   }
               },
               "Response": {
                   "AdditionalResponse": "...PaymentAccountReference=HcQNpZIC4aB3Zn0QkdiKnw30acufi...alias=M469509594859802...recurring.recurringDetailReference=7219687191761347&recurring.shopperReference=12345&recurringProcessingModel=Subscription...shopperEmail=S.Hopper%40example.com...tokenization.shopperReference=12345&tokenization.store.operationType=created&tokenization.storedPaymentMethodId=7219687191761347...",
                   "Result": "Success"
               },
               "SaleData": {...}
               }
           }
       }
   }
   ```

   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 token 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](/development-resources/api-credentials#generate-api-key) to authenticate your request to the back end.

If you are using a Terminal API integration with [cloud-based communications](/point-of-sale/design-your-integration/choose-your-architecture#cloud-communications), you can use the existing API key that you use for Terminal API requests.

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

1. Make a POST [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/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](/online-payments/tokenization/make-token-payments#make-a-one-click-payment)
     * [Subscription payment](/online-payments/tokenization/make-token-payments#make-a-subscription-or-unscheduled-card-on-file-payment)
     * [Auto top-up payment](/online-payments/tokenization/make-token-payments#make-a-subscription-or-unscheduled-card-on-file-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](/development-resources/api-credentials). This API credential must have an [API key](/development-resources/api-credentials#generate-api-key).

  If you are using a Terminal API integration with [cloud-based communications](/point-of-sale/design-your-integration/choose-your-architecture#cloud-communications), you can use the existing API key that you use for Terminal API requests.

* For instructions, see [Manage tokens](/online-payments/tokenization/managing-tokens).

## See also

* [Blog: Everything you need to know about card-on-file](https://www.adyen.com/knowledge-hub/card-on-file)
* [Pass additional data](/point-of-sale/add-data)
* [Ask for input on the terminal](/point-of-sale/shopper-engagement/shopper-input)
