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.

Requirements

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

Requirement	Description
Integration type	An online payments integration using the Sessions flow.
API credential roles	Make sure that you have the following role(s): Checkout webservice role Merchant Recurring role
Webhooks	Subscribe to the Recurring tokens life cycle events webhook.
Limitations	With the /sessions endpoint, you can create tokens for all recurring payment types, but making subsequent subscription or automatic top-ups require using the `/payments` endpoint.
Setup steps	Before you begin: Add the payment methods that support recurring payments in your Customer Area. Set up your Sessions flow integration. 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. Review additional SCA requirements based on business models that may apply to you depending on your tokenization implementation.

How it works

To store payment details of your shoppers:

When the shopper proceeds to pay, ask for their consent to store their payment details for future payments.
In your payment request, include tokenization parameters to create a token with the payment details of your shopper.
For subsequent payments, pay with the token you created to offer a faster checkout experience to your shoppers.
To make subscription, automatic top-up, or non-fixed schedule contract payments, you need to use the /payments endpoint.

When you create a token, you receive a webhook that contains the ID of the token, along with other information about the token.

We strongly recommend that you ask explicit permission from the shopper if you intend to store their payment details. Being transparent about the payment schedule and the charged amount reduces the risk of chargebacks.

Tokenization parameters

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

Enable the webhook

To get updates when a token is created, updated, or disabled, enable the Recurring tokens life cycle events webhook.

This webhook includes:

storedPaymentMethodId: the ID of the token that was created, updated, or disabled.
shopperReference:: your unique shopper reference. Use this to associate the shopper with the token.
eventId: the pspReference for the transaction made to store the shopper's payment details.

type: the event that caused a change in the token status. The table below lists the possible values.

`type`	Description
recurring.token.created	A token was created. To use in future recurring payments, store the `storedPaymentMethodId` together with the `shopperReference`, so that you associate the token with the shopper.
recurring.token.disabled	A token was disabled, this can happen when: You delete stored payment details. A third-party disables the payment details.
recurring.token.updated	The stored details for a token were updated. You can initiate the update, but stored details can also be updated by, for example, card networks.
recurring.token.alreadyExisting	A create or update operation was attempted with details that match an already existing token. The `storedPaymentMethodId` field contains the ID of the existing token.

We recommend that you set up the webhook with all default events.

When you create a token, you receive a recurring.token.created webhook that includes the token that you use for payments with the shopper's stored payment details. Store the token with the shopper reference to associate the token with the shopper.

We are no longer working on the development of the RECURRING_CONTRACT webhook. We strongly recommend to use the new Recurring tokens life cycle events webhook instead, because it keeps you informed of more token lifecycle events. If your integration already uses the RECURRING_CONTRACT webhook, the webhook remains available.

Create a token

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

Pay with a token

Select the type of recurring payment to make:

Test and go live

In your test environment:

Test that you get the Recurring tokens life cycle events webhook.
Store a test token.
Make a test payment with the token.

Before going live:

Enable the Recurring tokens life cycle events 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.