Create and use tokens with the Sessions flow

Learn how to create and use tokens with a Sessions flow integration.

Implementation examples
  Java Spring
  .NET
  Node.js

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

If you are implementing 3D Secure for PSD2 SCA compliance, use our self-service guide to find out about the PSD2 SCA compliance rules that apply to your business when tokenizing shopper payment details.

Set parameters to flag transactions

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

Parameter	Description
recurringProcessingModel	When you first create a token, indicates what type of recurring payment the token is intended for. For subsequent payments, indicates the type of recurring payment. Possible values: CardOnFile: A transaction where shopper card details are stored to enable one-click or omnichannel journeys, or to offer a faster checkout later. UnscheduledCardOnFile: A transaction that occurs on a non-fixed schedule and/or have variable amounts. Subscription: A transaction for a fixed or variable amount, which follows a fixed schedule.
shopperInteraction	Indicates the sales channel through which the shopper gives their card details, for online transactions, this is Ecommerce. For subsequent payments, indicates whether the shopper is a returning customer (ContAuth).
shopperReference	Your unique reference for the 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.
storePaymentMethodMode	Indicates if the details of the payment method will be stored for the shopper. Possible values: disabled: No details will be stored (default). askForConsent: When `shopperReference` is included, the Drop-in/Component shows a checkbox where the shopper can select to store their payment details. enabled: When `shopperReference` is included, the payment details will be stored. The Drop-in/Component will not display a checkbox where the shopper can select to store their payment details.

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

Field	Description
`originalReference`	The `pspReference` for the payment made to store the shopper's payment details.
`additionalData.recurring.recurringDetailReference`	The token for the stored payment details. You must contact our Support Team to enable this parameter in your response.
`additionalData.recurring.shopperReference`	Your unique shopper reference. Use this to associate the shopper with the token.
`pspReference`	The token for the stored payment details. This is the same as `recurringDetailReference`.

Example RECURRING_CONTRACT webhook

 {
   "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"
         }
      }
   ]
}

Create a token

You can use the /sessions endpoint to create tokens for all recurring payment types, but you need to use the /payments endpoint to make subsequent Subscription and UnscheduledCardOnFile payments with tokens.

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

We strongly recommend that you ask explicit permission from the shopper if you intend to store their payment details.

One-off transactions where a shopper stores payment details or where the shopper purchases from your website or app at a later time using the saved details.

SCA can be required depending on regulations and scheme rules.

Save payment details for one-off payments

From your server, make a POST /sessions request including:

Parameter	Description
amount	The `currency` and `value` of the payment amount in minor units. You can set `amount.value` to 0 to validate the payment details with a zero-auth transaction before processing payments.
shopperReference	Your unique identifier for the 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.
shopperInteraction	Ecommerce
recurringProcessingModel	CardOnFile
storePaymentMethodMode	askForConsent: To display a checkbox where the shopper can select to store their payment details. enabled: To store your shopper's payment details without displaying a checkbox where the shopper can select to store their payment details.

Create a token

 curl https://checkout-test.adyen.com/checkout/v71/sessions \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
   "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
   "amount": {
      "value": 100,
      "currency": "EUR"
   },
   "shopperReference": "YOUR_SHOPPER_REFERENCE",
   "returnUrl": "https://your-company.com/checkout?shopperOrder=12xy..",
   "reference": "YOUR_PAYMENT_REFERENCE",
   "countryCode": "NL",
   "storePaymentMethodMode": "enabled",
   "shopperInteraction": "Ecommerce",
   "recurringProcessingModel": "CardOnFile"
}'

The token is created after a successful payment authorization to ensure that the payment details the shopper provided are linked to an active, chargeable account. You receive the token you can use for future payments in an asynchronous RECURRING_CONTRACT webhook.

You get a /sessions response, including storePaymentMethod: true.

Example response after a token is created

 {
   "amount": {
     "currency": "EUR",
     "value": 100
   },
   "shopperReference": "YOUR_SHOPPER_REFERENCE",
   "countryCode": "NL",
   "expiresAt": "2022-01-11T13:56:05+01:00",
   "id": "FJM726V375BV9D82",
   "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
   "recurringProcessingModel": "CardOnFile",
   "reference": "YOUR_PAYMENT_REFERENCE",
   "returnUrl": "https://your-company.com/checkout?shopperOrder=12xy..",
   "shopperInteraction": "Ecommerce",
   "storePaymentMethod": true,
   "sessionData": "Ab02b4c0!BQABAgBfYI29..."
}

Pay with a token

Select the type of recurring payment to make:

Present the shopper's saved payment method in your payment form.

With our client-side solutions (Drop-in, Components, or Pay by Link), you can present a shopper's stored cards in the payment form. For more information on how to do this, refer to the Cards documentation for Drop-in (Web, iOS, Android), the Card Component documentation (Web, iOS, Android), or our Pay by Link documentation.

From your server, make a POST /sessions request including:

Parameter	Required	Description
shopperReference		Your unique identifier for the shopper. Must be the same one you included with the request to create the token.
shopperInteraction		ContAuth
recurringProcessingModel		CardOnFile

If you use 3D Secure for PSD2 SCA compliance, some issuing banks require SCA for ContAuth with CardOnFile transactions. See the PSD2 SCA compliance guide for more information.

Test and go live

In your test environment:

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

Before going live:

Enable the RECURRING_CONTRACT webhook in your live Customer Area.

Next steps

Capture a payment

Capture approved authorization when it is necessary to complete a payment.

Manage tokens

Retrieve, update, and disable tokens you stored with Adyen.

Create and use tokens with the Sessions flow

Set parameters to flag transactions

Enable the webhook

Create a token

Save payment details for one-off payments

Pay with a token

Test and go live

See also

Next steps