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_tokenis provisioned usingcreate_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_tokenis provisioned usingcreate_payment_token - A customer’s letter of medical necessity is rejected, on sales channels configured to provision
a token anyway. The
payment_tokenis still provisioned so the outcome can be matched back to theprovision_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: thepayment_tokenreturned to the partner by Truemed in response to acreate_payment_sessionrequest whentokenizewas set toTruepayment_session_id: (Optional) theidof thepayment_sessionreturned bycreate_payment_session- This is used if the
payment_tokenwas provisioned as part of acreate_payment_sessionwithtokenize=true.
- This is used if the
failed_payment_session_id: (Optional) theidreturned to the partner by Truemed in response to acreate_payment_sessionrequest- Only present if the
payment_tokenwas used increate_payment_sessionand failed to be charged as outlined in the failure cases in the Subscriptions Guide.
- Only present if the
provision_token_request_id: (Optional)- Present when provisioning/updating a
payment_tokenwith a call tocreate_payment_tokenorupdate_payment_token
- Present when provisioning/updating a
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_sessionreturns astatusdescribing 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.
- Sent on every
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
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.
Optional ISO 8601 formatted date when the LMN expires (inclusive, UTC).
Response
Webhook received successfully (HTTP 204 No Content)