> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://docs-dev.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://docs-dev.truemed.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-dev.truemed.com/_mcp/server.

# Update Payment Token

POST https://dev-api.truemed.com/api/v1/payment_tokens/{payment_token}/update
Content-Type: application/json

Endpoint allowing your customers to update their payment method(s) and/or requalify
after a cart change.

## Overview

The `update_payment_token` endpoint is available for partners to call when customers
change the items in their subscription or when they want to update their card(s) on
file.

If `update_card_info=False` and only the `order_items` are being updated, the user
**may or may not need to retake the tele-health survey** depending on a variety of
factors. The `next_action` field in the response body will indicate what the customer
must do next, and a `redirect_url` will be provided if the customer needs to take action.

If you call this endpoint and the `next_action` is not `None`, and a `redirect_url` is
present, we don't guarantee you can invoke
[`create_payment_session`](/v-1/api-reference/payment-sessions/create-payment-session) with the `payment_token` until the user
has completed the action and you've received the
[`payment_token_updated`](/v-1/api-reference/payment-tokens/payment-token-updated-webhook) webhook.

The customer must be in the flow when calling this endpoint, typically from within a
subscription management dashboard.

**Primary Use Cases for this Endpoint:**

* Allowing customers to update their card(s) on file with Truemed
* Ensuring that the user is still eligible to use their HSA/FSA after a cart/subscription
  change.
  * If the customer must requalify by retaking the tele-health survey, the `next_action`
    will be `HealthSurvey`, which can be taken by redirecting the customer to the
    `redirect_url`.
* Changing the email address for a customer's token after the customer changes their email with you.

All subscription related fields here are to enhance the customer experience, a dedicated
subscription management system is needed on the partner's side.

The diagram below outlines the customer flow when using this endpoint:

Partner invokes `update_payment_token` triggered by a customer action. The customer is either updating their payment method(s) or has made a change to the items in their subscription.

The partner redirects the customer to the `redirect_url` if `next_action` is not `None`. The customer completes the required action on Truemed's site.

The customer is redirected to the `success_url` upon completion of the next action on Truemed's site.

Truemed issues a [`payment_token_updated`](/v-1/api-reference/payment-tokens/payment-token-updated-webhook) webhook indicating that the `payment_token` has been updated.

```mermaid
sequenceDiagram
    participant User
    participant Partner
    participant Truemed

    User->>Partner: Update payment method or cart
    Partner->>Truemed: update_payment_token request
    Truemed-->>Partner: redirect_url response
    Partner-->>User: Redirect to redirect_url (if needed)
    User->>Truemed: Complete survey or update card
    Note over User: User eligible or card updated
    Truemed->>Partner: payment_token_updated webhook
    Truemed-->>User: Redirect to success_url
```

The webhook/callback is invoked at the same time the user is being redirected
to the `success_url` - we don't guarantee that it will be called before the redirect.

## Updating the Customer's Email

When a customer changes their email address with you, send the new address in `customer_email`.
Truemed sends receipts and Letter of Medical Necessity (LMN) notifications for this token to that
address from then on, and returns it as `customer_email` on the token.

* Verify that the new address belongs to the same customer before you send it. Truemed does not
  verify it.
* This is the only way to change the token's email. `create_payment_session` ignores
  `customer_email` when the request includes `payment_token`.
* The change applies to this token only. The customer's Truemed account and dashboard login do not
  change. To change their login email, the customer contacts Truemed Support.
* A request that sends only `customer_email` returns `next_action` `None` and no `redirect_url`.

## Request Notes

* **update\_card\_info** (Optional): boolean - Indicates if this request is to update the
  card(s) on file.
  * If set to `True`, the response will always include `redirect_url` so the user can
    update their payment method(s) on file with Truemed.
* **order\_items** (Optional): An array of `order_item` objects, each with the following
  fields:
  * **name** (Required): string - the name of the item.
  * **sku** (Required): sku - the SKU or id for this product.
  * **NOTES**: This should only be supplied when the user is changing the items associated
    with a given subscription
* **success\_url** (Required): Where to redirect the user to after the customer successfully
  completes the tele-health survey and/or updates their payment method(s).
  * This is often used to display a confirmation screen, or similar
* **failure\_url** (Required): When the user opts to not complete the tele-health survey or
  selects "cancel" during the process, or when the user is ineligible to spend HSA/FSA funds
  on the items in the request.
  * We attempt to recover from incorrect CVV, or other card detail errors by prompting the
    user for retry
* **use\_iframe** (Optional): Optional query parameter that can be used to modify the
  response's `redirect_url` so it can be used and communicated with in an iframe.
