> 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.

# 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`](/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`](/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`.

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`](/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.

## 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.
* **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](/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://developers.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
- `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 neither `update_card_info` nor `metadata` 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`, `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);
}
```