Payment tokens can be created outside of the [`create_payment_session`](/api-reference/payment-sessions/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`](/api-reference/payment-sessions/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. <Info title="Entering General Availability in Late October 2025"> For early access, contact your Truemed sales engineer. </Info> # Overview This endpoint supports creating a `payment_token` outside of the [`create_payment_session`](/api-reference/payment-sessions/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`](/api-reference/payment-sessions/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`](/api-reference/payment-tokens/payment-token-updated-webhook) 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`](/api-reference/payment-tokens/retrieve-payment-token-provision-request) docs. <Warning title="This endpoint creates a Token Provision Request NOT a Payment Token"> Partners only receive valid `payment_tokens` via the [`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook. A payment token can't be issued until the user successfully completes the tele-health survey and/or enters payment information. A callback is used to indicate the customer has completed token setup with Truemed. </Warning> The diagram below outlines the customer flow when using this endpoint: <Steps> <Step title="Create payment token"> The merchant partner calls `create_payment_token` and receives a `redirect_url`. </Step> <Step title="Customer completes Truemed checkout"> The customer is redirected to the `redirect_url` and completes the tele-health survey and enters payment information. </Step> <Step title="Customer returns to merchant"> The customer is redirected to the `success_url` provided by the merchant during the initial call to `create_payment_token`. </Step> <Step title="Receive payment token"> Truemed issues a [`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook including the newly provisioned `payment_token`. Customer email and name are included along with the `metadata` field to aid in linking to existing data in the partner's backend. </Step> </Steps> ```mermaid sequenceDiagram participant User participant Partner participant Truemed User->>Partner: Add HSA/FSA card option Partner->>Truemed: create_payment_token request Truemed-->>Partner: redirect_url response Partner-->>User: Redirect to redirect_url User->>Truemed: Complete eligibility survey Note over User: User eligible for HSA/FSA Truemed-->>User: Show payment method form User->>Truemed: Enter HSA/FSA card details Note over User: Payment method stored Truemed->>Partner: payment_token_callback webhook Truemed-->>User: Redirect to success_url ``` <Note> The webhook/callback is invoked at the same time the user is being redirected to the `success_url` - we don't guarantee that it will be called before the redirect. </Note> <Info title="Customer In The Flow"> **The customer must be in the flow** when calling this endpoint, typically from within a subscription management dashboard. </Info> **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. <Warning title="Truemed does not handle your subscription"> All subscription related fields here are to enhance the customer experience, you'll need your own subscription management system. </Warning> ## 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`](/api-reference/payment-tokens/payment-token-updated-webhook) 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. Partners can create an iframe and set the `src` to `redirect_url` and this will render Truemed's survey and checkout flow in the iframe. When using iframes, the flow completion is communicated via `postMessage`. The parent window should listen for messages from the iframe. The message will contain: - **success**: Returns `true` if checkout flow was successful on Truemed's end, `false` if otherwise - **redirectUrl**: String that will be set to `success_url` from the original request body if `success` is `true` or set to `failure_url` if `success` is `false`. - Only need to be used if redirect is desired or can handle success and failure differently ## 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`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook. - You can query the status of this request using the [`retrieve_provision_token_request`](/api-reference/payment-tokens/retrieve-payment-token-provision-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`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook was already received for this customer. To update, use the [`update_payment_token`](/api-reference/payment-tokens/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`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook and then use the [`update_payment_token`](/api-reference/payment-tokens/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.