No momento, esta página não está disponível em português
Online-payment icon

Create a token to make recurring payments

Learn how to create and use tokens you stored with Adyen.

      Try it in our API Explorer.
  Postman collection

Implementation examples
  Java Spring
  .NET
  Node.js

You can use tokens for:

  • One-off payments: 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.
  • Subscriptions: a recurring transaction made at regular intervals for a product or a service.
  • Automatic top-ups: contracts that occur on a non-fixed schedule using stored card details. This includes automatic top-ups when the cardholder's balance drops below a certain amount.

Set parameters to flag transactions

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

Parameter Description
recurringProcessingModel When you first create a token, this indicates what type of recurring payment the token is intended for.
For following payments, indicates the type of recurring payment.
shopperInteraction Indicates if you're creating a token or using a previously created token.
shopperReference Your unique reference for the shopper. Minimum length: three characters. Do not include personally identifiable information (PII), such as name or email address.
storePaymentMethod When you first create a token, set to true to store the shopper's payment details.
For following payments, this parameter is not required.
Business model
Initial payment Later payment(s)
recurringProcessingModel shopperInteraction recurringProcessingModel shopperInteraction
One-off payments
SCA can be required depending on regulations and scheme rules
CardOnFile Ecommerce CardOnFile ContAuth
Subscriptions
SCA is required for the initial payment
Subscription Ecommerce Subscription ContAuth
Automatic top-ups and other non-fixed schedule contracts
SCA is required for the initial payment
UnscheduledCardOnFile Ecommerce UnscheduledCardOnFile ContAuth

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.

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.

Import recurring payment details

If you have existing recurring contracts with another payment service provider, you can migrate and import recurring payment details to Adyen. When you import the data, you won't need to collect your shopper's payment details again to create a token.

When the recurring 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.

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:

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.

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

Create a token and pay

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

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.

If you're using one of our client-side solutions, refer to Cards Drop-in pages for Web, iOS, and Android or Component pages for Web, iOS, and Android.

Save payment details for one-off payments

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

Parameter Description
paymentMethod Contains the shopper's payment details.
shopperReference Your unique identifier for the shopper. Minimum length: three characters. Do not include personally identifiable information (PII), such as name or email address.
shopperInteraction Ecommerce
recurringProcessingModel CardOnFile
storePaymentMethod
Checkout API v49 or later
true
amount Contains the value to pay. You can set amount.value to 0 to validate the payment details with a zero-auth transaction before processing payments.

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.

PSD2 regulations may have additional requirements for processing recurring transactions.

Result codes

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

Result code Description Action
Authorised The payment was successful, and the payment details were tokenized. Save the token from the RECURRING_CONTRACT webhook.
Pending The payment is pending, and the payment details haven't been tokenized yet. Wait for the RECURRING_CONTRACT webhook that you get when the payment reaches the Authorised status.
Refused The payment was refused, and the payment details weren't tokenized. Make another payment request to try tokenizing again.

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:

Because the API response doesn't always include the token, we recommend always getting it from the RECURRING_CONTRACT webhook.

Make a one-off payment with saved payment details

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

    If you are using one of 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.

    If you are using an API-only integration, you will need to build the UI for this yourself.

  2. From your server, make a POST /payments request including:

    Parameter Required Description
    paymentMethod.storedPaymentMethodId
    Checkout API v49 or later
    -white_check_mark- The token for the shopper's stored payment details. This is the recurringDetailReference from the response when you created the token.
    shopperReference -white_check_mark- Your unique identifier for the shopper. Must be the same one you included with the request to create the token.
    shopperInteraction -white_check_mark- ContAuth
    recurringProcessingModel -white_check_mark- CardOnFile
    encryptedSecurityCode -white_check_mark- The encrypted card verification code (CVC).
    If you don't want to require the CVC for one-off payments using stored details, you must contact our Support Team to activate the skipCvcForOneClick in your Customer Area.
    Don't store the CVC. Storing it violates PCI compliance rules.

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.

If the payment is successful, you receive resultCode: Authorised.

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

Test and go live

To receive the enable receiving 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.

Próximas etapas