Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Tokenization

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

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.
  • Unified commerce: 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.

Tokenization is not supported yet on Android terminals.

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.

You can ask our POS Support Team 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. There are also other regulations that may apply.

Tokenization parameters

v.1.85 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 POS 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 POS Support team).
shopperReference (Your own reference) Your reference to uniquely identify this shopper, for example user ID or account ID. Minimum length: 3 characters.

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.

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 (recurringDetailReference): you receive this in the AdditionalResponse 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.

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

  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).
    • 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:

      JSON object
      {
          "recurringProcessingModel": "UnscheduledCardOnFile",
          "shopperReference": "12345",
          "shopperEmail": "S.Hopper@example.com"
      }
      Converted to Base64
      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
    {
       "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, 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.
    Response including the recurring detail reference (token)
    {
        "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": "...alias=M469509594859802...recurring.shopperReference=12345...shopperEmail=S.Hopper%40example.com&shopperReference=12345...&PaymentAccountReference=o4Yrw1bLz9sypaoG3Qklefx5WTv0j...",
                    "Result": "Success"
                },
                "SaleData": {...}
                }
            }
        }
    }

    Note that the PaymentToken object contains the card alias. You can't 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.

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.

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:
  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