Payment Token Updated Webhook

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:

A payment_token is provisioned using create_payment_session
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
A payment_token is provisioned using create_payment_token
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.

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 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 and failed to be charged as outlined in the failure cases in the Subscriptions Guide.
provision_token_request_id: (Optional)
- Present when provisioning/updating a payment_token with a call to create_payment_token or 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

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

Payload

The payload of this webhook request is an object.

payment_tokenstringRequired

The payment token identifier

eligibility_statusenum or nullOptional

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.

failed_payment_session_idstring or nullOptional

Optional payment session ID that failed, triggering token update

lmn_expires_atstring or nullOptional

Optional ISO-8601 timestamp of when the LMN expires

metadatastring or nullOptional

Optional metadata associated with the payment token

payment_methodslist of objects or nullOptional

Optional list of available payment methods for the token

payment_session_idstring or nullOptional

Optional payment session ID associated with the token update

provision_token_request_idstring or nullOptional

Optional provision token request ID

Response

204

Webhook received successfully (HTTP 204 No Content)

400

Invalid payload or authentication failure

500

Server error processing webhook