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

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