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

# Payment Token Updated Webhook

POST 

The partner is required to implement an endpoint that Truemed requests to inform the partner
of updates made to payment tokens which back customer subscriptions.

The `payment_token_updated` webhook is invoked when:

1. A `payment_token` is provisioned using [`create_payment_session`](/api-reference/payment-sessions/create-payment-session)
2. A customer updates their payment token due to one of the failure cases outlined in the
   subscriptions guide, or as part of [`update_payment_token`](/api-reference/payment-tokens/update-payment-token)
3. A `payment_token` is provisioned using [`create_payment_token`](/api-reference/payment-tokens/create-payment-token)
4. A customer's letter of medical necessity is rejected, on sales channels configured to provision
   a token anyway. The `payment_token` is still provisioned so the outcome can be matched back to
   the `provision_token_request_id`, but it carries no HSA/FSA eligibility: charges against it
   route entirely to the credit/debit card. Ask your Truemed contact to enable this if you would
   rather take the order on the customer's backup card than lose it.

The request body includes the `payment_token`, and one of 3 optional IDs mapping back to the
originating entity (`payment_session_id`, `failed_payment_session_id`, or
`provision_token_request_id`).

Once you receive this webhook, the `payment_token` can successfully be used in subsequent
calls to [`create_payment_session`](/api-reference/payment-sessions/create-payment-session).

**Authentication**: Partners should verify the request comes from Truemed by checking that
the API key is present in the `x-truemed-api-key` HTTP header.

## Request Notes

- `payment_token`: the `payment_token` returned to the partner by Truemed in response to a
  [`create_payment_session`](/api-reference/payment-sessions/create-payment-session) request
  when `tokenize` was set to `True`
- `payment_session_id`: **(Optional)** the `id` of the `payment_session` returned by
  `create_payment_session`
  - This is used if the `payment_token` was provisioned as part of a `create_payment_session`
    with `tokenize=true`.
- `failed_payment_session_id`: **(Optional)** the `id` returned to the partner by Truemed in
  response to a `create_payment_session` request
  - Only present if the `payment_token` was used in [`create_payment_session`](/api-reference/payment-sessions/create-payment-session)
    and failed to be charged as outlined in the failure cases in the [Subscriptions Guide](/guides/subscriptions/overview).
- `provision_token_request_id`: **(Optional)**
  - Present when provisioning/updating a `payment_token` with a call to
    [`create_payment_token`](/api-reference/payment-tokens/create-payment-token) or
    [`update_payment_token`](/api-reference/payment-tokens/update-payment-token)
- `eligibility_status`: where the customer's clinical eligibility stands at the moment the webhook
  is sent
  - Sent on every `payment_token_updated`, including the card-update and requalification ones, so it
    always describes the customer's current standing rather than only the change that prompted the
    webhook.
  - This is a clinical status, not a payment one. `create_payment_session` returns a `status`
    describing the payment; the two are different vocabularies and the names are kept apart on purpose.
  - It answers *whether* the customer is covered. For *which* of your items that covers, and until
    when, use the eligibility read.

## Response Notes

### Success Case

HTTP Status: `204`

The partner does not need to include any content in the body, but MUST respond with `204`.

### Failure Case

Truemed will retry the requests to your backend with backoff for up to 7 days

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

## Request

### Payload

- `payment_token` (string, required) — The payment token identifier
- `eligibility_status` (enum, optional, nullable) — Where this customer's clinical eligibility stands at the moment this webhook is sent. Named apart from `status` on a payment session, which is that payment's status rather than the customer's. For which items that covers, and until when, use the eligibility read. One of: - `approved` — A verified, unexpired letter stands for this customer. - `pending` — A survey is with a clinician; the outcome is not decided yet. - `expired` — The letter that covered this customer has lapsed and not been renewed. - `rejected` — A clinician reviewed this customer's most recent survey and declined it. - `never_requested` — No letter has ever been requested for this customer here.
  - Allowed values: `approved`, `pending`, `expired`, `rejected`, `never_requested`
- `failed_payment_session_id` (string, optional, nullable) — Optional payment session ID that failed, triggering token update
- `lmn_expires_at` (date, optional, nullable) — Optional ISO 8601 formatted date when the LMN expires (inclusive, UTC).
- `metadata` (string, optional, nullable) — Optional metadata associated with the payment token
- `payment_methods` (list of PaymentMethodResponse, optional, nullable) — Optional list of available payment methods for the token
- `payment_session_id` (string, optional, nullable) — Optional payment session ID associated with the token update
- `provision_token_request_id` (string, optional, nullable) — Optional provision token request ID

## Types

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