* **customer\_email** (Optional): string - The customer's new email address for this token. See
  [Updating the Customer's Email](#updating-the-customers-email).
* **metadata** (Optional): Any additional data supplied by the partner. This will be echoed
  back in the `payment_token_updated` webhook after the `update_payment_token` flow is
  complete.
  * **Important**: This must be a string. If you want to include JSON, encode it as a string.
  * **Important**: DO NOT INCLUDE sensitive information in this field.

## iFrame Support

If `use_iframe` is set to `true`, `redirect_url` will be iframe-compatible. When the customer
finishes, the iframe posts one completion message to your page:

```json
{ "success": true, "redirectUrl": "https://example.com/success" }
```

`redirectUrl` echoes the `success_url` or `failure_url` from your request, matching `success`. See
the [Embedded Checkout guide](/v-1/guides/setup/api/payment-sessions/i-frame-payment-session) for how to
render the flow, validate the message's origin, and handle it.

## Response Notes

### Success Case

**HTTP Status: 200:**

* **next\_action**: The action the customer must take. Can be one of the following:
  * `UpdatePaymentMethod`: Customer must enter a new payment method.
  * `HealthSurvey`: Customer must take the health survey
  * `None`: There is no other action needed at this time.
* **redirect\_url**: Contains a URI through which the customer can complete the
  `payment_token`. If `next_action=None`, this field won't be present.

### Bad Request

**HTTP Status: 400**

If a field is missing or the request otherwise can't be processed, we'll return a 400 with
the following fields:

* **error**: Can be one of:
  * `MissingField`: One of the required fields is not present in the request
  * `IdempotencyViolation`: An `idempotency_key` was reused with different request parameters
  * `ServerError`: There was an internal server error.
    * Requests can be retried as long as the `idempotency_key` is the same.
  * `InvalidToken`: The requested token was not found
  * `IneligibleItemAdded`: A new item is ineligible for HSA/FSA spend. Can be returned when
    requesting to update the items associated with a customer's `payment_token`
* **message**: Indication of one of the following:
  * Which field was missing
  * Details on how the total amount was invalid

Reference: https://docs-dev.truemed.com/api-reference/payment-tokens/update-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

### Path parameters

- `payment_token` (string, required) — The payment token to update

### Body (application/json)

This endpoint expects an UpdatePaymentTokenRequest.

- `failure_url` (string, required) — Where Truemed sends the customer when they opt out of HSA/FSA, do not qualify in the survey, or cancel a payment method update. In an iframe, Truemed returns this URL in the completion message instead of navigating.
- `success_url` (string, required) — Where Truemed should redirect the customer after successfully completing the next action
- `customer_email` (string, optional, nullable) — The customer's new email address. Verify that it belongs to the same customer before you send it. Truemed sends receipts and Letter of Medical Necessity (LMN) notifications for this token to this email from now on. The customer's Truemed account and dashboard login do not change.
- `metadata` (string, optional, nullable) — Merchants can use this free-form field to store extra information with the payment token
- `order_items` (list of UpdatedOrderItemsRequest, optional, nullable) — Updated list of items for this subscription. Required when `renew_eligibility` is true, or when none of `update_card_info`, `metadata` or `customer_email` is set, unless this sales channel is configured for full-catalog qualification. A full-catalog channel needs at least one of `update_card_info`, `metadata`, `customer_email`, `order_items` or `renew_eligibility`. On a full-catalog channel, eligibility is checked against the whole catalog only when `renew_eligibility` is true, and these items do not narrow it.
- `renew_eligibility` (boolean, optional, default: false) — Set to true to ask the customer to requalify. The response is `TakeHealthSurvey` when the customer's LMN is missing, rejected, expired, or expires within 30 days, and `None` otherwise. When the token has no backup card and an item needs one, the response is `UpdatePaymentMethod` instead. The items are `order_items`, or the whole catalog on a full-catalog channel. Use lmn_expires_at from Retrieve or List Payment Token responses or the Payment Token Updated Webhook payload to identify upcoming expirations. On a full-catalog channel, this is the only update that can return a survey.
- `update_card_info` (boolean, optional, default: false) — Set to true to allow the Truemed checkout flow to update the user's card information
- `use_iframe` (boolean, optional, default: false) — If true, the customer should be redirected to the `redirect_url` using an iframe.

## Response

### 200

Successful response

- `next_action` (enum, required) — Next action required for this payment token, if any.
  - Allowed values: `UpdatePaymentMethod`, `TakeHealthSurvey`, `None`
- `redirect_url` (string, required, nullable) — A URI through which the customer can correct the payment_token.

## Errors

### 400 Bad Request Error

Bad Request

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

### 404 Not Found Error

Not Found

- `error` (enum, required)
  - Allowed values: `InvalidToken`, `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

### UpdatedOrderItemsRequest

- `name` (string, required) — The name of the order item
- `sku` (string, required) — The SKU of the item

## Examples

**Request**

```json
{
  "failure_url": "string",
  "success_url": "string"
}
```

**Response**

```json
{
  "next_action": "UpdatePaymentMethod",
  "redirect_url": "string"
}
```

**SDK Code**

```python
import requests

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

payload = {
    "failure_url": "string",
    "success_url": "string"
}
headers = {
    "x-truemed-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://dev-api.truemed.com/api/v1/payment_tokens/payment_token/update';
const options = {
  method: 'POST',
  headers: {'x-truemed-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"failure_url":"string","success_url":"string"}'
};

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