> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://developers.truemed.com/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.truemed.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.truemed.com/_mcp/server.

# List Payment Tokens

GET https://dev-api.truemed.com/api/v1/payment_tokens

Lists all payment tokens created with the [`create_payment_token`](/api-reference/payment-tokens/create-payment-token)
and [`create_payment_session`](/api-reference/payment-sessions/create-payment-session) endpoints.

This endpoint returns a paginated view of all payment tokens
associated with the API key used in the request header, sorted by their `created_at`
date in descending order. Optional search fields are provided to aid in finding the
token or tokens associated with a given user.

Reference: https://developers.truemed.com/api-reference/payment-tokens/list-payment-token

## Authentication

- `x-truemed-api-key` header (required) — Sales channel API key for merchant server-to-server authentication

## Servers

- `https://dev-api.truemed.com` (Development server, default)
- `https://api.truemed.com` (Production server)

## Request

### Query parameters

- `page` (integer, optional) — Optional field indicating which page to access. Defaults to 1.
- `page_size` (integer, optional) — Optional field indicating the number of records per page. Defaults to 30.
- `email` (string, optional) — The email to search for. Partial matches supported, using 'includes' semantics.
- `name` (string, optional) — The name to search for. Partial matches supported, using 'includes' semantics.
- `card_expires_before` (string, optional) — Filter payment tokens with cards expiring on or before this month (YYYY-MM format, e.g., '2024-06')
- `lmn_expires_before` (date, optional) — Filter payment tokens whose `lmn_expires_at` is on or before this date (YYYY-MM-DD format, e.g., '2024-06-15'), including tokens whose LMN has already expired.

## Response

### 200

Successful response

- `payment_tokens` (list of PaymentTokenResponse, required) — An array of `payment_token` objects.
- `pagination` (PaginationBody, optional, nullable) — A pagination object with information about the current page, page size, total count, and last page.

## Errors

### 400 Bad Request Error

Bad Request

- `error` (enum, required)
  - Allowed values: `TotalAmountInvalid`, `ValidationError`
- `message` (string, required)

### 404 Not Found Error

Not Found

- `error` (enum, required)
  - Allowed values: `NotFound`
- `message` (string, required)

### 405 Method Not Allowed Error

Method Not Allowed

- `error` (enum, required)
  - Allowed values: `MethodNotAllowed`
- `message` (string, required)

### 500 Internal Server Error

Internal Server Error

- `error` (enum, required)
  - Allowed values: `ServerError`
- `message` (string, required)

### 501 Not Implemented Error

Not Implemented

- `error` (enum, required)
  - Allowed values: `NotImplemented`
- `message` (string, required)

## Types

### PaymentTokenResponse

- `created_at` (string, required) — ISO 8601 formatted date and time the `payment_token` was created at.
- `customer_email` (string, required) — The email address for the customer associated with this `payment_token`.
- `customer_name` (string, required) — The first and last name of the customer associated with this `payment_token`.
- `payment_token` (string, required) — The payment token identifier.
- `lmn_expires_at` (date, optional, nullable) — ISO 8601 formatted date when this payment token's HSA/FSA coverage ends (inclusive, UTC). Counts letters earned on the token's own sessions and letters its customer earned on this sales channel, matching the date the Payment Token Updated webhook reports for the same token. Null if the customer holds no verified LMN. Prompt the customer to requalify before this date.
- `payment_methods` (list of PaymentMethodResponse, optional, nullable) — An optional array of payment_method objects.

### PaginationBody

- `count` (integer, required) — The total number of items associated with the provided API key.
- `current_page` (integer, required) — The page requested. If none was provided, this will default to 1.
- `last_page` (integer, required) — The last page. You can iterate through pages by providing integers up to last_page in the page parameter.
- `page_size` (integer, required) — The number of items per page applied to this response.

### PaymentMethodResponse

- `expiration` (string, optional, nullable) — A MM/YYYY formatted string specifying the month and year the card on file will expire.
- `last4` (string, optional, nullable) — The last 4 digits of the CC number associated with this payment method.
- `payment_method_updated_at` (string, optional, nullable) — ISO 8601 formatted DateTime object that represents the date and time the `payment_method` was last updated by the customer.

## Examples

**Response**

```json
{
  "payment_tokens": [
    {
      "created_at": "string",
      "customer_email": "string",
      "customer_name": "string",
      "payment_token": "string",
      "lmn_expires_at": "2023-01-15",
      "payment_methods": [
        {
          "expiration": "string",
          "last4": "string",
          "payment_method_updated_at": "string"
        }
      ]
    }
  ],
  "pagination": {
    "count": 1,
    "current_page": 1,
    "last_page": 1,
    "page_size": 1
  }
}
```

**SDK Code**

```python
import requests

url = "https://dev-api.truemed.com/api/v1/payment_tokens"

headers = {"x-truemed-api-key": "<apiKey>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://dev-api.truemed.com/api/v1/payment_tokens';
const options = {method: 'GET', headers: {'x-truemed-api-key': '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```