---
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 roles:- **Checkout webservice role**
- **Merchant Recurring role**
- **API tokenise payment details** |
| **[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)
