Create Payment Session

Create a payment session to begin the “Pay with Truemed” checkout flow. Call this endpoint after the customer clicks “Checkout with Truemed” or similar. The customer is redirected to Truemed to complete a health survey and enter HSA/FSA card details, then redirected back to your site via the provided success_url or failure_url.

The outcome is communicated asynchronously via the payment_session_complete webhook.

Request Notes

• total_amount (Required): The total amount in cents to charge the user, inclusive of discounts, shipping, taxes, and other fees being collected by the partner
  • IMPORTANT: total_amount must equal the sum of:
    • payment.amount_details.total_additional_charges
    • payment.amount_details.total_discounts
    • For each order_item, the sum of:
      • item.quantity * item.price
      • item.amount_details.total_additional_charges
      • item.amount_details.total_discounts
• amount_details (Required): Read further here
• success_url (Required): Where to redirect the user to after Truemed successfully processes a payment
  • This is often used to display an order confirmation screen, or similar
  • Templating:
    • We support limited templating of this URL parameter. Any part of the URL string containing {{payment_session_id}} will be replaced by the id (UUID) returned by this call.
    • IMPORTANT: The template variable must be EXACTLY {{payment_session_id}} - no spaces around the braces on either side.
  • For unattended payment flows using payment tokens, the meaning of the success_url is slightly different. In such cases a payment may fail because the stored payment methods are expired or otherwise declined. When those failures occur, we will return a 422 status with a redirect_url to our page for updating stored payment methods. Merchants should email or otherwise notify users of the need to update their stored payment methods using this url. When users successfully complete that page, they will be redirected to the success_url provided here.
• failure_url (Required): When the payment fails in an irrecoverable way, or the user is ineligible to spend HSA/FSA funds on the purchase
  • We attempt to recover from incorrect CVV, or other card detail errors by prompting the user for retry
  • The exact failure reason will be communicated in the call to the partner’s payment_session_complete callback
  • Templating:
    • We support limited templating of this URL parameter. Any part of the URL string containing {{payment_session_id}} will be replaced by the id (UUID) returned by this call.
    • IMPORTANT: The template variable must be EXACTLY {{payment_session_id}} - no spaces around the braces on either side.
  • For unattended payment flows using payment tokens, the meaning of the failure_url is slightly different. In such cases a payment may fail because the stored payment methods are expired or otherwise declined. When those failures occur, we will return a 422 status with a redirect_url to our page for updating stored payment methods. Merchants should email or otherwise notify users of the need to update their stored payment methods using this url. When users start but cancel the update before fully completing the process, they will be redirected to the failure_url provided here.
• 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 webhook and detail view 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.
• kind (Optional): one of the following:
  • one_time_payment (DEFAULT): The charge is not a subscription related charge. This is the default if this field is not set.
  • authorization: A one_time_payment authorization hold only, must be manually captured or voided with a follow up API call.
• payment_token (Conditionally required): the ID returned by Truemed on initial recurring charges (when tokenize=True).
  • When payment_token is provided, customer identity is derived from the token’s user. Any customer_email or customer_name values in the request are ignored.
• tokenize (Optional): True or False - set to True to enable subsequent charges. Must be False if payment_token is provided.
• request_multicapture (Optional): True or False - set to True to opt this authorization into multiple partial captures.
  • IMPORTANT: This field requires multi-capture to be enabled on your sales channel, and cannot be combined with tokenize=true or payment_token. Otherwise the request fails with FeatureNotEnabled.
  • Only meaningful with kind=authorization. On a one_time_payment the charge captures immediately, so the flag is accepted but does nothing.
  • Requesting multi-capture does not guarantee it. The card network decides at authorization time, so a later capture sent with final: false can still be rejected.
• display_next_bill_info (Optional): Partners should only provide this field if they want to initiate a free trial subscription for the customer. The information in this object will be displayed on Truemed’s checkout page to provide more context to the customer when submitting their payment method(s)
  • total_amount: The amount in cents the customer will be charged when the free trial period ends
  • date: A YYYY-MM-DD string indicating the date the free trial period ends
  • IMPORTANT: This field requires tokenize=true and total_amount=0 (free trial subscriptions only)

