Subscriptions

Create a Subscription (Existing Subscriber)

To enable an existing subscriber to qualify and store their payment method with Truemed, partner backends should create a payment_token and redirect the customer to Truemed’s qualification flow via the redirect_url included in the response to create_payment_token. The customer needs to be present during the flow to store their payment method for future use.

The order of operations is as follows:

1. Create a payment_token

Call create_payment_token to begin the process of provisioning a token that can be used for subsequent charges via the create_payment_session endpoint.

  • In the request, an optional metadata string can be provided to track/reference this session later (e.g. customer ID, subscription plan, etc.). Metadata provided on creation will be echoed back via the payment_token_updated webhook, and is available via the retrieve_provision_token_request endpoint.

2. Redirect the user to the provided redirect_url

Redirect the user to the provided redirect_url and store the provision_token_request_id which can be used to determine the status of the payment_token being provisioned.

No need to poll for status

There is no need to poll for the status via our retrieve_provision_token_request endpoint as the status will be communicated via the payment_token_updated webhook.

The full response in case of success contains the following:

  • HTTP Status Code: 200
  • provision_token_request_id: A unique identifier for the subscription setup request.
    • This ID should be associated with your internal notion of user, so you can refer back to it later when a payment_token is provisioned.
  • redirect_url: Send the customer to this URL to initiate Truemed’s HSA/FSA eligibility survey and payment setup. The user will return to the success_url you provided once checkout is complete.

In the case of failure, Truemed will provide an error enum and a message outlining the error — these are particularly useful during development.

3. User completes the Truemed survey and stores payment details

The customer will complete the Truemed health survey and provide their payment information.

4. User is redirected back to the success_url

User is redirected back to the success_url provided in the call to create_payment_token.

  • NOTE: The user will only be redirected to the failure_url provided if they click “Cancel” while on the Truemed survey or checkout pages.
  • The user should be shown a “Thank You” or “Payment Method Stored Successfully” message.

Wait for the payment_token_updated webhook

IMPORTANT: Note that it is possible a token is never provisioned. Partners must wait for the payment_token_updated webhook containing a valid token before using it for charges.

At this point, the user is no longer present and has been told their payment method has been stored successfully. The following webhooks will be issued asynchronously:

payment_token_updated webhook

  • This will include the payment_token and also the provision_token_request_id that was returned in Step (1) above. Partners should use this data to associate with the end-customer in partner subscription-management systems.

In the rare case that the user successfully completes the survey, but a Letter-of-Medical-Necessity is not issued, this webhook will never be issued as a valid payment_token was never successfully provisioned.