Create Payment Session

To begin the "Pay with Truemed" flow, a post request needs to be made to Truemed's `create_payment_session` endpoint. The `create_payment_session` endpoint should be called after a user clicks "Checkout with Truemed" or similar. The user will be redirected to Truemed to complete the checkout flow, and will be redirected back to the partner site upon successful (or failed) payments via the URLs provided in the request by the partner. The failure or success status is communicated to the partner via a [`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`). - `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**: If this object is provided, the `total_amount` field must be 0 to reflect that this is a free trial ### 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: - `MissingField`: One of the required fields is not present in the request - `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 - `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`. - `PendingPaymentTokenUpdate`: When a `payment_token` is provided to create a new charge before the user has resolved a pending action, such as updating their payment method or retaking the health survey. See the failure recovery section in our Subscriptions Guide. - `message`: Indication of one of the following: - Which field was missing - Details on how the total amount was invalid ### 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`.