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`](/api-reference/payment-sessions/payment-session-completed-webhook) 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](/guides/payment-sessions/itemized-fees-and-discounts) - `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. - **NOTE: We don't support authorization holds for subscriptions** - `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. - `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) ### iFrame Payment Session If `use_iframe` is set to `true`, `redirect_url` will be iframe-compatible. Refer to iFrame Payment Session for a guide on handling the communication between the iframe and the parent as well as examples. ## Response Notes ### Success Case HTTP Status: `200` - `id` - the unique ID for this checkout session. This same ID will be returned if the endpoint is called with the same `idempotency_key` - 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 - `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 (e.g., Stripe configuration) is not enabled - `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`.