Idempotency

idempotency_key lets you safely retry a request (e.g. after a network blip, or to dedupe between concurrent retries) without creating a duplicate payment session.

• Identical retry: If you call this endpoint again with the same idempotency_key and the same key request fields, you’ll get back the same payment session id (HTTP 200). The session is not re-created.
• Reused key with a different request: If you reuse the idempotency_key but change one of the key fields, you’ll get a 400 IdempotencyViolation. The message will name the specific field(s) that diverged so you can debug.

Fields compared (must match the original request to be treated as a retry):

• customer_email — compared case-insensitively (User@example.com matches user@example.com)
• total_amount
• success_url, failure_url
• order_items (name, sku, quantity, price, item_id, and item-level amount details)
• kind
• payment_token (when present on the retry)
• display_next_bill_info.total_amount, display_next_bill_info.date, and the implied is_free_trial flag (when present on the original)

Fields not compared — differences in these fields do not affect idempotency matching:

• customer_name
• metadata
• customer_state
• survey_config
• billing_name, billing_address, shipping_name, shipping_address
• request_multicapture, test_config, and other request configuration

If a retry sends different values for any of these, the original payment session is still returned — the new values are not applied to the existing session.

How order_items is compared. Line order does not matter, and neither does the order of the entries inside a line’s amount_details. A cart carrying the same line twice must replay with it twice. item_id is part of a line’s identity: omit it and Truemed provisions one, so a retry that adds your own id is rejected. Send the same item_id on both calls, or omit it on both.

The 400 carries no payment session id. If you lost the original response, find the session with list payment sessions.

iFrame Payment Session

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

• id - the unique ID for this checkout session. The same id will be returned if the endpoint is called again with the same idempotency_key and the request’s key fields match the original (see Idempotency below).
  • Associate this id with your internal representation of a checkout session, if applicable
• redirect_url - the URL that the partner should redirect the customer to
  • Typically this would be done after the user presses a “Checkout with Truemed” button or similar on the partner’s site
  • The user will perform the following steps on Truemed’s platform
    • Complete a health survey to determine eligibility to spend HSA/FSA funds on the purchase
    • Enter HSA/FSA card details, and confirm the purchase
  • The status of the checkout session will be communicated back to the partner via the payment_session_complete webhook

Bad Request

HTTP Status: 400

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

• error: Can be one of:
  • MissingRequiredParameter: A required field is not present in the request
  • InvalidRequestParameter: A field value is invalid (e.g., malformed email, invalid URL)
  • TotalAmountInvalid: The total_amount field is either:
    • Not greater than or equal to the sum of the object_item amount fields
    • The total_amount is 0
    • The total_amount is negative
  • OrderItemsInvalid: The order_items array failed validation
  • IdempotencyViolation: An idempotency_key was reused with different request parameters. The message names the specific field(s) that diverged from the original request. See Idempotency below for which fields are compared.
  • ServerError: There was an internal server error.
    • Requests can be retried as long as the idempotency-key is the same.
  • SessionPending: A charge to the existing payment method is unable to be processed because the user has yet to enter a payment method.
    • This is only possible when creating a charge using a payment_token before the user has finished the initial checkout (for the payment_session created with tokenize=True).
  • TokenizeNotSupported: Both tokenize=True and payment_token were set. You can’t tokenize a payment session if the session is being billed back to a prior one using a payment_token.
  • FeatureNotEnabled: A required merchant feature is not enabled - for example Stripe configuration, or request_multicapture=true on a sales channel without multi-capture enabled or in combination with tokenize or payment_token
• message: A human-readable description of the error

Unprocessable Entity

HTTP Status: 422

If a payment_token was provided and the token requires customer intervention before it can be used again, a 422 will be returned.

• next_action: The action the customer must take. Can be one of the following:
  • UpdatePaymentMethod: Customer must enter a new payment method.
  • TakeHealthSurvey: Customer must retake the health survey
• redirect_url: Contains a URI through which the customer can correct the payment_token.