Create and use tokens with the Advanced flow

To tokenize your shoppers payment details, you need to include additional fields when you make a /payments request. If your request is successful, you receive a webhook containing the token that can be used subsequent payments. You can use the token when making a payment request to offer returning customers a faster checkout experience. You can also use tokens to charge your customers for subscription, or automatic top-up payments.

Set parameters to flag transactions

When you make a /payments request to create a token or pay with a token, you must include:

When creating a token that you want to use for more than one type of recurring payment (for example, initially Subscription but in future also CardOnFile), use the recurringProcessingModel that is most appropriate at the time of token creation. In subsequent transactions you can then specify the applicable recurringProcessingModel.

Enable the webhook

When you store a shopper's payment details, you receive a RECURRING_CONTRACT webhook. You must enable it on the Standard webhook page and the Webhooks settings page.

The webhook includes the token that you use for payments with the shopper's stored payment details:

{
   "live" : "false",
   "notificationItems" : [
      {
         "NotificationRequestItem" : {
            "additionalData" : {
               "recurring.shopperReference" : "YOUR_SHOPPER_REFERENCE",
               "recurring.recurringDetailReference" : "M5N7TQ4TG5PFWR50",
               "hmacSignature" : "YOUR_HMAC_SIGNATURE",
               "shopperReference" : "YOUR_SHOPPER_REFERENCE",
               "checkoutSessionId" : "******************"
            },
            "amount" : {
               "currency" : "US",
               "value" : 0
            },
            "eventCode" : "RECURRING_CONTRACT",
            "eventDate" : "2023-06-20T16:09:48+02:00",
            "merchantAccountCode" : "YOUR_MERCHANT_ACCOUNT",
            "merchantReference" : "YOUR_PAYMENT_REFERENCE",
            "originalReference" : "DZ4DPSHB4WD2WN82",
            "paymentMethod" : "mc",
            "pspReferenceThis is a duplicate of recurringDetailReference." : "M5N7TQ4TG5PFWR50",
            "reasonWhen success = false, this field includes an explanation for the refusal." : "",
            "success" : "true"
         }
      }
   ]
}

Store the token with the shopper reference to associate the token with the shopper.

Create a token

Select the tab that fits your business model and follow the integration steps:

curl https://checkout-test.adyen.com/checkout/v70/payments \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
   "amount":{
      "value":0,
      "currency":"USD"
   },
   "paymentMethod":{
      "type":"scheme",
      "number":"4111111111111111",
      "expiryMonth":"03",
      "expiryYear":"2030",
      "cvc":"737",
      "holderName":"John Smith"
   },
   "reference":"YOUR_ORDER_REFERENCE",
   "shopperInteraction": "Ecommerce",
   "recurringProcessingModel": "Subscription",
   "storePaymentMethod": "true",
   "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
   "shopperReference":"YOUR_SHOPPER_REFERENCE",
   "returnUrl":"https://your-company.com/..."
}'

Result codes

The outcome of the tokenization request depends on the resultCode you get.

When you get the token, store it with your shopper reference so that you and the shopper can use it for recurring payments.

Authorised API response

For some API responses with resultCode: Authorised, the token is included. You can enable the feature to get the token in the API response, when available, in the additionalData.recurring.recurringDetailReference. For example:

{
    "additionalData": {
        "recurring.recurringDetailReference": "M5N7TQ4TG5PFWR50",
        "recurring.shopperReference":"YOUR_SHOPPER_REFERENCE"
    },
    "pspReference": "DZ4DPSHB4WD2WN82",
    "resultCode": "Authorised",
    "amount": {
        "currency": "USD",
        "value": 0
    },
    "merchantReference": "YOUR_ORDER_REFERENCE"
}

Because the API response does not always include the token, we recommend always getting it from the RECURRING_CONTRACT webhook.

Pay with a token

Select the type of recurring payment to make:

curl https://checkout-test.adyen.com/checkout/v70/payments \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
   "amount":{
      "value":2000,
      "currency":"USD"
   },
   "paymentMethod":{
      "type":"scheme",
      "storedPaymentMethodIdPreviously known as recurringDetailReference":"M5N7TQ4TG5PFWR50",
      "encryptedSecurityCode": "adyenjs_0_1_18$MT6ppy0FAMVMLH..."
   },
   "reference":"YOUR_ORDER_REFERENCE",
   "shopperInteraction": "ContAuth",
   "recurringProcessingModel": "CardOnFile",
   "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
   "shopperReference":"YOUR_SHOPPER_REFERENCE",
   "returnUrl":"https://your-company.com/..."
}'

Copy code
{
   "pspReference": "VK9DRSLLRCQ2WN82",
   "resultCode": "Authorised"
}

Test and go live

To receive the recurringDetailReference in the /payments response when it is available:

1. In your Customer Area, go to Developers > Additional data.
2. Select Recurring details.
3. Select Save.

In your test environment:

1. Test that you get the RECURRING_CONTRACT webhook.
2. Store a test token.
3. Make a test payment with the token.

Before going live:

Enable the RECURRING_CONTRACT webhook in your live Customer Area.

See also