Create tokens

Learn how to create tokens with your online payments integration.

To tokenize your shopper's payment details, you need to include additional fields when you make an API request to create a payment session or make a payment. When the details are successfully tokenized, you receive a webhook that contains the token you can use for subsequent payments.

You can tokenize your shopper's payment details when they pay for a purchase, or with a zero-value auth.

If you already have existing recurring contracts with another payment service provider, you can import the stored payment details to Adyen.

Requirements

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

Requirement	Description
Integration type	An online payments integration.
API credential roles	Make sure that you have the following roles: Checkout webservice role Merchant Recurring role Only if you want to use the /storedPaymentMethods endpoint: API tokenise payment details
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 unscheduled card-on-file payments 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 online payments 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 can apply to you, depending on your tokenization implementation.

How it works

To store your shoppers payment details and get a token that you can use for future payments:

Enable the Recurring tokens life cycle events webhook.
Before the shopper pays on your website or app, ask for their consent to store their payment details for future payments. You must inform the shopper about the payment schedule and the amount that you will charge to reduce the risk of chargebacks.
In your payment request, include tokenization parameters to create a token with the shopper's payment details. Multiple endpoints support tokenizing your shopper's payment details:
- POST /sessions: the simplest way to create tokens. The payment session contains all the information needed to collect payment details securely. This reduces your PCI scope to the simplest level (SAQ A).
- POST /payments: lets you have more control over the checkout experience, and lets you handle more complex payment flows where you need to manage the state and data flow yourself.
- POST /storedPaymentMethods: Only available on Checkout API v70 and later. Lets you create tokens without an authorization. We recommend to create tokens with an authorization, to make sure the tokens you create are linked to active, chargeable accounts.
After the transaction is authorized, get the unique identifier and other information about the token from the recurring.token.created webhook.

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:

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

type: the type of webhook. 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.

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 endpoint you are using:

Import stored payment details

If you have existing recurring contracts with another payment service provider, you can migrate and import stored payment details to Adyen. When you import the data, you do not need to collect your shoppers' payment details again to create a token.

When the stored payment details are successfully migrated, you receive an output file. From this file you can get the parameters that you need to use the tokens in future payments.

Test and go live

Follow our testing guide for tokenization and make sure that you receive the recurring.token.created webhook when you store payment details.

When you are ready to go live:

Enable the Recurring tokens life cycle events webhooks in your live Customer Area.
Follow the Tokenization end-to-end testing checklist.

Next steps

Make token payments

Make one-click, subscription, or unscheduled card-on-file payments with the tokens you created.

Manage tokens

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