Checkout icon

Manage tokens

Learn how to manage tokens you stored with Adyen.

  Postman collection

Implementation examples
  Java Spring
  .NET
  Node.js

You can use the Checkout API to:

You can use webhooks to get informed when a token is created, updated, or deleted.

List stored payment details

To see all the payment details stored for a shopper, make a GET /storedPaymentMethods request including the following query parameters:

Query parameter Description
merchantAccount Your merchant account name.
shopperReference Your unique identifier for the shopper.

The storedPaymentMethods array in the response includes:

Parameter Description
id The storedPaymentMethodId value that you need to make payments with the shopper's stored payment details.
supportedRecurringProcessingModels Defines the type of recurring payment that the stored payment details can be used for. Possible values:
  • CardOnFile: The stored payment details can be used to enable one-click payments, or to offer a faster checkout later.
  • UnscheduledCardOnFile: The stored payment details can be used for transactions that occur on a non-fixed schedule and/or have variable amounts.
  • Subscription: The stored payment details can be used for transactions that follow a fixed schedule, for a fixed or variable amount.

Store payment details

We recommend that you store payment details by making a zero-auth transaction, because a successful authorised result code indicates that the payment details were validated by the card scheme.

If you validated a shopper's payment details in a different way, you can store payment details without making a zero-auth transaction.

Requirements:

Make a POST /storedPaymentMethods request including either encrypted or unencrypted payment details.

You get a response that includes the token that you use to make recurring payments in the id field. For example:

If you store tokens on your server, store the id with the shopperReference.

Update stored details

On Checkout API v70 and later, updating stored details with an API request requires additional configuration on our side. Reach out to our Support Team to discuss your eligibility.

You can update the following fields without changing the storedPaymentMethodId of the stored payment details:

Field Description
expiryMonth The expiry month.
expiryYear The expiry year.
holderName The cardholder's name.
billingAddress The cardholder's address.

If the shopper has a new card number, make a /payments request to store new payment details and receive a new identifier.

To update the expiryMonth, expiryYear, holderName, or billingAddress, make a /payments request including:

Parameter Description
amount.value 0
storedPaymentMethodId The token with the stored payment details.
shopperReference Your unique identifier for the shopper.
merchantAccount Your merchant account name.
shopperInteraction Defines the type of shopper interaction that the stored payment details can be used for.
recurringProcessingModel Defines the type of recurring payment that the stored payment details can be used for.
reference The reference to uniquely identify a payment

Also include at least one of the fields you want to update:

Parameter Description
expiryMonth The expiry month.
expiryYear The expiry year.
holderName The cardholder's name.

For example, to update the cardholder name, make a /payments request including the required fields and paymentMethod.holderName:

Updates from card networks

Card networks (for example, Visa and Mastercard) also send updates to your shopper's payment details. The way these updates are handled depends on the Account Updater service you use.

  • If you are using our Real Time Account Updater, you do not have to do anything to handle the updates from the card networks. The card details are automatically updated, and the token remains unchanged.
  • If you are using our Batch Account Updater, then you will receive the updated card details in a batch result file. You then need to make a zero-value transaction with the updated card details.

Delete stored payment details

You can delete a single token by its identifier, which is returned when you create a token. Alternatively, to find all tokens for a given shopper, you can list stored payment details and get the id from the relevant item in the storedPaymentMethods array.

To delete the token, make a DELETE /storedPaymentMethods/{storedPaymentMethodId} request including the following parameters:

Parameter name Parameter type Description
storedPaymentMethodId Path parameter The unique identifier for the token you want to delete.
merchantAccount Query parameter Your merchant account name.
shopperReference Query parameter Your unique identifier for the shopper.

After you delete payment details stored with Adyen, you must also delete any remaining shopper details from your servers.

Receive token lifecycle webhooks

While you manage tokens, you can stay informed of status changes to your tokens with 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 payment 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 new token was created.
    recurring.token.disabled A token was disabled, this can happen when:
    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.

For example, when you delete a token, you get a webhook that looks like the following:

See also