--- title: "Manage tokens" description: "Learn how to manage tokens you stored with Adyen." url: "https://docs.adyen.com/online-payments/tokenization/managing-tokens" source_url: "https://docs.adyen.com/online-payments/tokenization/managing-tokens.md" canonical: "https://docs.adyen.com/online-payments/tokenization/managing-tokens" last_modified: "2026-03-12T15:39:00+01:00" language: "en" --- # Manage tokens Learn how to manage tokens you stored with Adyen. [View source](/online-payments/tokenization/managing-tokens.md) When you store your shopper's payment details with Adyen, you can use our [Checkout API](https://docs.adyen.com/api-explorer/Checkout/latest/overview) to manage the lifecycle of your tokens to ensure that the stored payment details remain up-to-date, so that you can continue to offer your shopper's a smooth payment experiences. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | An [online payments integration](/online-payments/build-your-integration/). | | **[API credential roles](/development-resources/api-credentials/roles/)** | Make sure that you have the following role(s):- **Checkout webservice role** - **Merchant Recurring role** | | **[Webhooks](/development-resources/webhooks)** | Subscribe to the [**Recurring tokens life cycle events** webhook](/development-resources/webhooks/webhook-types/#other-webhooks). | | **Setup steps** | Before you begin:- Follow our guides to [create tokens](/online-payments). | ## How it works After you have [created tokens](/online-payments/tokenization/create-tokens), you can use the Checkout API to: * [Get a list of the shopper's stored payment details](#list-stored-details). * [Update stored payment details](#update-stored-details). * [Delete stored payment details](#delete-stored-details). When a token is updated, or deleted, you get notified with the [Tokenization webhooks](https://docs.adyen.com/api-explorer/Tokenization-webhooks/latest/overview). ## List stored payment details To see all the payment details stored for a shopper, make a **GET** [/storedPaymentMethods](https://docs.adyen.com/api-explorer/Checkout/latest/get/storedPaymentMethods) request including the following query parameters: | Query parameter | Description | | ------------------ | --------------------------------------- | | `merchantAccount` | Your merchant account name. | | `shopperReference` | Your unique identifier for the shopper. | **Example request to get a list stored payment details** ```txt https://checkout-test.adyen.com/v71/storedPaymentMethods/?merchantAccount=YOUR_MERCHANT_ACCOUNT/&shopperReference=YOUR_UNIQUE_SHOPPER_REFERENCE ``` The [storedPaymentMethods](https://docs.adyen.com/api-explorer/Checkout/latest/get/storedPaymentMethods#responses-200-storedPaymentMethods) array in the response includes: | Parameter | Description | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | The [storedPaymentMethodId](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-StoredPaymentMethodDetails-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. | **Example response with stored payment details** ```json { "storedPaymentMethods": [ { "brand": "visa", "expiryMonth": "10", "expiryYear": "2020", "holderName": "SHOPPER_NAME", "id": "8415890871952836", "recurringProcessingModel":"Subscription", ... } ] } ``` ## Update stored details Only applicable for tokens for stored with `recurringProcessingModel`: **CardOnFile**.\ 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](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to discuss your eligibility. You can update the following fields without changing the [storedPaymentMethodId](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-StoredPaymentMethodDetails-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](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request to store new payment details and receive a new identifier. To update the `expiryMonth`, `expiryYear`, `holderName`, or `billingAddress`, make a [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/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](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request including the required fields and `paymentMethod.holderName`: **Example of a request to update the cardholder name** ```json { "merchantAccount": "ADYEN_MERCHANT_ACCOUNT", "shopperReference": "YOUR_UNIQUE_SHOPPER_ID", "reference": "YOUR_UNIQUE_REFERENCE", "amount": { "currency": "GBP", "value": 0 }, "paymentMethod": { "storedPaymentMethodId":"8415890871952836", "holderName": "NEW_SHOPPER_NAME" }, "shopperInteraction": "ContAuth", "recurringProcessingModel": "Subscription" } ``` ### 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](/online-payments/account-updater) you use. * If you are using our [Real Time Account Updater](/online-payments/account-updater/real-time-account-updater#receive-card-updates-in-payment-response), 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](/online-payments/account-updater/batch-account-updater#update-card-details), then you will receive the updated card details in a batch result file. You then need to make a [zero-value transaction](/online-payments/tokenization/create-tokens) 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](/online-payments/tokenization/create-tokens). Alternatively, to find all tokens for a given shopper, you can [list stored payment details](#list-stored-details) and get the `id` from the relevant item in the `storedPaymentMethods` array. To delete the token, make a **DELETE** [/storedPaymentMethods/{storedPaymentMethodId}](https://docs.adyen.com/api-explorer/Checkout/latest/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. | **Example request to delete a token** #### curl ```bash curl -X DELETE 'https://checkout-test.adyen.com/v70/storedPaymentMethods/{storedPaymentMethodId}?merchantAccount={YOUR_MERCHANT_ACCOUNT}&shopperReference={YOUR_SHOPPER_REFERENCE}' \ --header 'X-API-Key: ADYEN_API_KEY' ``` #### Java ```java // Adyen Java API Library v26.3.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.service.checkout.*; // For the live environment, additionally include your liveEndpointUrlPrefix. Client client = new Client("ADYEN_API_KEY", Environment.TEST); // Send the request RecurringApi service = new RecurringApi(client); service.deleteTokenForStoredPaymentDetails("storedPaymentMethodId", "String", "String", null); ``` #### PHP ```php // Adyen PHP API Library v18.2.1 use Adyen\Client; use Adyen\Environment; use Adyen\Service\Checkout\RecurringApi; $client = new Client(); $client->setXApiKey("ADYEN_API_KEY"); // For the live environment, additionally include your liveEndpointUrlPrefix. $client->setEnvironment(Environment::TEST); $requestOptions['queryParams'] = array('shopperReference' => 'string', 'merchantAccount' => 'string'); // Send the request $service = new RecurringApi($client); $service->deleteTokenForStoredPaymentDetails('storedPaymentMethodId', $requestOptions); ``` #### C\# ```cs // Adyen .net API Library v17.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Service.Checkout; // For the live environment, additionally include your liveEndpointUrlPrefix. var config = new Config() { XApiKey = "ADYEN_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Send the request var service = new RecurringService(client); service.DeleteTokenForStoredPaymentDetails("storedPaymentMethodId", shopperReference: "string", merchantAccount: "string"); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v17.3.0 // Require the parts of the module you want to use const { Client, CheckoutAPI } = require('@adyen/api-library'); // Initialize the client object // For the live environment, additionally include your liveEndpointUrlPrefix. const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"}); // Send the request const checkoutAPI = new CheckoutAPI(client); checkoutAPI.RecurringApi.deleteTokenForStoredPaymentDetails("storedPaymentMethodId", "string", "string"); ``` #### Go ```go // Adyen Go API Library v10.4.0 import ( "context" "github.com/adyen/adyen-go-api-library/v9/src/common" "github.com/adyen/adyen-go-api-library/v9/src/adyen" "github.com/adyen/adyen-go-api-library/v9/src/checkout" ) // For the live environment, additionally include your liveEndpointUrlPrefix. client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, }) // Send the request service := client.Checkout() req := service.RecurringApi.DeleteTokenForStoredPaymentDetailsInput("storedPaymentMethodId") req = req.ShopperReference("string").MerchantAccount("string") service.RecurringApi.DeleteTokenForStoredPaymentDetails(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v12.5.1 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_API_KEY" # For the live environment, additionally include your liveEndpointUrlPrefix. adyen.client.platform = "test" # The environment to use library in. query_parameters = { "shopperReference" : "string", "merchantAccount" : "string" } # Send the request adyen.checkout.recurring_api.delete_token_for_stored_payment_details(storedPaymentMethodId="storedPaymentMethodId", query_parameters=query_parameters) ``` #### Ruby ```rb # Adyen Ruby API Library v9.5.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_API_KEY' # For the live environment, additionally include your liveEndpointUrlPrefix. adyen.env = :test # Set to "live" for live environment # Create the request object(s) query_params = { :shopperReference => 'string', :merchantAccount => 'string' } # Send the request adyen.checkout.recurring_api.delete_token_for_stored_payment_details('storedPaymentMethodId', query_params: query_params) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v17.3.0 // Require the parts of the module you want to use import { Client, CheckoutAPI, Types } from "@adyen/api-library"; // Initialize the client object // For the live environment, additionally include your liveEndpointUrlPrefix. const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"}); // Send the request const checkoutAPI = new CheckoutAPI(client); checkoutAPI.RecurringApi.deleteTokenForStoredPaymentDetails("storedPaymentMethodId", "string", "string"); ``` 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 [Tokenization webhooks](https://docs.adyen.com/api-explorer/Tokenization-webhooks/latest/overview). Enable the [Recurring tokens life cycle events](/development-resources/webhooks/webhook-types/#other-webhooks) webhooks in your Customer Area to receive these webhooks. This webhook includes: * `data.storedPaymentMethodId`: the ID of the token that was created, updated, or disabled. * `data.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 type of webhook. The table below lists the possible values. | `type` | Description | | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [recurring.token.created](https://docs.adyen.com/api-explorer/Tokenization-webhooks/latest/post/recurring.token.created) | A new token was created. | | [recurring.token.disabled](https://docs.adyen.com/api-explorer/Tokenization-webhooks/latest/post/recurring.token.disabled) | A token was disabled, this can happen when:- [You delete stored payment details](#delete-stored-details). - A third-party disables the payment details. | | [recurring.token.updated](https://docs.adyen.com/api-explorer/Tokenization-webhooks/latest/post/recurring.token.updated) | The stored details for a token were updated. You can [initiate the update](#update-stored-details), but stored details can also be updated by, for example, [card networks](#updates-from-card-networks). | | [recurring.token.alreadyExisting](https://docs.adyen.com/api-explorer/Tokenization-webhooks/latest/post/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: **Token disabled webhook** ```json { "createdAt": "2024-01-14T18:10:49+01:00", "environment": "test", "type": "recurring.token.disabled", "data": { "merchantAccount": "ADYEN_MERCHANT_ACCOUNT", "shopperReference": "YOUR_SHOPPER_REFERENCE", "storedPaymentMethodId": "M5N7TQ4TG5PFWR50", "type": "visa" }, "eventId": "QBQQ9DLNRHHKGK38" } ``` ## See also * [Checkout API](https://docs.adyen.com/api-explorer/Checkout/latest/overview) * [Account Updater](/online-payments/account-updater)