Manage Tokens

After creating tokens, you'll need to manage them throughout their lifecycle. This guide covers how to list, retrieve, update, and delete tokens for your shoppers.

List Tokens for a Shopper

Retrieve all stored payment methods for a specific customer. This is useful for displaying saved cards in your checkout or account settings.

curl -X GET "https://api.plexypay.com/v2/tokens?shopper_id=shopper_123456" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "tok_card_visa_4242",
      "type": "card",
      "shopper_id": "shopper_123456",
      "recurring_processing_model": "CardOnFile",
      "card": {
        "brand": "visa",
        "last4": "4242",
        "exp_month": 12,
        "exp_year": 2028,
        "funding": "credit",
        "issuer_country": "US"
      },
      "billing_address": {
        "line1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94102",
        "country": "US"
      },
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-01-15T10:30:00Z"
    },
    {
      "id": "tok_card_mastercard_5678",
      "type": "card",
      "shopper_id": "shopper_123456",
      "recurring_processing_model": "Subscription",
      "card": {
        "brand": "mastercard",
        "last4": "5678",
        "exp_month": 6,
        "exp_year": 2027,
        "funding": "debit",
        "issuer_country": "KZ"
      },
      "created_at": "2026-02-20T14:45:00Z",
      "updated_at": "2026-02-20T14:45:00Z"
    }
  ],
  "has_more": false
}

Filtering Options

You can filter tokens by various criteria:

# Filter by recurring model
curl -X GET "https://api.plexypay.com/v2/tokens?shopper_id=shopper_123456&recurring_processing_model=Subscription" \
  -H "x-api-key: YOUR_API_KEY"

# Filter by card brand
curl -X GET "https://api.plexypay.com/v2/tokens?shopper_id=shopper_123456&card_brand=visa" \
  -H "x-api-key: YOUR_API_KEY"

# Pagination
curl -X GET "https://api.plexypay.com/v2/tokens?shopper_id=shopper_123456&limit=10&starting_after=tok_card_visa_4242" \
  -H "x-api-key: YOUR_API_KEY"

Retrieve a Single Token

Get detailed information about a specific token.

curl -X GET https://api.plexypay.com/v2/tokens/tok_card_visa_4242 \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "id": "tok_card_visa_4242",
  "type": "card",
  "shopper_id": "shopper_123456",
  "recurring_processing_model": "CardOnFile",
  "card": {
    "brand": "visa",
    "last4": "4242",
    "exp_month": 12,
    "exp_year": 2028,
    "funding": "credit",
    "issuer_country": "US",
    "issuer_name": "Chase"
  },
  "billing_address": {
    "line1": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "US"
  },
  "metadata": {
    "nickname": "Personal Visa"
  },
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z"
}

Update Token Details

You can update certain token attributes like billing address and metadata. Card details themselves cannot be modified - you would need to create a new token.

curl -X PATCH https://api.plexypay.com/v2/tokens/tok_card_visa_4242 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "billing_address": {
      "line1": "456 New Street",
      "line2": "Apt 7B",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "US"
    },
    "metadata": {
      "nickname": "Work Card",
      "is_default": true
    }
  }'

Response

{
  "id": "tok_card_visa_4242",
  "type": "card",
  "shopper_id": "shopper_123456",
  "recurring_processing_model": "CardOnFile",
  "card": {
    "brand": "visa",
    "last4": "4242",
    "exp_month": 12,
    "exp_year": 2028,
    "funding": "credit"
  },
  "billing_address": {
    "line1": "456 New Street",
    "line2": "Apt 7B",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001",
    "country": "US"
  },
  "metadata": {
    "nickname": "Work Card",
    "is_default": true
  },
  "updated_at": "2026-03-25T16:00:00Z"
}

Updatable Fields

Field	Description
`billing_address`	Customer's billing address
`metadata`	Custom key-value pairs (up to 50 keys)

