Payment tokens can be created outside of the create_payment_session API call. This is most commonly used to support existing subscription customers, allowing them to move their subscriptions to their HSA/FSA. Use create_payment_session with tokenize=True to create a subscription as part of a checkout flow, such as the first order in a subscription, or free trials.

Overview

This endpoint supports creating a payment_token outside of the create_payment_session flow, and is commonly used to support giving the option to existing subscribers to pay with their HSA/FSA. This endpoint can also be used to “store a payment method with Truemed” inside of a user dashboard. Subscription free-trials are possible with this endpoint, though we recommend using create_payment_session for trials for consistency with the standard checkout experience.

This endpoint returns the ID of a new provision_token_request, NOT a new payment_token. The payment_token itself will be available upon receipt of the payment_token_updated webhook with the corresponding provision_token_request_id. In order to support backfills in the case of unforeseen downtime (a webhook that goes unacknowledged, or is missed), you can also query the status of the provision_token_request directly as outlined in our retrieve_provision_token_request docs.

The diagram below outlines the customer flow when using this endpoint:

Primary Use Cases for this Endpoint:

• Supporting existing customers
  • You may have existing subscriptions customers that want to move their subscription over to their HSA/FSA card. Providing a “use your HSA/FSA via Truemed” button within a subscription management dashboard powered by this endpoint allows you to do that.
• Store payment method with Truemed
  • Allow customers to add an HSA to their account for future use
• Free-trial support (non preferred)
  • Allowing customers to qualify for a given subscription and store their payment info for future use.
  • ⚠️ We recommend using create_payment_session with tokenize=True for free trials as outlined in the main subscription guide to reflect the fact that the customer is “checking out”, though at no-cost.

Request Notes

• success_url (Required): Where to redirect the user to after the customer successfully completes the tele-health survey and their payment method(s) have been stored.
  • This is often used to display a confirmation screen, or similar
• failure_url (Required): When the user opts to not complete the tele-health survey or selects “cancel” during the process, or when the user is ineligible to spend HSA/FSA funds on the items in the request.
  • We attempt to recover from incorrect CVV, or other card detail errors by prompting the user for retry
• customer_state (Optional): The 2-letter ISO 3166-2:US code for a region, without the US- prefix. For example, California should be provided as CA and Rhode Island as RI.
  • If customer_state is provided, the state of residence question in the health survey will be prefilled with the full state name that corresponds to the ISO code.
• metadata (Optional): Will be echoed back in the payment_token_updated webhook and detail endpoint if present.
  • Important: This must be a string. If you want to include JSON, encode it as a string.
  • Important: DO NOT INCLUDE sensitive information in this field.
• use_iframe (Optional): Optional query parameter that can be used to modify the response’s redirect_url so it can be used and communicated with in an iframe.

iFrame Support

If use_iframe is set to true, redirect_url will be iframe-compatible. When the customer finishes, the iframe posts one completion message to your page:

{ "success": true, "redirectUrl": "https://example.com/success" }

redirectUrl echoes the success_url or failure_url from your request, matching success. See the Embedded Checkout guide for how to render the flow, validate the message’s origin, and handle it.

Response Notes

Success Case

HTTP Status: 200:

• provision_token_request_id: A UUID that represents this creation request.
  • This ID is returned along with the provisioned payment_token in the payment_token_updated webhook.
  • You can query the status of this request using the retrieve_provision_token_request endpoint.
• redirect_url: Contains a URI through which the customer can complete the payment_token.

Bad Request

HTTP Status: 400

If a field is missing or the request otherwise can’t be processed, we’ll return a 400 with the following fields:

• error: Can be one of:
  • MissingField: One of the required fields is not present in the request
  • IdempotencyViolation: An idempotency_key was reused with different request parameters or the customer email specified in the request already has a payment token provisioned. Check to see if a payment_token_updated webhook was already received for this customer. To update, use the update_payment_token endpoint.
  • WaitingForVerification: If the lmn verification process has started, you cannot attempt to call this endpoint again for the same customer email. If you receive this error, please wait for the payment_token_updated webhook and then use the update_payment_token endpoint.
  • ServerError: There was an internal server error.
    • Requests can be retried as long as the idempotency_key is the same.
  • ValidationError: There was an issue with the request. Check the message field for the exact issue.
• message: Detailed string explaining the reason for the failure.