To update card details (number, expiry, CVC), create a new token and delete the old one. Card networks may automatically update expiry dates through Account Updater if enabled.

Delete a Token

Remove a stored payment method. This is typically done when a customer removes a card from their account.

curl -X DELETE https://api.plexypay.com/v2/tokens/tok_card_visa_4242 \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "id": "tok_card_visa_4242",
  "deleted": true
}

Deleting a token is permanent and cannot be undone. Any active subscriptions or scheduled payments using this token will fail. Ensure you have confirmation flows in your application before deleting customer payment methods.

Disable a Token

Instead of permanently deleting a token, you can disable it. This prevents the token from being used for new payments while preserving the record.

curl -X POST https://api.plexypay.com/v2/tokens/tok_card_visa_4242/disable \
  -H "x-api-key: YOUR_API_KEY"

Re-enable a Token

You can re-enable a disabled token if needed.

curl -X POST https://api.plexypay.com/v2/tokens/tok_card_visa_4242/enable \
  -H "x-api-key: YOUR_API_KEY"

Managing Tokens in the Plexy Dashboard

You can also manage tokens directly in the Plexy Dashboard:

Go to Customers in the sidebar and search for the shopper.

Click on the customer to see their stored payment methods.

From here you can:

View token details and transaction history
Update billing address
Disable or delete tokens
See which subscriptions are linked to each token

Check Token Validity

Before attempting a payment, you can verify that a token is still valid.

curl -X POST https://api.plexypay.com/v2/tokens/tok_card_visa_4242/verify \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "token_id": "tok_card_visa_4242",
  "valid": true,
  "card": {
    "brand": "visa",
    "last4": "4242",
    "exp_month": 12,
    "exp_year": 2028
  },
  "verified_at": "2026-03-25T16:30:00Z"
}

Token verification performs a zero-amount authorization. Some card issuers may show a temporary pending charge to the cardholder. Use this sparingly and consider caching results.

Monitor Expiring Tokens

Proactively identify tokens that will expire soon to request updated payment methods from customers.

# Get tokens expiring in the next 30 days
curl -X GET "https://api.plexypay.com/v2/tokens?expires_before=2026-04-25" \
  -H "x-api-key: YOUR_API_KEY"

API Reference

List Tokens Parameters

Parameter	Type	Description
`shopper_id`	string	Filter by customer (required)
`recurring_processing_model`	string	Filter by token type
`card_brand`	string	Filter by card brand (visa, mastercard, etc.)
`status`	string	Filter by status (`active`, `disabled`)
`expires_before`	string	Filter tokens expiring before date (YYYY-MM-DD)
`limit`	integer	Number of results (1-100, default 10)
`starting_after`	string	Cursor for pagination

Update Token Parameters

Parameter	Type	Description
`billing_address`	object	Customer billing address
`billing_address.line1`	string	Street address
`billing_address.line2`	string	Apartment, suite, etc.
`billing_address.city`	string	City
`billing_address.state`	string	State or province
`billing_address.postal_code`	string	ZIP or postal code
`billing_address.country`	string	Two-letter country code
`metadata`	object	Custom key-value pairs

Error Handling

curl https://api.plexypay.com/v2/tokens/tok_invalid \
  -H "x-api-key: YOUR_API_KEY"

If the request fails, the API returns an error object with a code field. Common error codes include token_not_found, token_disabled, and unauthorized.

Best Practices

Display tokens clearly - Show card brand, last 4 digits, and expiry to help customers identify their cards
Handle disabled tokens - Check token status before displaying in checkout
Monitor expiration - Set up automated reminders for expiring cards
Confirm deletion - Always confirm with the user before deleting a payment method
Use metadata wisely - Store nicknames or default flags to improve UX
Enable Account Updater - Automatically update card details when issuers reissue cards

Next Steps

Forward Payment Details - Share tokens with third-party providers
Account Management - Automatic card updates and retry logic

Manage Tokens

On this page