{ "openapi": "3.1.0", "info": { "contact": { "email": "api-support@truemed.com", "name": "API Support" }, "description": "Truemed integration API for payment processing and qualification management.", "license": { "name": "Proprietary", "url": "https://truemed.com/terms" }, "title": "Truemed Merchant Integration API v1", "version": "1.8.0" }, "servers": [ { "description": "Development server", "url": "https://dev-api.truemed.com" }, { "description": "Production server", "url": "https://api.truemed.com" } ], "tags": [ { "description": "APIs for creating and managing payment sessions, including authorization, capture, void, and cancellation operations", "name": "Payment Sessions" }, { "description": "APIs for creating and managing payment tokens for stored payment methods and subscription billing", "name": "Payment Tokens" }, { "description": "Pre-screen your customers for HSA/FSA spending before checkout. Create a session to check whether their cart might qualify, then guide them through the redirect flow to convert more eligible shoppers.", "name": "Qualification Sessions" }, { "description": "APIs for creating and managing catalog items", "name": "Product Catalog" }, { "description": "APIs for merchants to retrieve paginated reconciliation data, matching the report.", "name": "Reconciliations" } ], "paths": { "/payments/v1/create_payment_session": { "post": { "deprecated": false, "description": "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`.\n\nThe outcome is communicated asynchronously via the\n[`payment_session_complete`](/api-reference/payment-sessions/payment-session-completed-webhook) webhook.\n\n## Request Notes\n\n- `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\n - **IMPORTANT**: total_amount must equal the sum of:\n - `payment.amount_details.total_additional_charges`\n - `payment.amount_details.total_discounts`\n - For each order_item, the sum of:\n - `item.quantity * item.price`\n - `item.amount_details.total_additional_charges`\n - `item.amount_details.total_discounts`\n- `amount_details` **(Required)**: [Read further here](/guides/payment-sessions/itemized-fees-and-discounts)\n- `success_url` **(Required)**: Where to redirect the user to after Truemed successfully processes a payment\n - This is often used to display an order confirmation screen, or similar\n - **Templating**:\n - 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.\n - **IMPORTANT**: The template variable must be EXACTLY `{{payment_session_id}}` - no spaces around the braces on either side.\n - 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.\n- `failure_url` **(Required)**: When the payment fails in an irrecoverable way, or the user is ineligible to spend HSA/FSA funds on the purchase\n - We attempt to recover from incorrect CVV, or other card detail errors by prompting the user for retry\n - The exact failure reason will be communicated in the call to the partner's `payment_session_complete` callback\n - **Templating**:\n - 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.\n - **IMPORTANT**: The template variable must be EXACTLY `{{payment_session_id}}` - no spaces around the braces on either side.\n - 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.\n- `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\n - 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.\n- `metadata` **(Optional)**: - Will be echoed back in the webhook and detail view if present.\n - **IMPORTANT**: This must be a string. If you want to include JSON, encode it as a string.\n - **IMPORTANT**: DO NOT INCLUDE sensitive information in this field.\n- `kind` **(Optional)**: one of the following:\n - `one_time_payment` **(DEFAULT)**: The charge is not a subscription related charge. This is the default if this field is not set.\n - `authorization`: A `one_time_payment` authorization hold only, must be manually captured or voided with a follow up API call.\n - **NOTE: We don't support authorization holds for subscriptions**\n- `payment_token` **(Conditionally required)**: the ID returned by Truemed on initial recurring charges (when `tokenize=True`).\n - 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.\n- `tokenize` **(Optional)**: `True` or `False` - set to `True` to enable subsequent charges. Must be `False` if `payment_token` is provided.\n- `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)\n - `total_amount`: The amount in cents the customer will be charged when the free trial period ends\n - `date`: A YYYY-MM-DD string indicating the date the free trial period ends\n - **IMPORTANT**: This field requires `tokenize=true` and `total_amount=0` (free trial subscriptions only)\n\n### Idempotency\n\n`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.\n\n- **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.\n- **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.\n\n**Fields compared** (must match the original request to be treated as a retry):\n\n- `customer_email` \u2014 compared case-insensitively (`User@example.com` matches `user@example.com`)\n- `total_amount`\n- `success_url`, `failure_url`\n- `order_items` (name, sku, quantity, price, item-level amount details)\n- `kind`\n- `payment_token` (when present on the retry)\n- `display_next_bill_info.total_amount`, `display_next_bill_info.date`, and the implied `is_free_trial` flag (when present on the original)\n\n**Fields not compared** \u2014 differences in these fields do not affect idempotency matching:\n\n- `customer_name`\n- `metadata`\n- `customer_state`\n- `survey_config`\n- `billing_name`, `billing_address`, `shipping_name`, `shipping_address`\n- `request_multicapture`, `test_config`, and other request configuration\n\nIf a retry sends different values for any of these, the original payment session is still returned \u2014 the new values are not applied to the existing session.\n\n### iFrame Payment Session\n\nIf `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.\n\n## Response Notes\n\n### Success Case\n\nHTTP Status: `200`\n\n- `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](#idempotency) below).\n - Associate this id with your internal representation of a checkout session, if applicable\n- `redirect_url` - the URL that the partner should redirect the customer to\n - Typically this would be done after the user presses a \"Checkout with Truemed\" button or similar on the partner's site\n - The user will perform the following steps on Truemed's platform\n - Complete a health survey to determine eligibility to spend HSA/FSA funds on the purchase\n - Enter HSA/FSA card details, and confirm the purchase\n - The status of the checkout session will be communicated back to the partner via the `payment_session_complete` webhook\n\n### Bad Request\n\nHTTP Status: `400`\n\nIf a field is missing or the request is otherwise can't be processed, we'll return a `400` with the following fields:\n\n- `error`: Can be one of:\n - `MissingRequiredParameter`: A required field is not present in the request\n - `InvalidRequestParameter`: A field value is invalid (e.g., malformed email, invalid URL)\n - `TotalAmountInvalid`: The `total_amount` field is either:\n - Not greater than or equal to the sum of the `object_item` `amount` fields\n - The `total_amount` is 0\n - The `total_amount` is negative\n - `OrderItemsInvalid`: The `order_items` array failed validation\n - `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](#idempotency) below for which fields are compared.\n - `ServerError`: There was an internal server error.\n - Requests can be retried as long as the `idempotency-key` is the same.\n - `SessionPending`: A charge to the existing payment method is unable to be processed because the user has yet to enter a payment method.\n - 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`).\n - `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`.\n - `FeatureNotEnabled`: A required merchant feature (e.g., Stripe configuration) is not enabled\n- `message`: A human-readable description of the error\n\n### Unprocessable Entity\n\nHTTP Status: `422`\n\nIf a `payment_token` was provided and the `token` requires customer intervention before it can be used again, a `422` will be returned.\n\n- `next_action`: The action the customer must take. Can be one of the following:\n - `UpdatePaymentMethod`: Customer must enter a new payment method.\n - `TakeHealthSurvey`: Customer must retake the health survey\n- `redirect_url`: Contains a URI through which the customer can correct the `payment_token`.", "operationId": "createPaymentSession", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentSessionRequest" } } }, "description": "Request body for CreatePaymentSessionRequest", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentSessionResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "featurenotenabled": { "summary": "FeatureNotEnabled example", "value": { "error": "FeatureNotEnabled", "message": "Bad Request" } }, "idempotencyviolation": { "summary": "IdempotencyViolation example", "value": { "error": "IdempotencyViolation", "message": "Bad Request" } }, "invalidrequestparameter": { "summary": "InvalidRequestParameter example", "value": { "error": "InvalidRequestParameter", "message": "Bad Request" } }, "missingrequiredparameter": { "summary": "MissingRequiredParameter example", "value": { "error": "MissingRequiredParameter", "message": "Bad Request" } }, "orderitemsinvalid": { "summary": "OrderItemsInvalid example", "value": { "error": "OrderItemsInvalid", "message": "Bad Request" } }, "sessionpending": { "summary": "SessionPending example", "value": { "error": "SessionPending", "message": "Bad Request" } }, "tokenizenotsupported": { "summary": "TokenizeNotSupported example", "value": { "error": "TokenizeNotSupported", "message": "Bad Request" } }, "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "properties": { "error": { "enum": [ "FeatureNotEnabled", "IdempotencyViolation", "InvalidRequestParameter", "MissingRequiredParameter", "OrderItemsInvalid", "SessionPending", "TokenizeNotSupported", "TotalAmountInvalid", "ValidationError" ], "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "type": "object" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Page not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Create a new payment session for HSA/FSA checkout", "tags": [ "Payment Sessions" ] } }, "/payments/v1/payment_session/{business_id}": { "get": { "deprecated": false, "description": "Get the status of a payment session based on the payment session id.\n\n## Request Notes\n\nTo get the status of a Payment Session object, call the detail view with the ID of the\npayment session returned by the `create_payment_session` endpoint.\n\n## Response Notes\n\n- `status` - the status of the initial payment, an enum with one of the following values:\n - `captured` - payment has completed\n - `canceled` - payment was canceled before the user entered payment information via a call\n to our cancel API.\n - `pending` - payment has not been successfully completed yet.\n - `processing` - the customer has entered their payment information, but it is under review\n by Truemed\n - Any customer facing communication should indicate successful payment at this point,\n such as on the `success_url`.\n - The merchant should not fulfill the order until the Payment Session Webhook indicates\n that the payment has been captured.\n - `rejected` - While in the `processing` state, Truemed reviewed and rejected the payment\n session.\n - The merchant should not fulfill these orders, and should communicate failure to the\n user via email.\n - `authorized` - an auth hold has been placed on the customer's card.\n - `authorization_voided` - the auth hold has been voided via a call to our Void Session api.\n - `authorization_expired` - the auth hold has expired and we were not able to re-auth the\n transaction. This state is only possible after a call to our Manual Capture api, and is\n only set after we attempt a re-auth hold on the existing payment method.\n- `status_summary` - a summary of the overall payment session. This includes refunds and\n disputes, and is an enum of the following values:\n - `Incomplete` - Customer started checkout but did not complete\n - `Authorized` - Auth hold placed on customer's payment method\n - `Captured` - Payment has been processed\n - `Partially Captured` - The payment has been partially processed\n - `Refunded` - The full amount charged in this order has been refunded to customer\n - `Partially Refunded` - Part of the original order has been refunded to the customer\n - `Disputed` - The transaction has been disputed by the customer\n - `Voided` - The payment was voided by the partner\n - `Expired` - The partner did not capture an authorized session before it expired\n- `order_items` - a list of order items, with the following fields per item:\n - `item_id` - The item_id that uniquely identifies this item. If the client specified one\n when creating the Payment Session, that item_id will be returned.\n - `name` - the name of the item\n - `price` - the unit price in cents charged for the item\n - `quantity` - the number of this item in the cart\n - `sku` - the partner's SKU for the item\n - `total_refundable` **(Optional)** - If the Payment Session has been captured, this value\n will be the remaining amount refundable for this item. Otherwise it will not be included.\n - `quantity_refundable` **(Optional)** - If the Payment Session has been captured, this\n value will be the remaining quantity refundable for this item. Otherwise it will not be\n included.\n - `total_capturable` **(Optional)** - If the Payment Session is an authorization and is\n currently authorized, this value will be the remaining amount capturable for this item.\n Otherwise it will not be included.\n - `quantity_capturable` **(Optional)** - If the Payment Session is an authorization and is\n currently authorized, this value will be the remaining quantity capturable for this item.\n Otherwise it will not be included.\n- `capture_amount` **(Optional)** - the amount of funds actually captured.\n - For payment sessions of `kind=one_time_payment` this field will always be present and\n will be the same as `authorize_amount`.\n - For payment sessions of `kind=authorization` this field will not be present until the\n funds have been captured (via a call to Manual Capture).", "operationId": "retrievePaymentSession", "parameters": [ { "deprecated": false, "description": "The payment session ID.", "in": "path", "name": "business_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSessionDetailResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "missingfield": { "summary": "MissingField example", "value": { "error": "MissingField", "message": "Bad Request" } }, "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "properties": { "error": { "enum": [ "MissingField", "TotalAmountInvalid", "ValidationError" ], "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "type": "object" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "invalidpaymentid": { "summary": "InvalidPaymentId example", "value": { "error": "InvalidPaymentId", "message": "Payment not found." } }, "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Resource not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Retrieve the current status of a payment session", "tags": [ "Payment Sessions" ] } }, "/payments/v1/payment_sessions": { "get": { "deprecated": false, "description": "All payment sessions created with the Create payment session API call can be listed\nvia a GET to `/payments/v1/payment_sessions`.\n\nBy default, all payment sessions, including those that are pending, created as auth\nholds and those that have been manually voided or captured will be listed. Options are\nprovided for granular filtering, pagination, and search.\n\n## Pagination\n\nAll results are paginated, with 30 per page. The response field `pagination` contains\ninformation on how many payment sessions there are and how many pages are available\nfor the filtered query.\n\n## Sorting\n\nPayment sessions are sorted by the date they are created, with newer ones being returned first.\n\n# Response Notes\n\nThe response is an array of payment sessions in the `payment_sessions` key. A few things to point out about\nthe response payload:\n\n- `order_items` **(Optional)** - The list of the current state of the order items passed into\n `create_payment_session` if `include_order_items` is True\n - `total_refundable` **(Optional)** - If the Payment Session has been captured, this value\n will be the remaining amount refundable for this item. Otherwise it will not be included.\n - `quantity_refundable` **(Optional)** - If the Payment Session has been captured, this\n value will be the remaining quantity refundable for this item. Otherwise it will not be\n included.\n - `total_capturable` **(Optional)** - If the Payment Session is an authorization and is\n currently authorized, this value will be the remaining amount capturable for this item.\n Otherwise it will not be included.\n - `quantity_capturable` **(Optional)** - If the Payment Session is an authorization and is\n currently authorized, this value will be the remaining quantity capturable for this item.\n Otherwise it will not be included.\n- `authorized_on` - the date the payment was authorized in ISO 8601 format\n - example: \"2024-06-13T16:03:07.473Z\"\n - For `kind`: `one_time_payment`, this will be the same as `captured_on`\n- `refund_amount` **(Optional)** - int\n - Only present when `summarize_refunds=True` is included in the request.\n - The sum of processed refunds for the payment session, **in cents**\n- `truemed_fee` **(Optional)** - decimal - **in dollars**\n - Only present when `include_truemed_fee=True` is included in the request.\n - The fee collected by truemed for this payment session.\n\nThe response also includes a `pagination` object:\n\n```\n{\n \"pagination\": {\n \"current_page\": 1,\n \"page_size\": 30,\n \"count\": 54,\n \"last_page\": 2\n },\n \"payment_sessions\": [\n ]\n}\n```\n\n- `current_page` - the page requested. If none was provided, this will default to 1.\n- `page_size` - the number of `payment_session`'s per page, which is always 30.\n- `count` - the total number of `payment_session`'s matching the filters provided.\n- `last_page` - the last page.\n - You can iterate through pages by providing integers up to `last_page` in the `page`\n parameter.", "operationId": "listPaymentSession", "parameters": [ { "allowReserved": false, "deprecated": false, "description": "Optional field indicating which page to access. Defaults to 1.", "in": "query", "name": "page", "required": false, "schema": { "type": "integer" } }, { "allowReserved": false, "deprecated": false, "description": "Optional field indicating the number of records per page. Defaults to 30.", "in": "query", "name": "page_size", "required": false, "schema": { "type": "integer" } }, { "allowReserved": false, "deprecated": false, "description": "Filter out pending payment sessions.", "in": "query", "name": "filter_pending", "required": false, "schema": { "type": "boolean" } }, { "allowReserved": false, "deprecated": false, "description": "Filter out voided payment sessions.", "in": "query", "name": "filter_voided", "required": false, "schema": { "type": "boolean" } }, { "allowReserved": false, "deprecated": false, "description": "Include metadata field in the response.", "in": "query", "name": "include_metadata", "required": false, "schema": { "type": "boolean" } }, { "allowReserved": false, "deprecated": false, "description": "Include order items in the response.", "in": "query", "name": "include_order_items", "required": false, "schema": { "type": "boolean" } }, { "allowReserved": false, "deprecated": false, "description": "Search by payment session ID, user business ID, email, or name.", "in": "query", "name": "search", "required": false, "schema": { "type": "string" } }, { "allowReserved": false, "deprecated": false, "description": "Filter payment sessions created on or after this date (ISO 8601 format).", "in": "query", "name": "created_on_start", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "allowReserved": false, "deprecated": false, "description": "Filter payment sessions created on or before this date (ISO 8601 format).", "in": "query", "name": "created_on_end", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "allowReserved": false, "deprecated": false, "description": "Filter payment sessions captured on or after this date (ISO 8601 format).", "in": "query", "name": "captured_on_start", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "allowReserved": false, "deprecated": false, "description": "Filter payment sessions captured on or before this date (ISO 8601 format).", "in": "query", "name": "captured_on_end", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "allowReserved": false, "deprecated": false, "description": "Include refund details in the response (default: true).", "in": "query", "name": "include_refunds", "required": false, "schema": { "type": "boolean" } }, { "allowReserved": false, "deprecated": false, "description": "Include dispute details in the response (default: true).", "in": "query", "name": "include_disputes", "required": false, "schema": { "type": "boolean" } }, { "allowReserved": false, "deprecated": false, "description": "Filter by payment kind (comma-separated list: one_time_payment, authorization).", "explode": false, "in": "query", "name": "kind", "required": false, "schema": { "items": { "type": "string" }, "type": "array" }, "style": "form" }, { "allowReserved": false, "deprecated": false, "description": "Filter by payment session status (comma-separated list).", "explode": false, "in": "query", "name": "status", "required": false, "schema": { "items": { "type": "string" }, "type": "array" }, "style": "form" }, { "allowReserved": false, "deprecated": false, "description": "Include refund_amount summary instead of full refund details.", "in": "query", "name": "summarize_refunds", "required": false, "schema": { "type": "boolean" } }, { "allowReserved": false, "deprecated": false, "description": "Include Truemed fee in the response.", "in": "query", "name": "include_truemed_fee", "required": false, "schema": { "type": "boolean" } }, { "allowReserved": false, "deprecated": false, "description": "Filter payment sessions by payment token ID.", "in": "query", "name": "payment_token", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSessionListResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Page not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "List payment sessions with filtering and pagination", "tags": [ "Payment Sessions" ] } }, "/payments/v1/payment_session/{business_id}/capture": { "post": { "deprecated": false, "description": "The `capture_payment_session` endpoint should be called after [`create_payment_session`](/api-reference/payment-sessions/create-payment-session)\nhas been called with `kind` of `authorization` as outlined in [Manual/Delayed Capture](/guides/payment-sessions/manual-delayed-capture).\n\nThe failure or success status is communicated to the partner via a [`payment_session_complete`](/api-reference/payment-sessions/payment-session-completed-webhook)\nwebhook as before.\n\n## Request Notes\n\n\nThe `total_amount` field will often not be the sum of the `order_item[*].price` fields, as you may be charging additional\nfees or including taxes.\n\n\n- **`total_amount`** *(Required)* - The total amount in cents to charge the user, inclusive of taxes and fees being collected by the partner. **Must be less than or equal to the `total_amount` passed in when creating the payment session.**\n - If an amount more than the initial authorization should be captured, void the initial auth hold and create a new one.\n\n## Response Notes\n\n### Success Case\n\nHTTP Status: `200`\n\n- **`id`** - The unique ID for this session capture. 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.\n\n### Bad Request\n\nHTTP Status: `400`\n\nIf a field is missing or the request otherwise can't be processed, we'll return a `400` with the following fields:\n\n- **`error`** - can be one of:\n - `MissingField`: One of the required fields is not present in the request.\n - `TotalAmountInvalid`: The `total_amount` field is either not greater than or equal to the sum of the `order_item` `amount` fields, is 0, is negative, or is greater than the `total_amount` passed in when creating the payment session.\n - `PaymentSessionDoesNotExist`: The `payment_session_id` does not exist.\n - `ServerError`: There was an internal server error. Requests can be retried as long as the `idempotency_key` is the same.\n - `SessionVoided`: The session has already been voided via a call to [`/payment_session/{payment_session_id}/void`](/api-reference/payment-sessions/void-payment-session).\n - `SessionExpired`: The auth hold has expired and we were unable to recharge the customer for the amount requested.\n - `SessionPending`: The user hasn't completed the Truemed checkout flow (survey, CC entry form).\n - `SessionCaptured`: You're attempting to capture a payment_session that has already been captured. This error **will never** be returned if reissuing a capture call **with the same idempotency key** - the return value will be the same as the first call.\n - `ImmediateCapture`: The caller is attempting to void a payment_session that wasn't created with `kind=authorization`.\n- **`message`** - Indication of which field was missing, details on how the total amount was invalid, or details on voided sessions.", "operationId": "capturePaymentSession", "parameters": [ { "deprecated": false, "description": "The UUID of the payment session returned by create_payment_session.", "in": "path", "name": "business_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSessionCaptureRequest" } } }, "description": "Request body for PaymentSessionCaptureRequest", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSessionCaptureResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "immediatecapture": { "summary": "ImmediateCapture example", "value": { "error": "ImmediateCapture", "message": "This session uses kind=one_time_payment and was automatically captured. Manual capture is only available for sessions created with kind=authorization." } }, "sessioncaptured": { "summary": "SessionCaptured example", "value": { "error": "SessionCaptured", "message": "Cannot capture a payment that has already been captured." } }, "sessionexpired": { "summary": "SessionExpired example", "value": { "error": "SessionExpired", "message": "The auth hold for this payment session has expired." } }, "sessionpending": { "summary": "SessionPending example", "value": { "error": "SessionPending", "message": "Session is still pending." } }, "sessionvoided": { "summary": "SessionVoided example", "value": { "error": "SessionVoided", "message": "Session has been voided." } }, "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "properties": { "error": { "enum": [ "ImmediateCapture", "SessionCaptured", "SessionExpired", "SessionPending", "SessionVoided", "TotalAmountInvalid", "ValidationError" ], "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "type": "object" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Resource not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Capture a previously authorized payment session", "tags": [ "Payment Sessions" ] } }, "/payments/v1/payment_session/{business_id}/cancel": { "post": { "deprecated": false, "description": "The `cancel` API exists so that merchant partners can manage cart lifecycles.\nIn an ideal world, the customer experience would roughly be outlined by:\n\n\n \n The customer browses your store and adds items to their shopping cart.\n \n \n The customer clicks the \"Checkout with Truemed\" button to begin the payment process.\n \n \n The partner calls `create_payment_session`, and an inventory lock is placed on the items in the cart to ensure they can be fulfilled when payment is captured.\n \n \n The customer completes the survey and enters payment information in the Truemed interface.\n \n \n The merchant listens for the Partner webhook callback and fulfills the inventory locked above.\n \n\n\n## Deviations from the Happy Path\n\nIn the flow above, there are a few steps the customer can take that would void the\nexisting session.\n\nThe customer could:\n\n- **Navigate away from Truemed during the survey, and modify their cart.** This\n dictates a new idempotency key (e.g.: a new `payment_session`). As part of clean up\n and to ensure the customer can't navigate back to the now outdated survey link, the\n old payment session must be canceled.\n- **Take too long to complete the survey and finalize payment.** The merchant may wish\n to cancel the `payment_session` and release the lock on inventory as it appears the\n customer is no longer interested in making the purchase.\n\n## Customer Experience for Canceled Sessions\n\nIf this API is used to cancel a pending session, the customer will be shown a page\nindicating that the checkout session has timed out and a link will be provided to\n\"Go back to checkout\" which will return them to the `failure_url` provided in\n`create_payment_session`.\n\nThe page presented by the `failure_url` should be generic and display a relevant\nmessage asking the customer to checkout again if it has been too long.\n\n\"Too long\" is defined by our merchant partners depending on their inventory management.\nWe recommend 48-72 hours as customers will sometimes move funds into their HSA prior to\ncompleting checkout.\n\n# API Overview\n\nThe `cancel_payment_session` endpoint can be called after `create_payment_session` has\nbeen called, but before the customer has entered their payment information, for either\n`kind=authorization` or `kind=one_time_payment`.\n\nThe failure or success status is communicated to the partner via a webhook\n`payment_session_complete` as before.\n\n## Request Notes\n\nThere are no required fields for the request body, you simply call the endpoint with\nthe `payment_session_id` in the URL. The cancel API can be called repeatedly without an\nidempotency key and the same result will be returned.\n\n**Important** - you will only get a single callback queued on successful cancelation\n(albeit, invoked multiple times in the case of failures) as outlined in Partner webhook,\neven if you call the cancel endpoint multiple times.\n\n## Response Notes\n\n### Success Case\n\nHTTP Status: `200`\n\nNote: `order_items.sku` - the partner's SKU for the item. The value of this field will\nbe the SKU provided by the partner in the [`create_payment_session`](/api-reference/payment-sessions/create-payment-session)\nrequest. If the partner does not provide a SKU value for an item on creation of the payment, this\nkey will not be present.\n\n### Failure Case\n\nHTTP Status: `400`\n\nIf a field is missing or the request otherwise can't be processed, we'll return a `400`\nwith the following fields:\n\n- `error` - can be one of:\n - `InvalidPaymentId` - the `payment_session_id` does not exist.\n - `ServerError` - There was an internal server error. Requests can be retried.\n - `SessionCaptured` - The session has already been captured via a call to\n `/payment_session/{payment_session_id}/capture` and can no longer be canceled. In\n this case, to return funds to the customer, you'll need to issue a refund.\n - `SessionAuthorized` - The session has already been authorized. The user has\n completed the survey and entered their credit card information. In this case, the\n session should be voided via the Void Session API, and the customer should be\n informed that their order has been canceled.\n- `message` - Details on the above conditions.", "operationId": "cancelPaymentSession", "parameters": [ { "deprecated": false, "description": "The payment session ID to cancel.", "in": "path", "name": "business_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSessionCancelResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "sessionauthorized": { "summary": "SessionAuthorized example", "value": { "error": "SessionAuthorized", "message": "Payment session has been authorized, it must be voided, not canceled." } }, "sessioncaptured": { "summary": "SessionCaptured example", "value": { "error": "SessionCaptured", "message": "Payment session has already been captured." } }, "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "properties": { "error": { "enum": [ "SessionAuthorized", "SessionCaptured", "TotalAmountInvalid", "ValidationError" ], "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "type": "object" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Resource not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Cancel a pending payment session before completion", "tags": [ "Payment Sessions" ] } }, "/payments/v1/payment_session/{business_id}/void": { "post": { "deprecated": false, "description": "The `void_payment_session` endpoint should be called after\n[`create_payment_session`](/api-reference/payment-sessions/create-payment-session)\nhas been called with `kind` of `authorization` as outlined in [Create Payment Session\n(Manual Capture)](/guides/payment-sessions/manual-delayed-capture).\n\nThe failure or success status is communicated to the partner via a\n[`payment_session_complete`](/api-reference/payment-sessions/payment-session-completed-webhook) webhook as before.\n\n## Response Notes\n\n### Success Case\n\nHTTP Status: `200`\n\n- `id` - the unique ID for this void session. This same ID will be returned if the endpoint\n is called with the same `idempotency_key`\n - Associate this id with your internal representation of a checkout session, if applicable\n\n### Failure Case:\n\nHTTP Status: `400`\n\nIf a field is missing or the request is otherwise can't be processed, we'll return a `400`\nwith the following fields:\n\n- `error` - can be one of:\n - `MissingField`: one of the required fields is not present in the request\n - `PaymentSessionDoesNotExist` - the `payment_session_id` does not exist.\n - `ServerError`: There was an internal server error.\n - Requests can be retried as long as the `idempotency-key` is the same.\n - `SessionCaptured` - The session has already been captured via a call to\n [`/payment_session/{payment_session_id}/capture`](/api-reference/payment-sessions/capture-payment-session)\n and can no longer be voided.\n - In this case, to return funds to the customer, you'll need to issue a refund.\n - `SessionPending` - The survey hasn't been completed by the customer, and no auth hold\n has been placed, so there is no auth hold to void yet.\n - `ImmediateCapture` - The caller is attempting to void a payment_session that wasn't\n created with `kind=authorization`\n- `message`:\n - Indication of one of the following:\n - Which field was missing\n - Details on how the total amount was invalid\n - Details on captured sessions.", "operationId": "voidPaymentSession", "parameters": [ { "deprecated": false, "description": "The UUID of the payment session returned by create_payment_session.", "in": "path", "name": "business_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSessionVoidRequest" } } }, "description": "Request body for PaymentSessionVoidRequest", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSessionVoidResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "immediatecapture": { "summary": "ImmediateCapture example", "value": { "error": "ImmediateCapture", "message": "This session uses kind=one_time_payment and cannot be voided. Void is only available for sessions created with kind=authorization. To reverse a captured payment, use the refund endpoint." } }, "sessioncaptured": { "summary": "SessionCaptured example", "value": { "error": "SessionCaptured", "message": "Session has already been captured." } }, "sessionnotauthorized": { "summary": "SessionNotAuthorized example", "value": { "error": "SessionNotAuthorized", "message": "Cannot void a payment that has not been authorized." } }, "sessionvoided": { "summary": "SessionVoided example", "value": { "error": "SessionVoided", "message": "Cannot void a payment that has already been voided." } }, "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "properties": { "error": { "enum": [ "ImmediateCapture", "SessionCaptured", "SessionNotAuthorized", "SessionVoided", "TotalAmountInvalid", "ValidationError" ], "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "type": "object" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Resource not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Void an authorized payment session before capture", "tags": [ "Payment Sessions" ] } }, "/payments/v1/refund": { "post": { "deprecated": false, "description": "Use this endpoint to refund payments Truemed has already processed on your behalf. Partial refunds are supported.\n\n## Request Notes\n\n\nThe amount requested must be less than or equal to the total amount that the\npayment was originally created with.\n\n\n## Response Notes\n\n### Bad Request\n\nHTTP Status: `400`\n\nIf a field is missing or the request is otherwise can't be processed, we'll return a `400`\nwith the following fields:\n\n- `error` - can be one of:\n - `MissingField`: one of the required fields is not present in the request\n - `AmountInvalid`: the `amount` field is negative, 0, or greater than the amount remaining\n available to refund on the payment\n - `InvalidPaymentId`: requesting to refund a payment that does not exist\n - `ChargeDisputed`: Payment session has a pending dispute. Can't refund until the dispute is\n resolved. Lost disputes reduce the remaining refundable amount but no longer block refunds\n of the undisputed remainder.\n - `NoSessionCaptures`: The payment session can't be refunded because there haven't been any\n funds captured.\n- `message`:\n - Indication of one of the following:\n - Which field was missing\n - Details on how the amount was invalid\n - Invalid payment id", "operationId": "createRefund", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRefundRequest" } } }, "description": "Request body for CreateRefundRequest", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRefundResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Page not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Create a full or partial refund for a captured payment", "tags": [ "Payment Sessions" ] } }, "/api/v1/payment_tokens/create": { "post": { "deprecated": false, "description": "Payment tokens can be created outside of the\n[`create_payment_session`](/api-reference/payment-sessions/create-payment-session) API call. This is most\ncommonly used to support existing subscription customers, allowing them to move their subscriptions\nto their HSA/FSA. Use [`create_payment_session`](/api-reference/payment-sessions/create-payment-session)\nwith `tokenize=True` to create a subscription as part of a checkout flow, such as the first order in a subscription,\nor free trials.\n\n\nFor early access, contact your Truemed sales engineer.\n\n\n# Overview\n\nThis endpoint supports creating a `payment_token` outside of the\n[`create_payment_session`](/api-reference/payment-sessions/create-payment-session) flow,\nand is commonly used to support giving the option to existing subscribers to pay with their\nHSA/FSA. This endpoint can also be used to \"store a payment method with Truemed\" inside of a\nuser dashboard. Subscription free-trials are possible with this endpoint, though we recommend\nusing [`create_payment_session`](/api-reference/payment-sessions/create-payment-session) for trials\nfor consistency with the standard checkout experience.\n\nThis endpoint returns **the ID of a new `provision_token_request`, NOT a new `payment_token`**.\nThe `payment_token` itself will be available upon receipt of the\n[`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook with the corresponding\n`provision_token_request_id`. In order to support backfills in the case of unforeseen downtime\n(a webhook that goes unacknowledged, or is missed), you can also query the status of the\n`provision_token_request` directly as outlined in our\n[`retrieve_provision_token_request`](/api-reference/payment-tokens/retrieve-payment-token-provision-request) docs.\n\n\nPartners only receive valid `payment_tokens` via the\n[`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook. A payment token can't be issued\nuntil the user successfully completes the tele-health survey and/or enters payment information.\nA callback is used to indicate the customer has completed token setup with Truemed.\n\n\nThe diagram below outlines the customer flow when using this endpoint:\n\n\n \n The merchant partner calls `create_payment_token` and receives a `redirect_url`.\n \n \n The customer is redirected to the `redirect_url` and completes the tele-health survey and enters payment information.\n \n \n The customer is redirected to the `success_url` provided by the merchant during the initial call to `create_payment_token`.\n \n \n 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.\n \n\n\n```mermaid\nsequenceDiagram\n participant User\n participant Partner\n participant Truemed\n\n User->>Partner: Add HSA/FSA card option\n Partner->>Truemed: create_payment_token request\n Truemed-->>Partner: redirect_url response\n Partner-->>User: Redirect to redirect_url\n User->>Truemed: Complete eligibility survey\n Note over User: User eligible for HSA/FSA\n Truemed-->>User: Show payment method form\n User->>Truemed: Enter HSA/FSA card details\n Note over User: Payment method stored\n Truemed->>Partner: payment_token_callback webhook\n Truemed-->>User: Redirect to success_url\n```\n\n\nThe webhook/callback is invoked at the same time the user is being redirected to the\n`success_url` - we don't guarantee that it will be called before the redirect.\n\n\n\n**The customer must be in the flow** when calling this endpoint, typically from within a\nsubscription management dashboard.\n\n\n**Primary Use Cases for this Endpoint:**\n\n- **Supporting existing customers**\n - You may have existing subscriptions customers that want to move their subscription over to\n their HSA/FSA card. Providing a \"use your HSA/FSA via Truemed\" button within a subscription\n management dashboard powered by this endpoint allows you to do that.\n- **Store payment method with Truemed**\n - Allow customers to add an HSA to their account for future use\n- **Free-trial support (non preferred)**\n - Allowing customers to qualify for a given subscription and store their payment info for\n future use.\n - \u26a0\ufe0f **We recommend using `create_payment_session` with `tokenize=True` for free trials** as\n outlined in the main subscription guide to reflect the fact that the customer is \"checking\n out\", though at no-cost.\n\n\nAll subscription related fields here are to enhance the customer experience, you'll need your\nown subscription management system.\n\n\n## Request Notes\n\n- **success_url** (Required): Where to redirect the user to after the customer successfully\n completes the tele-health survey and their payment method(s) have been stored.\n - This is often used to display a confirmation screen, or similar\n- **failure_url** (Required): When the user opts to not complete the tele-health survey or selects\n \"cancel\" during the process, or when the user is ineligible to spend HSA/FSA funds on the items\n in the request.\n - We attempt to recover from incorrect CVV, or other card detail errors by prompting the user\n for retry\n- **customer_state** (Optional): The 2-letter ISO 3166-2:US code for a region, without the `US-`\n prefix. For example, California should be provided as `CA` and Rhode Island as `RI`.\n - If `customer_state` is provided, the state of residence question in the health survey will be\n prefilled with the full state name that corresponds to the ISO code.\n- **metadata** (Optional): Will be echoed back in the\n [`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook and detail endpoint if present.\n - **Important**: This must be a string. If you want to include JSON, encode it as a string.\n - **Important**: DO NOT INCLUDE sensitive information in this field.\n- **use_iframe** (Optional): Optional query parameter that can be used to modify the response's\n `redirect_url` so it can be used and communicated with in an iframe.\n\n## iFrame Support\n\nIf `use_iframe` is set to `true`, `redirect_url` will be iframe-compatible. Partners can create\nan iframe and set the `src` to `redirect_url` and this will render Truemed's survey and checkout\nflow in the iframe.\n\nWhen using iframes, the flow completion is communicated via `postMessage`. The parent window\nshould listen for messages from the iframe. The message will contain:\n\n- **success**: Returns `true` if checkout flow was successful on Truemed's end, `false` if\n otherwise\n- **redirectUrl**: String that will be set to `success_url` from the original request body if\n `success` is `true` or set to `failure_url` if `success` is `false`.\n - Only need to be used if redirect is desired or can handle success and failure differently\n\n## Response Notes\n\n### Success Case\n\n**HTTP Status: 200:**\n\n- **provision_token_request_id**: A UUID that represents this creation request.\n - This ID is returned along with the provisioned `payment_token` in the\n [`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook.\n - You can query the status of this request using the\n [`retrieve_provision_token_request`](/api-reference/payment-tokens/retrieve-payment-token-provision-request) endpoint.\n- **redirect_url**: Contains a URI through which the customer can complete the `payment_token`.\n\n### Bad Request\n\n**HTTP Status: 400**\n\nIf a field is missing or the request otherwise can't be processed, we'll return a 400 with the\nfollowing fields:\n\n- **error**: Can be one of:\n - `MissingField`: One of the required fields is not present in the request\n - `IdempotencyViolation`: An `idempotency_key` was reused with different request parameters or\n the customer email specified in the request already has a payment token provisioned. Check to\n see if a [`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook was already received for\n this customer. To update, use the [`update_payment_token`](/api-reference/payment-tokens/update-payment-token)\n endpoint.\n - `WaitingForVerification`: If the lmn verification process has started, you cannot attempt to\n call this endpoint again for the same customer email. If you receive this error, please wait\n for the [`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook and then use the\n [`update_payment_token`](/api-reference/payment-tokens/update-payment-token) endpoint.\n - `ServerError`: There was an internal server error.\n - Requests can be retried as long as the `idempotency_key` is the same.\n - `ValidationError`: There was an issue with the request. Check the `message` field for the\n exact issue.\n- **message**: Detailed string explaining the reason for the failure.", "operationId": "createPaymentToken", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentTokenRequest" } } }, "description": "Request body for CreatePaymentTokenRequest", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentTokenResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "featurenotenabled": { "summary": "FeatureNotEnabled example", "value": { "error": "FeatureNotEnabled", "message": "Bad Request" } }, "idempotencyviolation": { "summary": "IdempotencyViolation example", "value": { "error": "IdempotencyViolation", "message": "The same idempotency key was used for different requests" } }, "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } }, "waitingforverification": { "summary": "WaitingForVerification example", "value": { "error": "WaitingForVerification", "message": "The lmn verification process is ongoing." } } }, "schema": { "properties": { "error": { "enum": [ "FeatureNotEnabled", "IdempotencyViolation", "TotalAmountInvalid", "ValidationError", "WaitingForVerification" ], "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "type": "object" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Page not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Create a payment token for recurring billing", "tags": [ "Payment Tokens" ] } }, "/api/v1/payment_tokens/{payment_token}": { "get": { "deprecated": false, "description": "Get data back for a given `payment_token`.\n\nThis endpoint returns details about the `payment_token` specified in the URL path.\nThis endpoint can be used to populate information on a user facing dashboard,\nsuch as the last 4 of the card(s) on file and the expiration dates.\n\nPartners should store expiration dates of cards on file and preemptively encourage\nusers to update their payment methods (using a call to\n[`update_payment_token`](/api-reference/payment-tokens/update-payment-token)) to avoid the failure scenarios\noutlined in our [subscriptions guide](/guides/subscriptions/subsequent-billing-periods).\n\n## Request Notes\n\n**Path Params:**\n- **payment_token** (Required): The `payment_token` string provided by the\n [`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook.", "operationId": "retrievePaymentToken", "parameters": [ { "deprecated": false, "description": "The payment token to get details for", "in": "path", "name": "payment_token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentTokenResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "invalidtoken": { "summary": "InvalidToken example", "value": { "error": "InvalidToken", "message": "Payment Token not found" } }, "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Resource not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Retrieve details of a stored payment token", "tags": [ "Payment Tokens" ] } }, "/api/v1/payment_tokens": { "get": { "deprecated": false, "description": "Lists all payment tokens created with the [`create_payment_token`](/api-reference/payment-tokens/create-payment-token)\nand [`create_payment_session`](/api-reference/payment-sessions/create-payment-session) endpoints.\n\nThis endpoint returns a paginated view of all payment tokens\nassociated with the API key used in the request header, sorted by their `created_at`\ndate in descending order. Optional search fields are provided to aid in finding the\ntoken or tokens associated with a given user.", "operationId": "listPaymentToken", "parameters": [ { "allowReserved": false, "deprecated": false, "description": "Optional field indicating which page to access. Defaults to 1.", "in": "query", "name": "page", "required": false, "schema": { "type": "integer" } }, { "allowReserved": false, "deprecated": false, "description": "Optional field indicating the number of records per page. Defaults to 30.", "in": "query", "name": "page_size", "required": false, "schema": { "type": "integer" } }, { "allowReserved": false, "deprecated": false, "description": "The email to search for. Partial matches supported, using 'includes' semantics.", "in": "query", "name": "email", "required": false, "schema": { "type": "string" } }, { "allowReserved": false, "deprecated": false, "description": "The name to search for. Partial matches supported, using 'includes' semantics.", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "allowReserved": false, "deprecated": false, "description": "Filter payment tokens with cards expiring on or before this month (YYYY-MM format, e.g., '2024-06')", "in": "query", "name": "card_expires_before", "required": false, "schema": { "type": "string" } }, { "allowReserved": false, "deprecated": false, "description": "Filter payment tokens with lmns expiring on or before this month (YYYY-MM-DD) format, e.g., '2024-06-15')", "in": "query", "name": "lmn_expires_before", "required": false, "schema": { "format": "date", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentTokenListResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Page not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "List payment tokens with filtering and pagination", "tags": [ "Payment Tokens" ] } }, "/api/v1/payment_tokens/{payment_token}/update": { "post": { "deprecated": false, "description": "Endpoint allowing your customers to update their payment method(s) and/or requalify\nafter a cart change.\n\n## Overview\n\nThe `update_payment_token` endpoint is available for partners to call when customers\nchange the items in their subscription or when they want to update their card(s) on\nfile.\n\nIf `update_card_info=False` and only the `order_items` are being updated, the user\n**may or may not need to retake the tele-health survey** depending on a variety of\nfactors. The `next_action` field in the response body will indicate what the customer\nmust do next, and a `redirect_url` will be provided if the customer needs to take action.\n\nIf you call this endpoint and the `next_action` is not `None`, and a `redirect_url` is\npresent, we don't guarantee you can invoke\n[`create_payment_session`](/api-reference/payment-sessions/create-payment-session) with the `payment_token` until the user\nhas completed the action and you've received the\n[`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook.\n\n\nThe customer must be in the flow when calling this endpoint, typically from within a\nsubscription management dashboard.\n\n\n**Primary Use Cases for this Endpoint:**\n\n- Allowing customers to update their card(s) on file with Truemed\n- Ensuring that the user is still eligible to use their HSA/FSA after a cart/subscription\n change.\n - If the customer must requalify by retaking the tele-health survey, the `next_action`\n will be `HealthSurvey`, which can be taken by redirecting the customer to the\n `redirect_url`.\n\n\nAll subscription related fields here are to enhance the customer experience, a dedicated\nsubscription management system is needed on the partner's side.\n\n\nThe diagram below outlines the customer flow when using this endpoint:\n\n\n \n Partner invokes `update_payment_token` triggered by a customer action. The customer is either updating their payment method(s) or has made a change to the items in their subscription.\n \n \n The partner redirects the customer to the `redirect_url` if `next_action` is not `None`. The customer completes the required action on Truemed's site.\n \n \n The customer is redirected to the `success_url` upon completion of the next action on Truemed's site.\n \n \n Truemed issues a [`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook indicating that the `payment_token` has been updated.\n \n\n\n```mermaid\nsequenceDiagram\n participant User\n participant Partner\n participant Truemed\n\n User->>Partner: Update payment method or cart\n Partner->>Truemed: update_payment_token request\n Truemed-->>Partner: redirect_url response\n Partner-->>User: Redirect to redirect_url (if needed)\n User->>Truemed: Complete survey or update card\n Note over User: User eligible or card updated\n Truemed->>Partner: payment_token_updated webhook\n Truemed-->>User: Redirect to success_url\n```\n\n\nThe webhook/callback is invoked at the same time the user is being redirected\nto the `success_url` - we don't guarantee that it will be called before the redirect.\n\n\n## Request Notes\n\n- **update_card_info** (Optional): boolean - Indicates if this request is to update the\n card(s) on file.\n - If set to `True`, the response will always include `redirect_url` so the user can\n update their payment method(s) on file with Truemed.\n- **order_items** (Optional): An array of `order_item` objects, each with the following\n fields:\n - **name** (Required): string - the name of the item.\n - **sku** (Required): sku - the SKU or id for this product.\n - **NOTES**: This should only be supplied when the user is changing the items associated\n with a given subscription\n- **success_url** (Required): Where to redirect the user to after the customer successfully\n completes the tele-health survey and/or updates their payment method(s).\n - This is often used to display a confirmation screen, or similar\n- **failure_url** (Required): When the user opts to not complete the tele-health survey or\n selects \"cancel\" during the process, or when the user is ineligible to spend HSA/FSA funds\n on the items in the request.\n - We attempt to recover from incorrect CVV, or other card detail errors by prompting the\n user for retry\n- **use_iframe** (Optional): Optional query parameter that can be used to modify the\n response's `redirect_url` so it can be used and communicated with in an iframe.\n- **metadata** (Optional): Any additional data supplied by the partner. This will be echoed\n back in the `payment_token_updated` webhook after the `update_payment_token` flow is\n complete.\n - **Important**: This must be a string. If you want to include JSON, encode it as a string.\n - **Important**: DO NOT INCLUDE sensitive information in this field.\n\n## iFrame Support\n\nIf `use_iframe` is set to `true`, `redirect_url` will be iframe-compatible. Partners can\ncreate an iframe and set the `src` to `redirect_url` and this will render Truemed's survey\nand checkout flow in the iframe.\n\nWhen using iframes, the flow completion is communicated via `postMessage`:\n\n- **success** - Returns `true` if checkout flow was successful on Truemed's end, `false` if\n otherwise\n- **redirectUrl** - string that will be set to `success_url` from the original request body\n if `success` is `true` or set to `failure_url` if `success` is `false`. Only need to be\n used if redirect is desired or can handle success and failure differently.\n\n## Response Notes\n\n### Success Case\n\n**HTTP Status: 200:**\n\n- **next_action**: The action the customer must take. Can be one of the following:\n - `UpdatePaymentMethod`: Customer must enter a new payment method.\n - `HealthSurvey`: Customer must take the health survey\n - `None`: There is no other action needed at this time.\n- **redirect_url**: Contains a URI through which the customer can complete the\n `payment_token`. If `next_action=None`, this field won't be present.\n\n### Bad Request\n\n**HTTP Status: 400**\n\nIf a field is missing or the request otherwise can't be processed, we'll return a 400 with\nthe following fields:\n\n- **error**: Can be one of:\n - `MissingField`: One of the required fields is not present in the request\n - `IdempotencyViolation`: An `idempotency_key` was reused with different request parameters\n - `ServerError`: There was an internal server error.\n - Requests can be retried as long as the `idempotency_key` is the same.\n - `InvalidToken`: The requested token was not found\n - `IneligibleItemAdded`: A new item is ineligible for HSA/FSA spend. Can be returned when\n requesting to update the items associated with a customer's `payment_token`\n- **message**: Indication of one of the following:\n - Which field was missing\n - Details on how the total amount was invalid", "operationId": "updatePaymentToken", "parameters": [ { "deprecated": false, "description": "The payment token to update", "in": "path", "name": "payment_token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePaymentTokenRequest" } } }, "description": "Request body for UpdatePaymentTokenRequest", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePaymentTokenResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "featurenotenabled": { "summary": "FeatureNotEnabled example", "value": { "error": "FeatureNotEnabled", "message": "Bad Request" } }, "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "invalidtoken": { "summary": "InvalidToken example", "value": { "error": "InvalidToken", "message": "Payment Token not found" } }, "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Resource not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Update metadata on a stored payment token", "tags": [ "Payment Tokens" ] } }, "/api/v1/payment_tokens/{payment_token}/delete": { "post": { "deprecated": false, "description": "Invoke this endpoint to invalidate a `payment_token`.\n\nThe delete endpoint removes the `payment_token` after which the token will no longer\nwork for calls to [`create_payment_session`](/api-reference/payment-sessions/create-payment-session).\n\nThe request body should be empty.\n\n\n## Response Notes\n\n### Success Case\n\n**HTTP Status: 204** - No content is returned on successful deletion.\n\n### Error Cases\n\n**HTTP Status: 404** - If the `payment_token` is not found or does not belong to the\nrequesting sales channel.", "operationId": "deletePaymentToken", "parameters": [ { "deprecated": false, "description": "The payment token to delete.", "in": "path", "name": "payment_token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentTokenDeleteResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "featurenotenabled": { "summary": "FeatureNotEnabled example", "value": { "error": "FeatureNotEnabled", "message": "Bad Request" } }, "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Resource not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Delete a stored payment token and its associated methods", "tags": [ "Payment Tokens" ] } }, "/api/v1/payment_tokens/provision_request/{provision_token_request_id}": { "get": { "deprecated": false, "description": "Check the status of a [`create_payment_token`](/api-reference/payment-tokens/create-payment-token)\nor [`update_payment_token`](/api-reference/payment-tokens/update-payment-token) API calls.\n\nThe `retrieve_provision_token_request` endpoint returns details about the request to\ncreate or update a `payment_token`. This endpoint is only provided as a fall back to\nthe [`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook and is only necessary\nfor as fallback for the [`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook.\n\n## Request Notes\n\n**Path Params:**\n- **provision_token_request_id** (Required): The `provision_token_request_id` string\n returned by Truemed to the partner either:\n - in response to a [`create_payment_token`](/api-reference/payment-tokens/create-payment-token) request\n - in a response to a [`update_payment_token`](/api-reference/payment-tokens/update-payment-token) request\n\n## Response Notes\n\n### Success Case\n\n**HTTP Status: 200**\n\n- **payment_token** (Optional): string - the `payment_token` created as part of the\n `provision_request`, if one exists. Null otherwise.\n - Use the [`retrieve_payment_token`](/api-reference/payment-tokens/retrieve-payment-token) endpoint to get\n more information on the token.\n- **metadata**: (Optional) - returned if supplied in the call to\n [`create_payment_token`](/api-reference/payment-tokens/create-payment-token).", "operationId": "retrievePaymentTokenProvisionRequest", "parameters": [ { "deprecated": false, "description": "The ID of a ProvisionTokenRequest returned via create_payment_token", "in": "path", "name": "provision_token_request_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentTokenProvisionRequestDetailResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "featurenotenabled": { "summary": "FeatureNotEnabled example", "value": { "error": "FeatureNotEnabled", "message": "Bad Request" } }, "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Provision request not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Retrieve the status of a payment token provision request", "tags": [ "Payment Tokens" ] } }, "/api/v1/qualification_session/{qualification_session_id}/transactions/create": { "post": { "deprecated": false, "description": "**DRAFT**\n\nRecord a captured network transaction against a qualification session whose Letter of Medical Necessity (LMN) has already been issued. Submit the captured cart, card-presentment details, and your merchant-side transaction identifier \u2014 Truemed confirms the transaction is covered by the session's LMN, schedules the resulting fee onto your next monthly Truemed invoice, and shortly after generates a customer receipt (delivered by email and surfaced in the customer's Truemed dashboard).\n\nUse this for the merchant-reported transaction (MRT) flow, where you run the HSA/FSA charge on your own payment rail (rather than Truemed's Stripe rail) and report the captured transaction to Truemed directly. Multiple MRTs may be reported against the same qualification session \u2014 each is billed independently, with the fee assessed against the lesser of the qualification session's amount and the reported transaction total.\n\n## Idempotency\n\nIdempotency is scoped per sales channel by the `merchant_transaction_id` field. Re-submitting a request with the same `merchant_transaction_id` against the same sales channel returns the originally recorded transaction without creating a duplicate.\n\n## Error Codes\n\nThe following business-rule error codes may be returned in the error response body once full enforcement lands. They are documented here in advance so you can plan customer-facing UX:\n\n- `lmn_not_verified` \u2014 The Letter of Medical Necessity backing this qualification session has not yet been verified.\n- `lmn_expired` \u2014 The LMN's validity window has lapsed.\n- `items_not_covered_by_existing_lmn` \u2014 One or more submitted `order_items` fall outside the LMN's covered eligibility categories.\n- `mrt_introduces_new_eligible_ec` \u2014 The submitted cart introduces an eligibility category not present on the original LMN.\n- `mrt_contains_ineligible_ec` \u2014 The submitted cart contains an ineligible eligibility category.\n\nFull enforcement of these codes lands with the complete Truemed-side implementation in a follow-up phase.", "operationId": "createMerchantReportedTransaction", "parameters": [ { "deprecated": false, "description": "The qualification session ID from the URL path.", "in": "path", "name": "qualification_session_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMerchantReportedTransactionRequest" } } }, "description": "Request body for CreateMerchantReportedTransactionRequest", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMerchantReportedTransactionResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Qualification session not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "DRAFT: Record a captured HSA/FSA transaction against a qualification session", "tags": [ "Qualification Sessions" ] } }, "/api/v1/qualification_sessions/create": { "post": { "deprecated": false, "description": "DRAFT: Pre-screen a returning shopper for HSA/FSA eligibility before checkout. Pass your\nown stable identifier for the customer so repeat shoppers skip qualification once they're\napproved. Redirect the consumer to `redirect_url` to complete the survey, or honor\n`is_already_qualified=true` to bypass it entirely.\n\n## Representing cart-wide amounts on line items\n\nCart-wide concepts like shipping, tax, and order-level promo codes have no top-level field \u2014\nallocate them across your line items inside each item's `amount_details`, then set\n`display_level` to control how each one renders on a Truemed-generated receipt. Allocating up\nfront keeps the breakdown unambiguous when a cart mixes qualifying and non-qualifying items.\n\nFor example, a \\$10 shipping fee that belongs to the whole order and a \\$5 gift-wrap charge\nthat applies only to one item are both sent on that line item, but tagged differently so the\nreceipt shows shipping as a single order-level row and gift wrap inline with its item:\n\n```json\n{\n \"order_items\": [\n {\n \"name\": \"Item A\",\n \"quantity\": 1,\n \"price\": 5500,\n \"sku\": \"item-a\",\n \"amount_details\": {\n \"total_additional_charges\": 1500,\n \"additional_charges_details\": [\n {\"name\": \"Shipping\", \"amount\": 1000, \"display_level\": \"order\"},\n {\"name\": \"Gift Wrap\", \"amount\": 500, \"display_level\": \"line_item\"}\n ]\n }\n }\n ]\n}\n```", "operationId": "createQualificationSession", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQualificationSessionRequest" } } }, "description": "Request body for CreateQualificationSessionRequest", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQualificationSessionResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Page not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "DRAFT: Pre-screen a customer for HSA/FSA eligibility", "tags": [ "Qualification Sessions" ] } }, "/api/v1/qualification_session/{qualification_session_id}": { "get": { "deprecated": false, "description": "Get the status of a `qualification_session` based on the `qualification_session_id`.\n\n## Request Notes\n\nTo get the status of a Qualification Session object, call the detail view with the ID\nof the qualification session returned by the\n[Qualification Session Completed](/api-reference/qualification-sessions/qualification-status-updated-webhook)\nwebhook.", "operationId": "retrieveQualificationSession", "parameters": [ { "deprecated": false, "description": "The qualification session ID from the URL path", "in": "path", "name": "qualification_session_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QualificationSessionResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Qualification session not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Retrieve details and eligibility result of a qualification session", "tags": [ "Qualification Sessions" ] } }, "/api/v1/qualification_sessions": { "get": { "deprecated": false, "description": "Returns a paginated view of all Qualification Sessions associated with the API key used\nin the request header, sorted by their `created_at` date. Optional search fields are provided\nto aid in finding the session or sessions associated with a given user.\n\n## Request Notes\n\nQuery Params:\n\n- `status` (Optional): filter Qualification Sessions by status. The supported values\n and their meanings are listed in the parameter's description below.\n- `page` (Optional): int - the page to retrieve, defaults to 1. 30 entries are\n returned per page.\n\n## Response Notes\n\n### Bad Request\n\nHTTP Status: 400\n\nIf a field is missing or the request otherwise can't be processed, we'll return a 400 with\nthe following fields:\n\n- **error**: Can be one of:\n - `ValidationError`: invalid request\n- **message**: Details on how the request was invalid", "operationId": "listQualificationSession", "parameters": [ { "allowReserved": false, "deprecated": false, "description": "Optional field indicating which page to access. Defaults to 1.", "in": "query", "name": "page", "required": false, "schema": { "type": "integer" } }, { "allowReserved": false, "deprecated": false, "description": "Optional field indicating the number of records per page. Defaults to 30.", "in": "query", "name": "page_size", "required": false, "schema": { "type": "integer" } }, { "allowReserved": false, "deprecated": false, "description": "An optional user_id to search for.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "allowReserved": false, "deprecated": false, "description": "An optional filter to only return sessions with the given status. One of:\n- `pending` \u2014 The session was created; the shopper hasn't completed the survey yet.\n- `processing` \u2014 The shopper completed the survey and it is under review.\n- `approved` \u2014 The shopper holds a valid Letter of Medical Necessity covering the items in this order.\n- `rejected` \u2014 The shopper is ineligible for a Letter of Medical Necessity for the items in this order.", "in": "query", "name": "status", "required": false, "schema": { "type": "string" } }, { "allowReserved": false, "deprecated": false, "description": "Filter by expiration date (YYYY-MM-DD format)", "in": "query", "name": "expires_at", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "allowReserved": false, "deprecated": false, "description": "Search across user name, email, user_business_id, utm, and external_user_id fields.", "in": "query", "name": "search", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QualificationSessionListResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Page not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "List qualification sessions with filtering and pagination", "tags": [ "Qualification Sessions" ] } }, "/api/v1/qualification_session/{qualification_session_id}/update": { "post": { "deprecated": false, "description": "Keep a qualification session in sync with your own records after you've created it. Attach your internal user identifier, store free-form metadata, and adjust the redirect URLs a customer returns to once they finish qualifying.\n\n## Request Notes\n\n- `idempotency_key` makes retries safe: a duplicate POST with the same key against the same qualification session is deduplicated and returns the original response, while reusing a key with a different payload returns a `400` validation error.\n- `user_id` is set-when-null only: you can supply it while the qualification session has no `user_id` yet, but attempting to overwrite a non-null value returns the documented `user_id_already_set` error code. Stale-value corrections must route through Truemed support, not this endpoint.\n- `metadata` is a JSON-encoded string echoing the same convention used by the create endpoint.\n- `success_url` and `failure_url` are still stored when supplied, but have no effect once the qualification session reaches a terminal status (`approved` / `rejected`) \u2014 the customer has already completed the flow and won't be redirected again.\n\n## Response Notes\n\n- `status` is a read-only passthrough \u2014 qualification-session status is never mutable via this endpoint. Status changes occur through the survey-submission and LMN-clinical-review flows.", "operationId": "updateQualificationSession", "parameters": [ { "deprecated": false, "description": "The qualification session ID from the URL path.", "in": "path", "name": "qualification_session_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateQualificationSessionRequest" } } }, "description": "Request body for UpdateQualificationSessionRequest", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateQualificationSessionResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "badrequest": { "summary": "BadRequest example", "value": { "error": "BadRequest", "message": "IDEMPOTENCY_VIOLATION" } }, "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Qualification session not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Update mutable fields on a qualification session", "tags": [ "Qualification Sessions" ] } }, "/api/v1/qualification_session/{qualification_session_id}/auth_hold": { "post": { "deprecated": false, "description": "BETA: Places a merchant-side auth hold on a qualification session and begins Truemed-side LMN clinical review.", "operationId": "createQualificationSessionAuthHold", "parameters": [ { "deprecated": false, "description": "The qualification session ID from the URL path.", "in": "path", "name": "qualification_session_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQualificationSessionAuthHoldRequest" } } }, "description": "Request body for CreateQualificationSessionAuthHoldRequest", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQualificationSessionAuthHoldResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "badrequest": { "summary": "BadRequest example", "value": { "error": "BadRequest", "message": "IDEMPOTENCY_VIOLATION" } }, "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Qualification session not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "409": { "content": { "application/json": { "examples": { "conflict": { "summary": "Conflict example", "value": { "error": "Conflict", "message": "merchant_auth_hold_id_in_use" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Conflict" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "BETA: Place an auth hold on a qualification session to begin clinical review", "tags": [ "Qualification Sessions" ] } }, "/api/v1/product_catalog/items/list": { "get": { "deprecated": false, "description": "Lists catalog items for the authenticated merchant, including current HSA/FSA eligibility for each item.\n\nThis endpoint is intended to complement the `Item Eligibility Updated` webhook: use the webhook to receive ongoing updates, and use this endpoint to enumerate items that were already categorized before webhook ingestion began (or to reconcile after a gap).\n\nUse `eligibility` to scope the response to a specific eligibility state, and `updated_after` to incrementally sync only items changed since the last poll.", "operationId": "listCatalogItems", "parameters": [ { "allowReserved": false, "deprecated": false, "description": "Optional field indicating which page to access. Defaults to 1.", "in": "query", "name": "page", "required": false, "schema": { "type": "integer" } }, { "allowReserved": false, "deprecated": false, "description": "Optional field indicating the number of records per page. Defaults to 30.", "in": "query", "name": "page_size", "required": false, "schema": { "type": "integer" } }, { "allowReserved": false, "deprecated": false, "description": "Filter results to items whose eligibility matches the given value. Items that have not been reviewed yet are excluded when this filter is set.", "in": "query", "name": "eligibility", "required": false, "schema": { "type": "string" } }, { "allowReserved": false, "deprecated": false, "description": "Return only catalog items whose last update is at or after this ISO 8601 timestamp. Useful for incremental sync after `Item Eligibility Updated` webhooks.", "in": "query", "name": "updated_after", "required": false, "schema": { "format": "date-time", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListItemsResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Page not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "List catalog items with eligibility and pagination", "tags": [ "Product Catalog" ] } }, "/api/v1/product_catalog/truemed_checkout_method": { "post": { "deprecated": false, "description": "This endpoint is intended to be used to make yes/no decisions about whether to display Truemed as a checkout option for a given set of items. It is limited in that it does not determine whether or not an order containing the items will truly be eligible for Truemed checkout because it does not receive prices, discounts nor additional charges. Any new items received will be created and subsequently categorized.", "operationId": "truemedCheckoutMethod", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TruemedCheckoutMethodRequest" } } }, "description": "Request body for TruemedCheckoutMethodRequest", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TruemedCheckoutMethodResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Page not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Check if Truemed checkout is available for a cart", "tags": [ "Product Catalog" ] } }, "/api/v1/product_catalog/items/create": { "post": { "deprecated": false, "description": "Create a catalog item. The product will not be immediately categorized.", "operationId": "createItem", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateItemRequest" } } }, "description": "Request body for CreateItemRequest", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateItemResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Page not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "409": { "content": { "application/json": { "examples": { "conflict": { "summary": "Conflict example", "value": { "error": "Conflict", "message": "Catalog Item with this SKU already exists." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Conflict" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Create a new item in the product catalog", "tags": [ "Product Catalog" ] } }, "/api/v1/product_catalog/items/update": { "post": { "deprecated": false, "description": "Update an item in the product catalog. The product will not be immediately re-categorized.", "operationId": "updateItem", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateItemRequest" } } }, "description": "Request body for UpdateItemRequest", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateItemResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "No catalog item found with the provided SKU." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Update an existing item in the product catalog", "tags": [ "Product Catalog" ] } }, "/api/v1/product_catalog/items/detail": { "post": { "deprecated": false, "description": "Retrieve details of a catalog item by SKU.", "operationId": "getItemDetail", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailItemRequest" } } }, "description": "Request body for DetailItemRequest", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailItemResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Page not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Retrieve details and eligibility status of a catalog item", "tags": [ "Product Catalog" ] } }, "/api/v1/reconciliation/payouts": { "get": { "deprecated": false, "description": "Returns a paginated list of payouts for the authenticated merchant within the specified date range.", "operationId": "listPayoutReconciliation", "parameters": [ { "allowReserved": false, "deprecated": false, "description": "Optional field indicating which page to access. Defaults to 1.", "in": "query", "name": "page", "required": false, "schema": { "type": "integer" } }, { "allowReserved": false, "deprecated": false, "description": "Number of results per page. Defaults to 30. Maximum 1000.", "in": "query", "name": "page_size", "required": false, "schema": { "type": "integer" } }, { "allowReserved": false, "deprecated": false, "description": "Start of the date range, inclusive (YYYY-MM-DD).", "in": "query", "name": "start_date", "required": true, "schema": { "format": "date", "type": "string" } }, { "allowReserved": false, "deprecated": false, "description": "End of the date range, inclusive (YYYY-MM-DD).", "in": "query", "name": "end_date", "required": true, "schema": { "format": "date", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutReconciliationListResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Page not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "List reconciliation payouts", "tags": [ "Reconciliations" ] } }, "/api/v1/reconciliation/transactions": { "get": { "deprecated": false, "description": "Returns a paginated list of transaction reconciliation data for the authenticated merchant within the specified date range.", "operationId": "listTransactionReconciliation", "parameters": [ { "allowReserved": false, "deprecated": false, "description": "Optional field indicating which page to access. Defaults to 1.", "in": "query", "name": "page", "required": false, "schema": { "type": "integer" } }, { "allowReserved": false, "deprecated": false, "description": "Optional field indicating the number of records per page. Defaults to 30.", "in": "query", "name": "page_size", "required": false, "schema": { "type": "integer" } }, { "allowReserved": false, "deprecated": false, "description": "Start of the date range, inclusive (YYYY-MM-DD).", "in": "query", "name": "start_date", "required": true, "schema": { "format": "date", "type": "string" } }, { "allowReserved": false, "deprecated": false, "description": "End of the date range, inclusive (YYYY-MM-DD).", "in": "query", "name": "end_date", "required": true, "schema": { "format": "date", "type": "string" } }, { "allowReserved": false, "deprecated": false, "description": "Comma-separated payout IDs to filter by, e.g. po_1,po_2.", "explode": false, "in": "query", "name": "payout_ids", "required": false, "schema": { "items": { "type": "string" }, "type": "array" }, "style": "form" }, { "allowReserved": false, "deprecated": false, "description": "When true (default), include transactions not yet associated with a payout. When false, return only rows with an associated payout.", "in": "query", "name": "include_pending_payouts", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionReconciliationListResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Page not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "List reconciliation transaction rows", "tags": [ "Reconciliations" ] } } }, "webhooks": { "paymentsessioncompleted": { "post": { "deprecated": false, "description": "The partner is required to implement an endpoint that Truemed can send requests to inform\nof the checkout status.\n\nWe'll call the `payment_session_complete` webhook once each time the `status` of the\n`payment_session` changes, including sessions that have been canceled, voided, and captured.\nFor delayed capture, we'll issue the webhook call for authorization (when the customer first\nsuccessfully enters card information), and again after the partner has manually captured funds\nvia the capture api.\n\nIn successful payment cases, we'll first issue a webhook indicating that the `payment_session`\nhas transition from `pending` to `processing`, after which you can expect a webhook\ntransitioning from `processing` to `captured` (in the default / immediate capture cases), and\nto `authorized` in the case of [Manual/Delayed Capture](/guides/payment-sessions/manual-delayed-capture).\n\n\nOrders should not be fulfilled until a webhook is received with a status\nof `captured`.\n\n\n**Authentication**: Partners should verify the request comes from Truemed by checking that\nthe API key is present in the `x-truemed-api-key` HTTP header.\n\n## Request Notes\n\nHeaders:\n\n- `x-truemed-api-key` - The partner's API key.\n\nNotable fields:\n\n- `status` - the status of the payment from Truemed's perspective\n - `captured` - payment has completed\n - `canceled` - payment was canceled before the user entered payment information via a call\n to our cancel API.\n - `pending` - payment has not been successfully completed yet.\n - `processing` - the customer has entered their payment information, but it is under review\n by Truemed\n - Any customer facing communication should indicate successful payment at this point,\n such as on the `success_url`.\n - The merchant should not fulfill the order until the Payment Session Webhook indicates\n that the payment has been captured.\n - `rejected` - While in the `processing` state, Truemed reviewed and rejected the payment\n session.\n - The merchant should not fulfill these orders, and should communicate failure to the\n user via email.\n - `authorized` - an auth hold has been placed on the customer's card.\n - `authorization_voided` - the auth hold has been voided via a call to our Void Session api.\n - `authorization_expired` - the auth hold has expired and we were not able to re-auth the\n transaction. This state is only possible after a call to our Manual Capture api, and is\n only set after we attempt a re-auth hold on the existing payment method.\n- `capture_amount` **(Optional)** - the amount of funds actually captured.\n - For payment sessions of `kind=one_time_payment` this field will always be present and\n will be the same as `authorize_amount`.\n - For payment sessions of `kind=authorization` this field will not be present until the\n funds have been captured (via a call to Manual Capture).\n- `order_items` - a list of order items, with the following fields per item:\n - `total_refundable` **(Optional)** - If the Payment Session has been captured, this value\n will be the remaining amount refundable for this item. Otherwise it will not be included.\n - `quantity_refundable` **(Optional)** - If the Payment Session has been captured, this\n value will be the remaining quantity refundable for this item. Otherwise it will not be\n included.\n - `total_capturable` **(Optional)** - If the Payment Session is an authorization and is\n currently authorized, this value will be the remaining amount capturable for this item.\n Otherwise it will not be included.\n - `quantity_capturable` **(Optional)** - If the Payment Session is an authorization and is\n currently authorized, this value will be the remaining quantity capturable for this item.\n Otherwise it will not be included.\n- `payment_token` **(Optional)** - Optional string indicating the `payment_token` used for\n the payment session. This field will be set only if the partner provided `tokenize=True` or\n a `payment_token` in the `create_payment_session` request, as outlined in our Subscriptions\n Flow\n\n## Response Body Documentation\n\n### Success Case\n\nHTTP Status: `204`\n\nThe partner does not need to include any content in the body\n\n### Failure Case\n\nTruemed will retry the requests to your backend with backoff for up to 7 days", "operationId": "paymentSessionCompletedWebhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusUpdateWebhookPayload" } } }, "description": "Webhook payload for paymentsessioncompleted", "required": true }, "responses": { "204": { "description": "Webhook received successfully (HTTP 204 No Content)" }, "400": { "description": "Invalid payload or authentication failure" }, "500": { "description": "Server error processing webhook" } }, "security": [ { "truemed-api-key-webhook": [] } ], "summary": "Payment Session Complete Webhook", "tags": [ "Payment Sessions" ] } }, "paymenttokenupdated": { "post": { "deprecated": false, "description": "The partner is required to implement an endpoint that Truemed requests to inform the partner\nof updates made to payment tokens which back customer subscriptions.\n\nThe `payment_token_updated` webhook is invoked when:\n\n1. A `payment_token` is provisioned using [`create_payment_session`](/api-reference/payment-sessions/create-payment-session)\n2. A customer updates their payment token due to one of the failure cases outlined in the\n subscriptions guide, or as part of [`update_payment_token`](/api-reference/payment-tokens/update-payment-token)\n3. A `payment_token` is provisioned using [`create_payment_token`](/api-reference/payment-tokens/create-payment-token)\n\nThe request body includes the `payment_token`, and one of 3 optional IDs mapping back to the\noriginating entity (`payment_session_id`, `failed_payment_session_id`, or\n`provision_token_request_id`).\n\nOnce you receive this webhook, the `payment_token` can successfully be used in subsequent\ncalls to [`create_payment_session`](/api-reference/payment-sessions/create-payment-session).\n\n**Authentication**: Partners should verify the request comes from Truemed by checking that\nthe API key is present in the `x-truemed-api-key` HTTP header.\n\n## Request Notes\n\n- `payment_token`: the `payment_token` returned to the partner by Truemed in response to a\n [`create_payment_session`](/api-reference/payment-sessions/create-payment-session) request\n when `tokenize` was set to `True`\n- `payment_session_id`: **(Optional)** the `id` of the `payment_session` returned by\n `create_payment_session`\n - This is used if the `payment_token` was provisioned as part of a `create_payment_session`\n with `tokenize=true`.\n- `failed_payment_session_id`: **(Optional)** the `id` returned to the partner by Truemed in\n response to a `create_payment_session` request\n - Only present if the `payment_token` was used in [`create_payment_session`](/api-reference/payment-sessions/create-payment-session)\n and failed to be charged as outlined in the failure cases in the [Subscriptions Guide](/guides/subscriptions/overview).\n- `provision_token_request_id`: **(Optional)**\n - Present when provisioning/updating a `payment_token` with a call to\n [`create_payment_token`](/api-reference/payment-tokens/create-payment-token) or\n [`update_payment_token`](/api-reference/payment-tokens/update-payment-token)\n\n## Response Notes\n\n### Success Case\n\nHTTP Status: `204`\n\nThe partner does not need to include any content in the body, but MUST respond with `204`.\n\n### Failure Case\n\nTruemed will retry the requests to your backend with backoff for up to 7 days", "operationId": "paymentTokenUpdatedWebhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentTokenUpdatedWebhookPayload" } } }, "description": "Webhook payload for paymenttokenupdated", "required": true }, "responses": { "204": { "description": "Webhook received successfully (HTTP 204 No Content)" }, "400": { "description": "Invalid payload or authentication failure" }, "500": { "description": "Server error processing webhook" } }, "security": [ { "truemed-api-key-webhook": [] } ], "summary": "Payment Token Updated Webhook", "tags": [ "Payment Tokens" ] } }, "productcatalogitemeligibilityupdated": { "post": { "deprecated": false, "description": "The partner can implement an endpoint that Truemed calls when the HSA/FSA eligibility status\nof an item changes.\n\nThis webhook is triggered when:\n\n1. An item's eligibility is updated (e.g., from `ineligible` to `eligible_with_lmn`)\n2. An item is reviewed and its eligibility status is determined\n\n**Authentication**: Partners should verify the request comes from Truemed by checking that\nthe `x-truemed-api-key` HTTP header matches their API key.\n\n## Request Notes\n\nThe webhook payload follows an envelope structure:\n\n- `event_type` - The event type identifier: `product_catalog.item.eligibility_updated`\n- `timestamp` - ISO-8601 timestamp of when the event occurred\n- `data.object` - The item details including:\n - `sku` - The SKU of the item\n - `name` - The name of the item\n - `eligibility` - The HSA/FSA eligibility status:\n - `eligible` - Item is default eligible for HSA/FSA\n - `eligible_with_lmn` - Item is eligible with a Letter of Medical Necessity\n - `ineligible` - Item is not eligible for HSA/FSA\n - `reviewed_at` - ISO-8601 timestamp of when the item was last reviewed\n\n## Response Notes\n\n### Success Case\n\nHTTP Status: `204`\n\nThe partner does not need to include any content in the body.\n\n### Failure Case\n\nTruemed will retry the requests to your backend with backoff for up to 7 days", "operationId": "productCatalogItemEligibilityUpdatedWebhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCatalogItemEligibilityUpdatedWebhookPayload" } } }, "description": "Webhook payload for productcatalogitemeligibilityupdated", "required": true }, "responses": { "204": { "description": "Webhook received successfully (HTTP 204 No Content)" }, "400": { "description": "Invalid payload or authentication failure" }, "500": { "description": "Server error processing webhook" } }, "security": [ { "truemed-api-key-webhook": [] } ], "summary": "Item Eligibility Updated Webhook", "tags": [ "Product Catalog" ] } }, "qualificationsessionprocessing": { "post": { "deprecated": false, "description": "The partner can implement an endpoint that Truemed calls the moment a `qualification_session`\nbecomes externally visible as `processing` \u2014 i.e., when a pending Letter-of-Medical-Necessity\nverification has been created and tied to the session.\n\n**Authentication**: Partners should verify the request comes from Truemed by checking that\nthe API key is present in the `x-truemed-api-key` HTTP header.\n\n## Request Notes\n\n- `event` - The wire-type discriminator: `qualification_session.processing`\n- `qualification_session_id` - The `qualification_session_id` returned by Truemed at session\n creation.\n- `sales_channel_id` - The id of the sales channel the qualification session belongs to.\n- `metadata`: **(Optional)** - JSON-encoded string echoing whatever metadata the merchant\n supplied at qualification-session creation. `null` if none was supplied.\n\n## Response Notes\n\n### Success Case\n\nHTTP Status: `204`\n\nThe partner does not need to include any content in the body.\n\n### Failure Case\n\nTruemed will retry the requests to your backend with backoff for up to 7 days", "operationId": "qualificationSessionProcessingWebhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QualificationSessionProcessingWebhookPayload" } } }, "description": "Webhook payload for qualificationsessionprocessing", "required": true }, "responses": { "204": { "description": "Webhook received successfully (HTTP 204 No Content)" }, "400": { "description": "Invalid payload or authentication failure" }, "500": { "description": "Server error processing webhook" } }, "security": [ { "truemed-api-key-webhook": [] } ], "summary": "Qualification Session Processing Webhook", "tags": [ "Qualification Sessions" ] } }, "qualificationstatusupdated": { "post": { "deprecated": false, "description": "The partner is required to implement an endpoint that Truemed requests to inform the partner\nof the `qualification_session` status.\n\nThe `qualification_session_complete` webhook will only be called once for each qualification\nsession, on status change to `approved`, or `rejected`.\n\n**Authentication**: Partners should verify the request comes from Truemed by checking that\nthe API key is present in the `x-truemed-api-key` HTTP header.\n\n## Request Notes\n\n- `status` - the status of the qualification session, an enum with one of the following\n values:\n - `pending` - the user hasn't has not completed the survey\n - `processing` - the user has completed the session and it is under review\n - `approved` - the user has been issued a Letter-of-Medical-Necessity\n - `rejected` - the user is ineligible to receive a Letter-of-Medical-Necessity\n- `expires_at`: **(Optional)** - the datetime at which the Letter-of-Medical-Necessity expires\n - If the Letter-of-Medical-Necessity hasn't been issued, this field will be `null`.\n- `user_id`: **(Optional)** - the `user_id` provided in the qualification session redirect\n URL param\n - This field will be `null` if `user_id` wasn't provided in the URL for creation.\n- `source`: **(Optional)** - the `source` provided in the qualification session redirect URL\n param\n - This field will be `null` if `source` wasn't provided in the URL for creation.\n\n## Response Notes\n\n### Success Case\n\nHTTP Status: `204`\n\nThe partner does not need to include any content in the body.\n\n### Failure Case\n\nTruemed will retry the requests to your backend with backoff for up to 7 days", "operationId": "qualificationStatusUpdatedWebhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QualificationSessionStatusUpdatedWebhookPayload" } } }, "description": "Webhook payload for qualificationstatusupdated", "required": true }, "responses": { "204": { "description": "Webhook received successfully (HTTP 204 No Content)" }, "400": { "description": "Invalid payload or authentication failure" }, "500": { "description": "Server error processing webhook" } }, "security": [ { "truemed-api-key-webhook": [] } ], "summary": "Qualification Session Complete Webhook", "tags": [ "Qualification Sessions" ] } } }, "components": { "schemas": { "Address": { "properties": { "city": { "description": "City for address", "title": "City", "type": "string" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "2-letter ISO 3166 for address", "title": "Country" }, "line1": { "description": "First line of address", "title": "Line1", "type": "string" }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Second line of address", "title": "Line2" }, "postal_code": { "description": "Zip code for address", "title": "Postal Code", "type": "string" }, "state": { "description": "State for address", "title": "State", "type": "string" } }, "required": [ "line1", "city", "state", "postal_code" ], "title": "Address", "type": "object" }, "CaptureItemDetails": { "properties": { "item_id": { "description": "ID that uniquely identifies the item within the Payment; optionally specified when creating the payment and retrievable from payment session status or list payment sessions.", "title": "Item Id", "type": "string" }, "quantity": { "description": "The quantity to capture for this order_item, up to the quantity_capturable for the item, retrievable from payment session status or list payment sessions.", "title": "Quantity", "type": "integer" }, "total": { "description": "The total amount in cents to capture for this order_item, up to the total_capturable for the item, retrievable from payment session status or list payment sessions.", "title": "Total", "type": "integer" } }, "required": [ "item_id", "quantity", "total" ], "title": "CaptureItemDetails", "type": "object" }, "CaptureWebhookPayload": { "properties": { "capture_amount": { "description": "The amount captured in cents", "title": "Capture Amount", "type": "integer" }, "captured_at": { "description": "ISO-8601 timestamp of when the capture occurred", "title": "Captured At", "type": "string" } }, "required": [ "captured_at", "capture_amount" ], "title": "CaptureWebhookPayload", "type": "object" }, "CardNetwork": { "enum": [ "visa", "mastercard" ], "title": "CardNetwork", "type": "string" }, "CatalogItemDetail": { "properties": { "created_at": { "description": "The date and time the catalog item was created.", "format": "date-time", "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "An optional description of the catalog item.", "title": "Description" }, "eligibility": { "anyOf": [ { "$ref": "#/components/schemas/CatalogItemEligibility" }, { "type": "null" } ], "description": "HSA/FSA eligibility status for the catalog item." }, "gtin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The GTIN of the catalog item.", "title": "Gtin" }, "image_urls": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Optional array of image URLs associated with the catalog item.", "title": "Image Urls" }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional metadata string for the catalog item.", "title": "Metadata" }, "name": { "description": "The name of the catalog item.", "title": "Name", "type": "string" }, "product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The product ID of the product which this catalog item is a variant of.", "title": "Product Id" }, "reviewed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "The date and time the catalog item was last reviewed.", "title": "Reviewed At" }, "sku": { "description": "The SKU of the catalog item.", "title": "Sku", "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "An optional display page URL for the catalog item.", "title": "Url" } }, "required": [ "sku", "name", "created_at" ], "title": "CatalogItemDetail", "type": "object" }, "CatalogItemEligibility": { "description": "HSA/FSA eligibility status for catalog items.", "enum": [ "eligible", "eligible_with_lmn", "ineligible" ], "title": "CatalogItemEligibility", "type": "string" }, "CreateItemRequest": { "properties": { "description": { "description": "The description of the item.", "title": "Description", "type": "string" }, "gtin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The GTIN of the catalog item.", "title": "Gtin" }, "image_urls": { "description": "An array of image URLs of the item.", "items": { "type": "string" }, "maxItems": 10, "minItems": 1, "title": "Image Urls", "type": "array" }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional metadata string for the catalog item.", "title": "Metadata" }, "name": { "description": "The name of the catalog item.", "title": "Name", "type": "string" }, "product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The product ID of the product which this catalog item is a variant of.", "title": "Product Id" }, "sku": { "description": "The SKU of the catalog item.", "title": "Sku", "type": "string" }, "url": { "description": "The display page URL for the item.", "title": "Url", "type": "string" } }, "required": [ "sku", "name", "description", "url", "image_urls" ], "title": "CreateItemRequest", "type": "object" }, "CreateItemResponse": { "properties": {}, "title": "CreateItemResponse", "type": "object" }, "CreateMerchantReportedTransactionRequest": { "properties": { "capture_time": { "description": "The datetime (ISO 8601) at which you captured funds for this transaction.", "format": "date-time", "title": "Capture Time", "type": "string" }, "card_holder_name": { "description": "The cardholder name on the card used to capture this transaction.", "maxLength": 255, "title": "Card Holder Name", "type": "string" }, "last4": { "description": "The last four digits of the card used to capture this transaction.", "maxLength": 4, "minLength": 4, "pattern": "^\\d{4}$", "title": "Last4", "type": "string" }, "merchant_descriptor": { "description": "The merchant descriptor that will appear on the cardholder's statement for this charge.", "maxLength": 22, "title": "Merchant Descriptor", "type": "string" }, "merchant_transaction_id": { "description": "Your merchant-side identifier for the captured transaction (typically the PSP or network transaction id). Idempotency is scoped per sales channel by this value \u2014 re-submitting the same `merchant_transaction_id` returns the originally recorded transaction without creating a duplicate.", "maxLength": 128, "title": "Merchant Transaction Id", "type": "string" }, "network": { "$ref": "#/components/schemas/CardNetwork", "description": "The card network of the card used to capture this transaction." }, "network_transaction_id": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "Optional card-network-side transaction identifier returned in the authorization response (e.g., the Visa or Mastercard transaction id). Provide when available \u2014 Truemed uses it as a preferred lookup key for downstream substantiation matching.", "title": "Network Transaction Id" }, "order_items": { "description": "The captured cart's line items. Each item's `sku` must match a SKU already registered with the qualification session at creation time so Truemed can resolve it against the LMN's covered eligibility categories. These items are the sole source of truth for the captured cart total \u2014 the amount Truemed bills and substantiates is the sum of the line items (`price` \u00d7 `quantity`, plus each item's `amount_details` additional charges, minus its discounts); there is no separate cart-level total. See each item's `amount_details` for how to represent cart-wide concepts like shipping, tax, and promotions.", "items": { "$ref": "#/components/schemas/QualificationSessionOrderItem" }, "maxItems": 250, "minItems": 1, "title": "Order Items", "type": "array" }, "postal_code": { "description": "The billing postal code for the card used to capture this transaction (US ZIP; 5- or 9-digit).", "maxLength": 10, "minLength": 5, "pattern": "^\\d{5}(-?\\d{4})?$", "title": "Postal Code", "type": "string" } }, "required": [ "merchant_transaction_id", "merchant_descriptor", "capture_time", "last4", "network", "card_holder_name", "postal_code", "order_items" ], "title": "CreateMerchantReportedTransactionRequest", "type": "object" }, "CreateMerchantReportedTransactionResponse": { "properties": { "fee_cents": { "description": "The Truemed fee for this reported transaction, in cents. Every reported transaction is billed; see `fee_due_at` for when this fee becomes due.", "title": "Fee Cents", "type": "integer" }, "fee_due_at": { "description": "When the fee for this transaction becomes due to Truemed. Treat this as the authoritative due datetime regardless of how or when the fee is ultimately collected.", "format": "date-time", "title": "Fee Due At", "type": "string" }, "merchant_reported_transaction_id": { "description": "Opaque Truemed-side identifier for the recorded merchant-reported transaction. Persist this so you can reference the transaction in future support or reconciliation flows.", "title": "Merchant Reported Transaction Id", "type": "string" } }, "required": [ "merchant_reported_transaction_id", "fee_cents", "fee_due_at" ], "title": "CreateMerchantReportedTransactionResponse", "type": "object" }, "CreatePaymentSessionRequest": { "properties": { "amount_details": { "$ref": "#/components/schemas/PaymentSessionAmountDetails", "description": "Additional amount details including discounts and charges." }, "billing_address": { "anyOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "null" } ], "description": "The Billing address for the order (used for better fraud detection)" }, "billing_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The first and last name of the person for billing (used for better fraud detection).", "title": "Billing Name" }, "customer_email": { "description": "The email address for the customer.", "title": "Customer Email", "type": "string" }, "customer_name": { "description": "The first and last name of the customer.", "title": "Customer Name", "type": "string" }, "customer_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The 2-letter ISO 3166-2:US code for a region, without the US- prefix.", "title": "Customer State" }, "display_next_bill_info": { "anyOf": [ { "$ref": "#/components/schemas/NextBillInfo" }, { "type": "null" } ], "description": "Information about the next bill for free trial sessions." }, "failure_url": { "description": "When the payment fails in an irrecoverable way, or the user is ineligible to spend HSA/FSA funds on the purchase.", "maxLength": 4096, "title": "Failure Url", "type": "string" }, "idempotency_key": { "description": "A unique identifier for the checkout session, used to safely retry this request. If the same `idempotency_key` is sent again with a request whose key fields match the original (`customer_email` (case-insensitive), `total_amount`, `success_url`, `failure_url`, `order_items`, `kind`, `payment_token`, and any `display_next_bill_info` fields), the original payment session is returned. If the key is reused with a different request, a `400 IdempotencyViolation` is returned naming the field(s) that diverged. `customer_name`, `metadata`, and survey configuration are not part of the idempotency comparison.", "title": "Idempotency Key", "type": "string" }, "kind": { "anyOf": [ { "$ref": "#/components/schemas/PurchaseKind" }, { "type": "null" } ], "default": "one_time_payment", "description": "One of the following: one_time_payment (DEFAULT), authorization." }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Will be echoed back in the webhook and detail view if present.", "title": "Metadata" }, "order_items": { "description": "A list of order items.", "items": { "$ref": "#/components/schemas/PaymentSessionOrderItem" }, "title": "Order Items", "type": "array" }, "payment_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ID returned by Truemed on initial recurring charges (when tokenize=True).", "title": "Payment Token" }, "shipping_address": { "anyOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "null" } ], "description": "The shipping address for the payment session." }, "shipping_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The first and last name of the person for shipping (used for better fraud detection).", "title": "Shipping Name" }, "success_url": { "description": "Where to redirect the user to after Truemed successfully processes a payment.", "maxLength": 4096, "title": "Success Url", "type": "string" }, "survey_config": { "anyOf": [ { "$ref": "#/components/schemas/SurveyConfig" }, { "type": "null" } ], "description": "Allows the partner to customize the health survey." }, "tokenize": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": false, "description": "True or False - set to True to enable subsequent charges.", "title": "Tokenize" }, "total_amount": { "description": "The total amount in cents to charge the user, inclusive of discounts, shipping, taxes, and other fees being collected by the partner.", "title": "Total Amount", "type": "integer" }, "use_iframe": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": false, "description": "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.", "title": "Use Iframe" } }, "required": [ "total_amount", "order_items", "success_url", "failure_url", "idempotency_key", "customer_name", "customer_email", "amount_details" ], "title": "CreatePaymentSessionRequest", "type": "object" }, "CreatePaymentSessionResponse": { "properties": { "authorization_expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "The latest UTC time at which the authorization is valid for capture. Null until the session has an authorized transaction. When the transaction has multiple active payments (e.g. HSA + credit), this is the earliest expiration across them.", "title": "Authorization Expires At" }, "id": { "description": "The unique ID for this checkout session.", "title": "Id", "type": "string" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional message for the response.", "title": "Message" }, "next_action": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The next action required for the payment.", "title": "Next Action" }, "payment_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The payment token for recurring payments.", "title": "Payment Token" }, "redirect_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The URL that the partner should redirect the customer to.", "title": "Redirect Url" } }, "required": [ "id" ], "title": "CreatePaymentSessionResponse", "type": "object" }, "CreatePaymentTokenRequest": { "properties": { "customer_email": { "description": "The customer's email", "format": "email", "title": "Customer Email", "type": "string" }, "customer_name": { "description": "The customer's full name", "title": "Customer Name", "type": "string" }, "customer_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Set this to pre-fill the answer to the State of Residence question in the health survey. The 2-letter ISO 3166-2:US code for a region, without the US- prefix", "examples": [ "AZ", "CO", "TX" ], "title": "Customer State" }, "failure_url": { "description": "Where Truemed should redirect the customer if they decide to cancel the checkout", "title": "Failure Url", "type": "string" }, "idempotency_key": { "description": "A unique ID that allows safely retrying the request without performing the same operation twice", "title": "Idempotency Key", "type": "string" }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A JSON string containing any custom key-value pairs. This string will be returned in the payment_session_complete webhook if provided", "title": "Metadata" }, "order_items": { "description": "The initial list of items for this subscription", "items": { "$ref": "#/components/schemas/PaymentTokenOrderItemSku" }, "minItems": 1, "title": "Order Items", "type": "array" }, "success_url": { "description": "Where Truemed should redirect the customer after successfully completing checkout", "title": "Success Url", "type": "string" }, "use_iframe": { "default": false, "description": "Set to true to allow the Truemed checkout flow to be surfaced via an iframe", "title": "Use Iframe", "type": "boolean" } }, "required": [ "idempotency_key", "success_url", "failure_url", "order_items", "customer_email", "customer_name" ], "title": "CreatePaymentTokenRequest", "type": "object" }, "CreatePaymentTokenResponse": { "properties": { "provision_token_request_id": { "description": "A UUID that represents this creation request", "title": "Provision Token Request Id", "type": "string" }, "redirect_url": { "description": "Contains a URI through which the customer can complete the payment token provisioning", "title": "Redirect Url", "type": "string" } }, "required": [ "provision_token_request_id", "redirect_url" ], "title": "CreatePaymentTokenResponse", "type": "object" }, "CreateQualificationSessionAuthHoldRequest": { "properties": { "amount": { "description": "The auth-hold amount you placed on the customer's card, in cents.", "exclusiveMinimum": 0.0, "maximum": 100000000.0, "title": "Amount", "type": "integer" }, "auth_hold_expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Optional datetime at which the auth hold expires.", "title": "Auth Hold Expires At" }, "card_holder_name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Card-holder name on the held card.", "title": "Card Holder Name" }, "idempotency_key": { "description": "A unique key for safely retrying the request, scoped to this qualification session. Duplicate POSTs with the same key against the same qualification session return the original auth hold.", "maxLength": 255, "title": "Idempotency Key", "type": "string" }, "last4": { "anyOf": [ { "maxLength": 4, "minLength": 4, "type": "string" }, { "type": "null" } ], "description": "Last four digits of the held card.", "title": "Last4" }, "merchant_auth_hold_id": { "description": "Your identifier for the auth hold. Must be unique within your account.", "maxLength": 255, "title": "Merchant Auth Hold Id", "type": "string" }, "metadata": { "anyOf": [ { "maxLength": 4096, "type": "string" }, { "type": "null" } ], "description": "Optional metadata string (JSON-encoded by convention).", "title": "Metadata" }, "network": { "anyOf": [ { "$ref": "#/components/schemas/CardNetwork" }, { "type": "null" } ], "description": "The card network of the held card." }, "postal_code": { "anyOf": [ { "maxLength": 16, "type": "string" }, { "type": "null" } ], "description": "Postal code associated with the held card.", "title": "Postal Code" } }, "required": [ "idempotency_key", "amount", "merchant_auth_hold_id" ], "title": "CreateQualificationSessionAuthHoldRequest", "type": "object" }, "CreateQualificationSessionAuthHoldResponse": { "properties": { "auth_hold_id": { "description": "Opaque identifier for the auth hold, returned by Truemed.", "title": "Auth Hold Id", "type": "string" }, "qualification_session_id": { "description": "The qualification_session_id this auth hold is attached to.", "title": "Qualification Session Id", "type": "string" }, "status": { "$ref": "#/components/schemas/QualificationSessionStatusSummary", "description": "The new qualification-session status summary \u2014 will be `processing` after a successful auth-hold call.\n\nOne of:\n- `pending` \u2014 The session was created; the shopper hasn't completed the survey yet.\n- `processing` \u2014 The shopper completed the survey and it is under review.\n- `approved` \u2014 The shopper holds a valid Letter of Medical Necessity covering the items in this order.\n- `rejected` \u2014 The shopper is ineligible for a Letter of Medical Necessity for the items in this order." } }, "required": [ "qualification_session_id", "auth_hold_id", "status" ], "title": "CreateQualificationSessionAuthHoldResponse", "type": "object" }, "CreateQualificationSessionRequest": { "properties": { "customer_email": { "description": "Customer email used to pre-fill the qualification survey. Not used to match the shopper against existing Truemed records \u2014 use `user_id` for that.", "maxLength": 320, "title": "Customer Email", "type": "string" }, "customer_name": { "description": "Customer full name for pre-fill.", "maxLength": 255, "title": "Customer Name", "type": "string" }, "failure_url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "description": "Optional URL the consumer is redirected to after a failed qualification.", "title": "Failure Url" }, "idempotency_key": { "description": "A unique key for safely retrying the request. Duplicate POSTs with the same key return the original session.", "maxLength": 255, "title": "Idempotency Key", "type": "string" }, "metadata": { "anyOf": [ { "maxLength": 4096, "type": "string" }, { "type": "null" } ], "description": "Optional metadata string (JSON-encoded by convention).", "title": "Metadata" }, "order_items": { "description": "Line items the shopper is checking out with. SKUs are matched against your Truemed product catalog to validate the cart and to resolve which eligibility categories the qualification should cover. These items are the sole source of truth for the cart total \u2014 the amount Truemed bills and substantiates is the sum of the line items (`price` \u00d7 `quantity`, plus each item's `amount_details` additional charges, minus its discounts); there is no separate cart-level total. See each item's `amount_details` for how to represent cart-wide concepts like shipping, tax, and promotions.", "items": { "$ref": "#/components/schemas/QualificationSessionOrderItem" }, "maxItems": 250, "minItems": 1, "title": "Order Items", "type": "array" }, "success_url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "description": "Optional URL the consumer is redirected to after a successful qualification.", "title": "Success Url" }, "use_iframe": { "default": false, "description": "Whether the qualification flow should render in an iframe.", "title": "Use Iframe", "type": "boolean" }, "user_id": { "description": "Your stable, opaque identifier for the shopper. Truemed uses it to recognize returning customers across qualification sessions so they can skip re-qualifying once approved.", "maxLength": 255, "title": "User Id", "type": "string" } }, "required": [ "idempotency_key", "user_id", "customer_email", "customer_name", "order_items" ], "title": "CreateQualificationSessionRequest", "type": "object" }, "CreateQualificationSessionResponse": { "properties": { "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Datetime at which the Letter-of-Medical-Necessity expires, if any.", "title": "Expires At" }, "is_already_qualified": { "description": "True if the shopper already holds a valid qualification for this order. When true, you can skip the `redirect_url` step and move the customer straight to checkout.", "title": "Is Already Qualified", "type": "boolean" }, "qualification_session_id": { "description": "Opaque identifier for the qualification session, returned by Truemed.", "title": "Qualification Session Id", "type": "string" }, "redirect_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL the consumer should be redirected to in order to complete qualification.", "title": "Redirect Url" }, "status": { "$ref": "#/components/schemas/QualificationSessionStatusSummary", "description": "Status summary of the qualification session.\n\nOne of:\n- `pending` \u2014 The session was created; the shopper hasn't completed the survey yet.\n- `processing` \u2014 The shopper completed the survey and it is under review.\n- `approved` \u2014 The shopper holds a valid Letter of Medical Necessity covering the items in this order.\n- `rejected` \u2014 The shopper is ineligible for a Letter of Medical Necessity for the items in this order." } }, "required": [ "qualification_session_id", "status", "is_already_qualified" ], "title": "CreateQualificationSessionResponse", "type": "object" }, "CreateRefundRequest": { "properties": { "amount": { "description": "The amount you wish to refund in cents. Cannot be greater than the total_amount originally charged.", "title": "Amount", "type": "integer" }, "idempotency_key": { "description": "Allows the endpoint to be called multiple times, and must be unique to the refund request.", "title": "Idempotency Key", "type": "string" }, "item_details": { "description": "A list of items to be refunded.", "items": { "$ref": "#/components/schemas/RefundItemDetails" }, "title": "Item Details", "type": "array" }, "payment_id": { "description": "The id returned to the partner by Truemed in response to a `create_payment_session` request.", "title": "Payment Id", "type": "string" }, "reason": { "$ref": "#/components/schemas/RefundReasons", "description": "Why you are initiating this refund request: customer_request - the customer requested a refund; fraudulent - the payment was fraudulent; duplicate_payment - the user checked out with HSA/FSA multiple times for one purchase." } }, "required": [ "payment_id", "amount", "idempotency_key", "reason", "item_details" ], "title": "CreateRefundRequest", "type": "object" }, "CreateRefundResponse": { "properties": { "refund_id": { "description": "The unique ID for this refund. Multiple refunds can be associated with a single payment, in the case of partial refunds.", "title": "Refund Id", "type": "string" } }, "required": [ "refund_id" ], "title": "CreateRefundResponse", "type": "object" }, "CustomerFacingTransactionStatus": { "enum": [ "Incomplete", "Canceled", "Rejected", "Processing", "Authorized", "Voided", "Expired", "Partially Captured", "Captured", "Partially Refunded", "Refunded", "PartiallyDisputed", "Disputed" ], "title": "CustomerFacingTransactionStatus", "type": "string" }, "DetailItemRequest": { "properties": { "sku": { "description": "The SKU of the catalog item to retrieve.", "title": "Sku", "type": "string" } }, "required": [ "sku" ], "title": "DetailItemRequest", "type": "object" }, "DetailItemResponse": { "properties": { "object": { "$ref": "#/components/schemas/CatalogItemDetail", "description": "The catalog item detail." } }, "required": [ "object" ], "title": "DetailItemResponse", "type": "object" }, "DisputeDetails": { "properties": { "amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": 0, "description": "The original disputed amount in cents. Always reflects what the dispute was filed for, independent of resolution. For Won disputes this stays non-zero even though `withdrawn_amount` becomes 0 after reinstatement, so consumers can show 'this dispute was for $X' regardless of outcome.", "title": "Amount" }, "description": { "description": "Further details about the state of a dispute.", "title": "Description", "type": "string" }, "dispute_id": { "description": "Stable Truemed dispute ID (UUID). Use this as the dispute's identifier.", "title": "Dispute Id", "type": "string" }, "disputed_on": { "description": "The date that the dispute was created.", "format": "date-time", "title": "Disputed On", "type": "string" }, "processor_dispute_id": { "description": "Raw payment-processor dispute ID (e.g. Stripe `du_\u2026`). Provided for reconciliation against processor records; prefer `dispute_id` (the stable Truemed UUID) as the identifier.", "title": "Processor Dispute Id", "type": "string" }, "reason": { "$ref": "#/components/schemas/DisputeReason", "description": "Specific reason the dispute was created." }, "resolved_on": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "The date that the dispute was resolved.", "title": "Resolved On" }, "status": { "$ref": "#/components/schemas/DisputeStatusPublic", "description": "Status of this dispute." }, "withdrawn_amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": 0, "description": "The total amount of money withdrawn based on the ruling.", "title": "Withdrawn Amount" } }, "required": [ "dispute_id", "processor_dispute_id", "status", "reason", "disputed_on", "description" ], "title": "DisputeDetails", "type": "object" }, "DisputeReason": { "description": "The reason for the dispute.\n\nhttps://docs.stripe.com/api/disputes/object#dispute_object-reason", "enum": [ "bank_cannot_process", "check_returned", "credit_not_processed", "customer_initiated", "debit_not_authorized", "duplicate", "fraudulent", "general", "incorrect_account_details", "insufficient_funds", "product_not_received", "product_unacceptable", "subscription_canceled", "unrecognized" ], "title": "DisputeReason", "type": "string" }, "DisputeStatusPublic": { "description": "The public facing status for the dispute.", "enum": [ "Lost", "Won", "Closed", "Investigating", "Under Review", "Unknown" ], "title": "DisputeStatusPublic", "type": "string" }, "ErrorResponse": { "properties": { "error": { "$ref": "#/components/schemas/ErrorType" }, "message": { "title": "Message", "type": "string" } }, "required": [ "error", "message" ], "title": "ErrorResponse", "type": "object" }, "ErrorType": { "enum": [ "BadRequest", "Unauthorized", "Forbidden", "NotFound", "MethodNotAllowed", "Conflict", "TooManyRequests", "ServerError", "BadGateway", "ServiceUnavailable", "GatewayTimeout", "NotImplemented", "RequestValueError", "ValidationError", "TokenExpired", "InvalidToken", "InvalidCredentials", "StripeInvalidRequestError", "StripeRateLimitError", "StripeError", "PaymentMethodNotFoundError", "CustomerIdNotFoundError", "InvalidPaymentId", "IneligibleItemAdded", "TotalAmountInvalid", "FeatureNotEnabled" ], "title": "ErrorType", "type": "string" }, "ListItemsResponse": { "properties": { "data": { "description": "An array of catalog item objects for the current page.", "items": { "$ref": "#/components/schemas/CatalogItemDetail" }, "title": "Data", "type": "array" }, "pagination": { "anyOf": [ { "$ref": "#/components/schemas/PaginationBody" }, { "type": "null" } ], "description": "A pagination object with information about the current page, page size, total count, and last page." } }, "required": [ "data" ], "title": "ListItemsResponse", "type": "object" }, "NextActionType": { "enum": [ "UpdatePaymentMethod", "TakeHealthSurvey", "None" ], "title": "NextActionType", "type": "string" }, "NextBillInfo": { "properties": { "date": { "format": "date", "title": "Date", "type": "string" }, "total_amount": { "title": "Total Amount", "type": "integer" } }, "required": [ "total_amount", "date" ], "title": "NextBillInfo", "type": "object" }, "PaginationBody": { "properties": { "count": { "description": "The total number of items associated with the provided API key.", "title": "Count", "type": "integer" }, "current_page": { "description": "The page requested. If none was provided, this will default to 1.", "title": "Current Page", "type": "integer" }, "last_page": { "description": "The last page. You can iterate through pages by providing integers up to last_page in the page parameter.", "title": "Last Page", "type": "integer" }, "page_size": { "description": "The number of items per page, which is at most 30.", "title": "Page Size", "type": "integer" } }, "required": [ "current_page", "page_size", "count", "last_page" ], "title": "PaginationBody", "type": "object" }, "PaymentMethodResponse": { "properties": { "expiration": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A MM/YYYY formatted string specifying the month and year the card on file will expire.", "title": "Expiration" }, "last4": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The last 4 digits of the CC number associated with this payment method.", "title": "Last4" }, "payment_method_updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 formatted DateTime object that represents the date and time the `payment_method` was last updated by the customer.", "title": "Payment Method Updated At" } }, "title": "PaymentMethodResponse", "type": "object" }, "PaymentSessionAmountDetail": { "properties": { "amount": { "description": "The amount in cents for this discount or charge.", "title": "Amount", "type": "integer" }, "name": { "description": "The name or description of the discount or charge.", "title": "Name", "type": "string" } }, "required": [ "name", "amount" ], "title": "PaymentSessionAmountDetail", "type": "object" }, "PaymentSessionAmountDetails": { "properties": { "additional_charges_details": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PaymentSessionAmountDetail" }, "type": "array" }, { "type": "null" } ], "description": "An array of individual additional charge line items with names and amounts.", "title": "Additional Charges Details" }, "discounts_details": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PaymentSessionAmountDetail" }, "type": "array" }, { "type": "null" } ], "description": "An array of individual discount line items with names and amounts.", "title": "Discounts Details" }, "total_additional_charges": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The total amount of additional charges (e.g., shipping, tax), in cents.", "title": "Total Additional Charges" }, "total_discounts": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The total amount of discounts applied, in cents.", "title": "Total Discounts" } }, "title": "PaymentSessionAmountDetails", "type": "object" }, "PaymentSessionCancelResponse": { "properties": { "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional field echoed back if present in the call to create_payment_session.", "title": "Metadata" }, "order_items": { "description": "A list of order items.", "items": { "$ref": "#/components/schemas/PaymentSessionOrderItem" }, "title": "Order Items", "type": "array" }, "status": { "$ref": "#/components/schemas/PaymentSessionStatus", "description": "The status field of the payment_session. When the payment session is pending, it will be marked as `canceled`." } }, "required": [ "status", "order_items" ], "title": "PaymentSessionCancelResponse", "type": "object" }, "PaymentSessionCaptureRequest": { "properties": { "final": { "default": true, "description": "Whether this is the final capture for the payment session. Set to false to allow additional captures up to the authorized amount.", "title": "Final", "type": "boolean" }, "idempotency_key": { "description": "Allows the endpoint to be called multiple times. It must be unique to the capture session.", "title": "Idempotency Key", "type": "string" }, "item_details": { "description": "A list of items being captured in the capture request.", "items": { "$ref": "#/components/schemas/CaptureItemDetails" }, "title": "Item Details", "type": "array" }, "total_amount": { "description": "The total amount in cents to charge the user, inclusive of taxes and fees being collected by the partner. Must be less than or equal to the total_amount passed in when creating the payment session. If an amount more than the initial authorization should be captured, void the initial auth hold and create a new one.", "title": "Total Amount", "type": "integer" } }, "required": [ "total_amount", "idempotency_key", "item_details" ], "title": "PaymentSessionCaptureRequest", "type": "object" }, "PaymentSessionCaptureResponse": { "properties": { "id": { "description": "The unique ID for this session capture. 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.", "title": "Id", "type": "string" } }, "required": [ "id" ], "title": "PaymentSessionCaptureResponse", "type": "object" }, "PaymentSessionDetailResponse": { "properties": { "amount_details": { "anyOf": [ { "$ref": "#/components/schemas/PaymentSessionAmountDetails" }, { "type": "null" } ], "description": "Detailed breakdown of the payment amount." }, "authorization_expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "The latest UTC time at which the authorization is valid for capture. Null until the session has an authorized transaction. When the transaction has multiple active payments (e.g. HSA + credit), this is the earliest expiration across them.", "title": "Authorization Expires At" }, "authorize_amount": { "description": "The amount the user's card will be authorized for. In the case of `kind=one_time_payment`, this will always the same same as `capture_amount`.", "title": "Authorize Amount", "type": "integer" }, "capture_amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The amount of funds actually captured.", "title": "Capture Amount" }, "created_at": { "description": "The date and time when the payment session was created.", "format": "date-time", "title": "Created At", "type": "string" }, "customer_business_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The business id of the customer.", "title": "Customer Business Id" }, "disputes": { "description": "A list of dispute objects that will be empty if the payment has no associated disputes.", "items": { "$ref": "#/components/schemas/DisputeDetails" }, "title": "Disputes", "type": "array" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The email of the user who executed the payment.", "title": "Email" }, "is_testing": { "description": "Whether the payment was executed in a test environment.", "title": "Is Testing", "type": "boolean" }, "kind": { "$ref": "#/components/schemas/PurchaseKind", "description": "The type of payment session." }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional field echoed back if present in the call to `create_payment_session`.", "title": "Metadata" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The name of the user who executed the payment.", "title": "Name" }, "order_items": { "description": "A list of order items.", "items": { "$ref": "#/components/schemas/PaymentSessionOrderItemDetails" }, "title": "Order Items", "type": "array" }, "payment_session_id": { "description": "The id of the payment session.", "title": "Payment Session Id", "type": "string" }, "refunds": { "description": "A list of refund objects that will be empty if the payment has no associated refunds.", "items": { "$ref": "#/components/schemas/RefundDetails" }, "title": "Refunds", "type": "array" }, "status": { "$ref": "#/components/schemas/PaymentSessionStatus", "description": "The status of the initial payment." }, "status_summary": { "$ref": "#/components/schemas/CustomerFacingTransactionStatus", "description": "A summary of the overall payment session." }, "stripe_payment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The Stripe payment id.", "title": "Stripe Payment Id" }, "total_amount": { "description": "The total amount captured, in cents.", "title": "Total Amount", "type": "integer" }, "truemed_fee": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" }, { "type": "null" } ], "description": "The fee that Truemed received from the payment session. Will return 0 until the session has been captured.", "title": "Truemed Fee" } }, "required": [ "payment_session_id", "status", "total_amount", "authorize_amount", "refunds", "disputes", "status_summary", "is_testing", "created_at", "order_items", "kind" ], "title": "PaymentSessionDetailResponse", "type": "object" }, "PaymentSessionDetails": { "properties": { "amount_details": { "anyOf": [ { "$ref": "#/components/schemas/PaymentSessionAmountDetails" }, { "type": "null" } ], "description": "Detailed breakdown of the payment amount including discounts and charges." }, "authorize_amount": { "description": "The total_amount passed into `create_payment_session`.", "title": "Authorize Amount", "type": "integer" }, "authorized_on": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "The date the payment was authorized in ISO 8601 format. Example: \"2024-06-13T16:03:07.473Z\". For kind: one_time_payment, this will be the same as captured_on.", "title": "Authorized On" }, "capture_amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "For one time payments, same as authorize_amount. Otherwise, the captured amount.", "title": "Capture Amount" }, "captured_on": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "The date the payment was captured in ISO 8601 format. Example: \"2024-06-13T16:03:07.473Z\".", "title": "Captured On" }, "created_at": { "description": "The date the payment session was created in ISO 8601 format. Example: \"2024-06-13T16:03:07.473Z\".", "format": "date-time", "title": "Created At", "type": "string" }, "disputes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/DisputeDetails" }, "type": "array" }, { "type": "null" } ], "description": "An array of dispute objects. Included if include_disputes is True (by default).", "title": "Disputes" }, "id": { "description": "The UUID returned by `create_payment_session`.", "title": "Id", "type": "string" }, "idempotency_key": { "description": "The idempotency key passed into create_payment_session.", "title": "Idempotency Key", "type": "string" }, "is_testing": { "description": "The testing flag.", "title": "Is Testing", "type": "boolean" }, "kind": { "$ref": "#/components/schemas/PurchaseKind", "description": "The payment kind, either one_time_payment or authorization." }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The raw `metadata` field passed into `create_payment_session`.", "title": "Metadata" }, "order_items": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PaymentSessionOrderItemDetails" }, "type": "array" }, { "type": "null" } ], "description": "The list of the current state of the order items passed into `create_payment_session` if `include_order_items` is True.", "title": "Order Items" }, "refund_amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Only present when summarize_refunds=True is included in the request. The sum of processed refunds for the payment session, in cents.", "title": "Refund Amount" }, "refund_count": { "description": "The number of refunds made on this payment.", "title": "Refund Count", "type": "integer" }, "refunds": { "anyOf": [ { "items": { "$ref": "#/components/schemas/RefundDetails" }, "type": "array" }, { "type": "null" } ], "description": "An array of refund objects. Included if include_refunds is True (by default).", "title": "Refunds" }, "status": { "$ref": "#/components/schemas/PaymentSessionStatus", "description": "Status of the Payment Session (pending, processing, captured, authorized, or authorization_voided, or rejected)." }, "status_summary": { "$ref": "#/components/schemas/CustomerFacingTransactionStatus", "description": "A summary of the overall payment session status." }, "stripe_payment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The Stripe payment ID associated with this payment session.", "title": "Stripe Payment Id" }, "truemed_fee": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" }, { "type": "null" } ], "description": "Only present when include_trumed_fee=True is included in the request. The fee collected by truemed for this payment session. Will return 0 until the session has been captured.", "title": "Truemed Fee" }, "user": { "$ref": "#/components/schemas/UserDetails", "description": "The user attached to the payment session." } }, "required": [ "id", "status", "authorize_amount", "kind", "user", "is_testing", "idempotency_key", "refund_count", "created_at", "status_summary" ], "title": "PaymentSessionDetails", "type": "object" }, "PaymentSessionListResponse": { "properties": { "pagination": { "anyOf": [ { "$ref": "#/components/schemas/PaginationBody" }, { "type": "null" } ], "description": "A pagination object with information about the current page, page size, total count, and last page." }, "payment_sessions": { "description": "List of payment session details.", "items": { "$ref": "#/components/schemas/PaymentSessionDetails" }, "title": "Payment Sessions", "type": "array" } }, "required": [ "payment_sessions" ], "title": "PaymentSessionListResponse", "type": "object" }, "PaymentSessionOrderItem": { "properties": { "amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The total amount for this line item in cents. Either amount or price must be provided.", "title": "Amount" }, "amount_details": { "$ref": "#/components/schemas/PaymentSessionAmountDetails", "description": "Optional itemized discounts and charges for this item." }, "item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A unique identifier for this order item within the payment.", "title": "Item Id" }, "name": { "description": "The name of the item.", "title": "Name", "type": "string" }, "price": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The unit price in cents for the item. Either amount or price must be provided.", "title": "Price" }, "quantity": { "description": "The number of this item in the cart.", "title": "Quantity", "type": "integer" }, "sku": { "description": "The SKU (Stock Keeping Unit) for this item.", "title": "Sku", "type": "string" } }, "required": [ "name", "quantity", "sku", "amount_details" ], "title": "PaymentSessionOrderItem", "type": "object" }, "PaymentSessionOrderItemDetails": { "properties": { "amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The total amount for this line item in cents (quantity \u00d7 price).", "title": "Amount" }, "amount_details": { "anyOf": [ { "$ref": "#/components/schemas/PaymentSessionAmountDetails" }, { "type": "null" } ], "description": "Itemized discounts and charges applied to this specific item." }, "item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional unique identifier for this item provided by the merchant.", "title": "Item Id" }, "name": { "description": "The name of the item.", "title": "Name", "type": "string" }, "price": { "description": "The unit price in cents charged for the item.", "title": "Price", "type": "integer" }, "quantity": { "description": "The number of this item in the cart.", "title": "Quantity", "type": "integer" }, "quantity_capturable": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The quantity of this item that can still be captured (for manual capture authorizations).", "title": "Quantity Capturable" }, "quantity_refundable": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The quantity of this item that can be refunded.", "title": "Quantity Refundable" }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The SKU (Stock Keeping Unit) for this item.", "title": "Sku" }, "total": { "description": "The post-discount, post-charge line total in cents \u2014 `(price \u00d7 quantity) + total_additional_charges - total_discounts`. Use this when displaying the per-item total or when computing capture `item_details.total` for a fresh capture.", "title": "Total", "type": "integer" }, "total_capturable": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The total amount in cents that can still be captured for this item.", "title": "Total Capturable" }, "total_refundable": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The total amount in cents that can be refunded for this item.", "title": "Total Refundable" } }, "required": [ "name", "quantity", "price", "total" ], "title": "PaymentSessionOrderItemDetails", "type": "object" }, "PaymentSessionStatus": { "enum": [ "pending", "canceled", "processing", "rejected", "authorized", "authorization_expired", "authorization_voided", "partially_captured", "captured" ], "title": "PaymentSessionStatus", "type": "string" }, "PaymentSessionVoidRequest": { "properties": { "idempotency_key": { "description": "Allows the endpoint to be called multiple times. It must be unique to the void session call.", "title": "Idempotency Key", "type": "string" } }, "required": [ "idempotency_key" ], "title": "PaymentSessionVoidRequest", "type": "object" }, "PaymentSessionVoidResponse": { "properties": { "id": { "description": "The unique ID for this void 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.", "title": "Id", "type": "string" } }, "required": [ "id" ], "title": "PaymentSessionVoidResponse", "type": "object" }, "PaymentTokenDeleteResponse": { "properties": {}, "title": "PaymentTokenDeleteResponse", "type": "object" }, "PaymentTokenListResponse": { "properties": { "pagination": { "anyOf": [ { "$ref": "#/components/schemas/PaginationBody" }, { "type": "null" } ], "description": "A pagination object with information about the current page, page size, total count, and last page." }, "payment_tokens": { "description": "An array of `payment_token` objects.", "items": { "$ref": "#/components/schemas/PaymentTokenResponse" }, "title": "Payment Tokens", "type": "array" } }, "required": [ "payment_tokens" ], "title": "PaymentTokenListResponse", "type": "object" }, "PaymentTokenOrderItemSku": { "properties": { "sku": { "description": "The SKU of the item as configured in your catalog", "title": "Sku", "type": "string" } }, "required": [ "sku" ], "title": "PaymentTokenOrderItemSku", "type": "object" }, "PaymentTokenProvisionRequestDetailResponse": { "properties": { "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The metadata string you provided as part of the create_payment_token request for the ProvisionTokenRequest. Will be null if no metadata was provided", "title": "Metadata" }, "payment_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The PaymentToken created as part of create_payment_token for the ProvisionTokenRequest. Will be null if the PaymentToken has not been provisioned yet", "title": "Payment Token" } }, "required": [ "payment_token", "metadata" ], "title": "PaymentTokenProvisionRequestDetailResponse", "type": "object" }, "PaymentTokenResponse": { "properties": { "created_at": { "description": "ISO 8601 formatted date and time the `payment_token` was created at.", "title": "Created At", "type": "string" }, "customer_email": { "description": "The email address for the customer associated with this `payment_token`.", "title": "Customer Email", "type": "string" }, "customer_name": { "description": "The first and last name of the customer associated with this `payment_token`.", "title": "Customer Name", "type": "string" }, "lmn_expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 formatted date when the earliest LMN associated with this payment token expires. Null if no verified LMN exists. Partners should prompt users to re-qualify before this date.", "title": "Lmn Expires At" }, "payment_methods": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PaymentMethodResponse" }, "type": "array" }, { "type": "null" } ], "description": "An optional array of payment_method objects.", "title": "Payment Methods" }, "payment_token": { "description": "The payment token identifier.", "title": "Payment Token", "type": "string" } }, "required": [ "payment_token", "customer_email", "customer_name", "created_at" ], "title": "PaymentTokenResponse", "type": "object" }, "PaymentTokenUpdatedWebhookPayload": { "properties": { "failed_payment_session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional payment session ID that failed, triggering token update", "title": "Failed Payment Session Id" }, "lmn_expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional ISO-8601 timestamp of when the LMN expires", "title": "Lmn Expires At" }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional metadata associated with the payment token", "title": "Metadata" }, "payment_methods": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PaymentMethodResponse" }, "type": "array" }, { "type": "null" } ], "description": "Optional list of available payment methods for the token", "title": "Payment Methods" }, "payment_session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional payment session ID associated with the token update", "title": "Payment Session Id" }, "payment_token": { "description": "The payment token identifier", "title": "Payment Token", "type": "string" }, "provision_token_request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional provision token request ID", "title": "Provision Token Request Id" } }, "required": [ "payment_token" ], "title": "PaymentTokenUpdatedWebhookPayload", "type": "object" }, "PayoutReconciliationData": { "properties": { "amount": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "description": "Payout amount in dollars.", "title": "Amount" }, "date": { "description": "Payout arrival date (YYYY-MM-DD).", "format": "date", "title": "Date", "type": "string" }, "payout_id": { "description": "Stripe payout identifier.", "title": "Payout Id", "type": "string" } }, "required": [ "date", "payout_id", "amount" ], "title": "PayoutReconciliationData", "type": "object" }, "PayoutReconciliationListResponse": { "properties": { "pagination": { "anyOf": [ { "$ref": "#/components/schemas/PaginationBody" }, { "type": "null" } ], "description": "A pagination object with information about the current page, page size, total count, and last page." }, "payouts": { "description": "List of payout data for the requested period.", "items": { "$ref": "#/components/schemas/PayoutReconciliationData" }, "title": "Payouts", "type": "array" } }, "required": [ "payouts" ], "title": "PayoutReconciliationListResponse", "type": "object" }, "ProductCatalogItemEligibilityUpdatedWebhookData": { "properties": { "object": { "$ref": "#/components/schemas/CatalogItemDetail", "description": "The catalog item with updated eligibility information." } }, "required": [ "object" ], "title": "ProductCatalogItemEligibilityUpdatedWebhookData", "type": "object" }, "ProductCatalogItemEligibilityUpdatedWebhookPayload": { "properties": { "data": { "$ref": "#/components/schemas/ProductCatalogItemEligibilityUpdatedWebhookData", "description": "The webhook payload data." }, "event_type": { "description": "The type of event that triggered this webhook (e.g., 'product_catalog.item.eligibility_updated').", "title": "Event Type", "type": "string" }, "timestamp": { "description": "ISO-8601 timestamp of when the event occurred.", "title": "Timestamp", "type": "string" } }, "required": [ "event_type", "timestamp", "data" ], "title": "ProductCatalogItemEligibilityUpdatedWebhookPayload", "type": "object" }, "PurchaseKind": { "description": "Enum for the kind of payment\n\nThis determines how the payment will be captured\n- OneTimePayment means captured by Truemed automatically\n- Authorization means manually captured by the requesting merchant", "enum": [ "one_time_payment", "authorization" ], "title": "PurchaseKind", "type": "string" }, "QualificationSessionAmountDetail": { "properties": { "amount": { "description": "Amount in cents.", "exclusiveMinimum": 0.0, "maximum": 100000000.0, "title": "Amount", "type": "integer" }, "display_level": { "$ref": "#/components/schemas/QualificationSessionAmountDisplayLevel", "description": "Which level of a Truemed-generated receipt this adjustment should be displayed at. `order` places the entry in the order-level summary section, rolling up entries with the same `name` across every line item into a single row \u2014 use this for cart-wide concepts you've allocated across items, like shipping, tax, or a promo code that applies to the whole order. `line_item` renders the entry inline with its line item \u2014 use this for genuinely per-item adjustments like a single-item upgrade fee." }, "name": { "description": "Name of this amount component (e.g. 'Tax', 'Shipping', 'Handling', 'Color Upgrade').", "maxLength": 255, "title": "Name", "type": "string" } }, "required": [ "name", "amount", "display_level" ], "title": "QualificationSessionAmountDetail", "type": "object" }, "QualificationSessionAmountDisplayLevel": { "description": "Which level of a Truemed-generated receipt an adjustment should be displayed at.", "enum": [ "order", "line_item" ], "title": "QualificationSessionAmountDisplayLevel", "type": "string" }, "QualificationSessionItemAmountDetails": { "properties": { "additional_charges_details": { "anyOf": [ { "items": { "$ref": "#/components/schemas/QualificationSessionAmountDetail" }, "maxItems": 250, "type": "array" }, { "type": "null" } ], "description": "Detailed breakdown of additional charges applied to this line item. Allocate cart-wide concepts like shipping or tax across your line items and tag each entry with `display_level=order` so receipts roll them back up into a single line.", "title": "Additional Charges Details" }, "discounts_details": { "anyOf": [ { "items": { "$ref": "#/components/schemas/QualificationSessionAmountDetail" }, "maxItems": 250, "type": "array" }, { "type": "null" } ], "description": "Detailed breakdown of discounts applied to this line item. Allocate cart-wide promo codes across your line items and tag each entry with `display_level=order` so receipts roll them back up into a single line.", "title": "Discounts Details" }, "total_additional_charges": { "anyOf": [ { "exclusiveMinimum": 0.0, "maximum": 100000000.0, "type": "integer" }, { "type": "null" } ], "description": "Total additional charges applied to this line item, in cents. When `additional_charges_details` is also provided, this should equal the sum of its entries.", "title": "Total Additional Charges" }, "total_discounts": { "anyOf": [ { "exclusiveMinimum": 0.0, "maximum": 100000000.0, "type": "integer" }, { "type": "null" } ], "description": "Total discounts applied to this line item, in cents. When `discounts_details` is also provided, this should equal the sum of its entries.", "title": "Total Discounts" } }, "title": "QualificationSessionItemAmountDetails", "type": "object" }, "QualificationSessionListResponse": { "properties": { "pagination": { "anyOf": [ { "$ref": "#/components/schemas/PaginationBody" }, { "type": "null" } ], "description": "A pagination object with information about the current page, page size, total count, and last page." }, "qualification_sessions": { "description": "An array of qualification_session objects.", "items": { "$ref": "#/components/schemas/QualificationSessionResponse" }, "title": "Qualification Sessions", "type": "array" } }, "required": [ "qualification_sessions" ], "title": "QualificationSessionListResponse", "type": "object" }, "QualificationSessionOrderItem": { "properties": { "amount_details": { "anyOf": [ { "$ref": "#/components/schemas/QualificationSessionItemAmountDetails" }, { "type": "null" } ], "description": "Optional per-line-item breakdown of discounts and additional charges. All adjustments \u2014 cart-wide and item-specific \u2014 live here; allocate cart-wide concepts (shipping, tax, order-level promos) across your line items and tag each entry with `display_level=order` so Truemed-generated receipts roll them back up into a single line." }, "item_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Optional identifier you assign to this line item.", "title": "Item Id" }, "name": { "description": "Display name of the item.", "maxLength": 255, "title": "Name", "type": "string" }, "price": { "description": "Unit price in cents.", "exclusiveMinimum": 0.0, "maximum": 100000000.0, "title": "Price", "type": "integer" }, "quantity": { "description": "Quantity of the item ordered.", "exclusiveMinimum": 0.0, "title": "Quantity", "type": "integer" }, "sku": { "description": "The SKU for this item, from your product catalog.", "maxLength": 255, "title": "Sku", "type": "string" } }, "required": [ "name", "quantity", "price", "sku" ], "title": "QualificationSessionOrderItem", "type": "object" }, "QualificationSessionProcessingWebhookPayload": { "properties": { "event": { "const": "qualification_session.processing", "description": "The event type identifier. Always `qualification_session.processing` for this webhook.", "title": "Event", "type": "string" }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "JSON-encoded string echoing the metadata supplied when the qualification session was created. `null` if no metadata was supplied.", "title": "Metadata" }, "qualification_session_id": { "description": "The `qualification_session_id` returned by Truemed when the qualification session was created via `create_qualification_session`.", "title": "Qualification Session Id", "type": "string" }, "sales_channel_id": { "description": "The id of the sales channel this qualification session belongs to.", "title": "Sales Channel Id", "type": "string" } }, "required": [ "event", "qualification_session_id", "sales_channel_id" ], "title": "QualificationSessionProcessingWebhookPayload", "type": "object" }, "QualificationSessionResponse": { "properties": { "charge_group_created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the charge group was created.", "title": "Charge Group Created At" }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the qualification session was created.", "title": "Created At" }, "customer_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The customer's status.", "title": "Customer Status" }, "eligible_amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The eligible amount for this qualification.", "title": "Eligible Amount" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The email address of the consumer who completed the qualification session.", "title": "Email" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "The datetime at which the Letter-of-Medical-Necessity expires.", "title": "Expires At" }, "fee": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The fee amount for this qualification.", "title": "Fee" }, "lmn_reviewed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the Letter of Medical Necessity was reviewed.", "title": "Lmn Reviewed At" }, "qualification_session_id": { "description": "The id of the qualification session.", "title": "Qualification Session Id", "type": "string" }, "session_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The type of qualification session.", "title": "Session Type" }, "skus_param": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The SKUs parameter from the qualification session.", "title": "Skus Param" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The source provided in the qualification session redirect URL param.", "title": "Source" }, "status": { "$ref": "#/components/schemas/QualificationSessionStatusSummary", "description": "The status of the qualification session.\n\nOne of:\n- `pending` \u2014 The session was created; the shopper hasn't completed the survey yet.\n- `processing` \u2014 The shopper completed the survey and it is under review.\n- `approved` \u2014 The shopper holds a valid Letter of Medical Necessity covering the items in this order.\n- `rejected` \u2014 The shopper is ineligible for a Letter of Medical Necessity for the items in this order." }, "stripe_invoice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The Stripe invoice ID associated with this qualification.", "title": "Stripe Invoice Id" }, "stripe_invoice_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The Stripe invoice number.", "title": "Stripe Invoice Number" }, "stripe_invoice_paid_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the Stripe invoice was paid.", "title": "Stripe Invoice Paid At" }, "user_business_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The user's business ID.", "title": "User Business Id" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The user_id provided in the qualification session redirect URL param.", "title": "User Id" }, "user_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The user's name (may be null if PII is hidden).", "title": "User Name" } }, "required": [ "qualification_session_id", "status" ], "title": "QualificationSessionResponse", "type": "object" }, "QualificationSessionStatusSummary": { "description": "This enum is used to summarize the status of the qualification session.\n\nIt abstracts the internal nuances of the qualification session and LMN verification status. It is\nto be used by merchants external to Truemed.", "enum": [ "pending", "processing", "approved", "rejected" ], "title": "QualificationSessionStatusSummary", "type": "string", "x-fern-enum": { "pending": { "description": "The session was created; the shopper hasn't completed the survey yet." }, "processing": { "description": "The shopper completed the survey and it is under review." }, "approved": { "description": "The shopper holds a valid Letter of Medical Necessity covering the items in this order." }, "rejected": { "description": "The shopper is ineligible for a Letter of Medical Necessity for the items in this order." } } }, "QualificationSessionStatusUpdatedWebhookPayload": { "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The email address of the consumer who completed the qualification session.", "title": "Email" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "An optional datetime at which the Letter-of-Medical-Necessity expires.", "title": "Expires At" }, "qualification_session_id": { "description": "The `qualification_session_id` returned by Truemed when the qualification session was created via `create_qualification_session`.", "title": "Qualification Session Id", "type": "string" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "An optional source, if provided in the redirect.", "title": "Source" }, "status": { "description": "The status of the qualification_session.", "title": "Status", "type": "string" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "An optional user_id, if provided in the redirect.", "title": "User Id" } }, "required": [ "qualification_session_id", "status" ], "title": "QualificationSessionStatusUpdatedWebhookPayload", "type": "object" }, "ReconciliationData": { "properties": { "charge_date": { "description": "Date the charge was created (YYYY-MM-DD).", "format": "date", "title": "Charge Date", "type": "string" }, "customer_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Anonymized customer identifier (replaces name and email when PII is hidden).", "title": "Customer Id" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Customer email address.", "title": "Email" }, "fee": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "description": "Truemed fee in dollars. Negative indicates an amount owed by the merchant.", "title": "Fee" }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Merchant-supplied metadata attached to the origin record, or null if absent.", "title": "Metadata" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Customer full name.", "title": "Name" }, "order_id": { "description": "Unique identifier for the order.", "title": "Order Id", "type": "string" }, "order_items": { "description": "Comma-separated list of order item names.", "title": "Order Items", "type": "string" }, "order_total": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "description": "Order total amount in dollars.", "title": "Order Total" }, "payment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External payment integration identifier.", "title": "Payment Id" }, "payout_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Date of the payout (YYYY-MM-DD), or null if not yet paid out.", "title": "Payout Date" }, "payout_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payout identifier, or null if not yet paid out.", "title": "Payout Id" }, "refund_needs_invoicing": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Whether the refund requires invoicing. Present only for fee rows; null otherwise.", "title": "Refund Needs Invoicing" }, "type": { "$ref": "#/components/schemas/ReconciliationDataType", "description": "Type of transaction data." } }, "required": [ "order_id", "payment_id", "charge_date", "type", "order_total", "fee", "payout_date", "payout_id", "order_items" ], "title": "ReconciliationData", "type": "object" }, "ReconciliationDataType": { "enum": [ "Charge", "Full Refund", "Partial Refund", "Dispute", "Fee", "Fee Refund" ], "title": "ReconciliationDataType", "type": "string" }, "RefundDetails": { "properties": { "amount": { "description": "The amount refunded, in cents.", "title": "Amount", "type": "integer" }, "id": { "description": "The UUID of the refund.", "title": "Id", "type": "string" }, "refunded_on": { "description": "The date the refund was made in ISO 8601 format. Example: \"2024-06-13T16:03:08.386Z\"", "format": "date-time", "title": "Refunded On", "type": "string" }, "truemed_fee_returned": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": 0, "description": "The amount of Truemed fees returned with this refund, in cents.", "title": "Truemed Fee Returned" } }, "required": [ "id", "amount", "refunded_on" ], "title": "RefundDetails", "type": "object" }, "RefundItemDetails": { "properties": { "item_id": { "description": "ID that uniquely identifies the item within the Payment; optionally specified when creating the payment and retrievable from payment session status or list payment sessions.", "title": "Item Id", "type": "string" }, "quantity": { "description": "The quantity of this particular item to being refunded of this item, up to `quantity_refundable` from payment session status or list payment sessions.", "title": "Quantity", "type": "integer" }, "total": { "description": "The total amount in cents of this particular item to being refunded of this item, up to `total_refundable` from payment session status or list payment sessions.", "title": "Total", "type": "integer" } }, "required": [ "item_id", "quantity", "total" ], "title": "RefundItemDetails", "type": "object" }, "RefundReasons": { "enum": [ "customer_request", "duplicate_payment", "fraudulent" ], "title": "RefundReasons", "type": "string" }, "StatusUpdateWebhookPayload": { "properties": { "authorize_amount": { "description": "The amount the user's card will be authorized for. In the case of `kind=one_time_payment`, this will always be the same as `capture_amount`", "title": "Authorize Amount", "type": "integer" }, "capture_amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The amount of funds actually captured. For payment sessions of `kind=one_time_payment` this field will always be present and will be the same as `authorize_amount`. For payment sessions of `kind=authorization` this field will not be present until the funds have been captured", "title": "Capture Amount" }, "captures": { "description": "List of capture details for the payment session", "items": { "$ref": "#/components/schemas/CaptureWebhookPayload" }, "title": "Captures", "type": "array" }, "created_at": { "description": "ISO-8601 timestamp of when the payment session was created", "title": "Created At", "type": "string" }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional field echoed back if present in the call to create_payment_session", "title": "Metadata" }, "order_items": { "description": "A list of order items with fields: item_id, name, price, quantity, sku, total_refundable (optional), quantity_refundable (optional), total_capturable (optional), quantity_capturable (optional)", "items": { "$ref": "#/components/schemas/PaymentSessionOrderItemDetails" }, "title": "Order Items", "type": "array" }, "payment_id": { "description": "The id returned to the partner by Truemed in response to a `create_payment_session` request", "title": "Payment Id", "type": "string" }, "payment_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional string indicating the payment_token used for the payment session. This field will be set only if the partner provided tokenize=True or a payment_token in the create_payment_session request", "title": "Payment Token" }, "status": { "$ref": "#/components/schemas/PaymentSessionStatus", "description": "The status of the payment from Truemed's perspective. Can be: captured, canceled, pending, processing, rejected, authorized, authorization_voided, authorization_expired" } }, "required": [ "payment_id", "status", "authorize_amount", "created_at", "captures", "order_items" ], "title": "StatusUpdateWebhookPayload", "type": "object" }, "SurveyConfig": { "properties": { "hide_back_to_checkout_cta": { "description": "Provide as true to hide the 'Back to checkout' CTA in the survey if the user fails to qualify.", "title": "Hide Back To Checkout Cta", "type": "boolean" } }, "required": [ "hide_back_to_checkout_cta" ], "title": "SurveyConfig", "type": "object" }, "TransactionReconciliationListResponse": { "properties": { "pagination": { "anyOf": [ { "$ref": "#/components/schemas/PaginationBody" }, { "type": "null" } ], "description": "A pagination object with information about the current page, page size, total count, and last page." }, "transactions": { "description": "Paginated list of transaction data.", "items": { "$ref": "#/components/schemas/ReconciliationData" }, "title": "Transactions", "type": "array" } }, "required": [ "transactions" ], "title": "TransactionReconciliationListResponse", "type": "object" }, "TruemedCheckoutMethodItemInfo": { "properties": { "name": { "description": "The name of the catalog item.", "title": "Name", "type": "string" }, "product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The product ID of the parent product which this catalog item is a variant of.", "title": "Product Id" }, "sku": { "description": "The SKU of the catalog item.", "title": "Sku", "type": "string" } }, "required": [ "sku", "name" ], "title": "TruemedCheckoutMethodItemInfo", "type": "object" }, "TruemedCheckoutMethodRequest": { "properties": { "items": { "description": "The items to check eligibility for.", "items": { "$ref": "#/components/schemas/TruemedCheckoutMethodItemInfo" }, "maxItems": 1000, "minItems": 1, "title": "Items", "type": "array" } }, "required": [ "items" ], "title": "TruemedCheckoutMethodRequest", "type": "object" }, "TruemedCheckoutMethodResponse": { "properties": { "enabled": { "description": "Whether the set of items is enabled for checkout with Truemed.", "title": "Enabled", "type": "boolean" } }, "required": [ "enabled" ], "title": "TruemedCheckoutMethodResponse", "type": "object" }, "UpdateItemRequest": { "properties": { "description": { "description": "The description of the item.", "title": "Description", "type": "string" }, "gtin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The GTIN of the catalog item.", "title": "Gtin" }, "image_urls": { "description": "An array of image URLs of the item.", "items": { "type": "string" }, "maxItems": 10, "minItems": 1, "title": "Image Urls", "type": "array" }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional metadata string for the catalog item.", "title": "Metadata" }, "name": { "description": "The name of the catalog item.", "title": "Name", "type": "string" }, "product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The product ID of the product which this catalog item is a variant of.", "title": "Product Id" }, "sku": { "description": "The SKU of the catalog item.", "title": "Sku", "type": "string" }, "url": { "description": "The display page URL for the item.", "title": "Url", "type": "string" } }, "required": [ "sku", "name", "description", "url", "image_urls" ], "title": "UpdateItemRequest", "type": "object" }, "UpdateItemResponse": { "properties": {}, "title": "UpdateItemResponse", "type": "object" }, "UpdatePaymentTokenRequest": { "properties": { "failure_url": { "description": "Where Truemed should redirect the customer after unsuccessfully completing the next action. In the case of a health survey, this applies to the user clicking the back or cancel buttons on the survey.", "title": "Failure Url", "type": "string" }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Merchants can use this free-form field to store extra information with the payment token", "title": "Metadata" }, "order_items": { "anyOf": [ { "items": { "$ref": "#/components/schemas/UpdatedOrderItemsRequest" }, "type": "array" }, { "type": "null" } ], "description": "Updated list of items for this subscription", "title": "Order Items" }, "renew_eligibility": { "default": false, "description": "Set to true to allow the customer to requalify within 30 days of LMN expiration. Use lmn_expires_at from Retrieve or List Payment Token responses or the Payment Token Updated Webhook payload to identify upcoming expirations. This is helpful to avoid interruptions to ongoing subscriptions.", "title": "Renew Eligibility", "type": "boolean" }, "success_url": { "description": "Where Truemed should redirect the customer after successfully completing the next action", "title": "Success Url", "type": "string" }, "update_card_info": { "default": false, "description": "Set to true to allow the Truemed checkout flow to update the user's card information", "title": "Update Card Info", "type": "boolean" }, "use_iframe": { "default": false, "description": "If true, the customer should be redirected to the `redirect_url` using an iframe.", "title": "Use Iframe", "type": "boolean" } }, "required": [ "success_url", "failure_url" ], "title": "UpdatePaymentTokenRequest", "type": "object" }, "UpdatePaymentTokenResponse": { "properties": { "next_action": { "$ref": "#/components/schemas/NextActionType", "description": "Next action required for this payment token, if any." }, "redirect_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A URI through which the customer can correct the payment_token.", "title": "Redirect Url" } }, "required": [ "next_action", "redirect_url" ], "title": "UpdatePaymentTokenResponse", "type": "object" }, "UpdateQualificationSessionRequest": { "properties": { "failure_url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "description": "Optional failure redirect URL. Has no effect once the qualification session reaches a terminal status.", "title": "Failure Url" }, "idempotency_key": { "description": "A unique key for safely retrying the request, scoped to this qualification session. Duplicate POSTs with the same key against the same qualification session are deduplicated and return the original response.", "maxLength": 255, "title": "Idempotency Key", "type": "string" }, "metadata": { "anyOf": [ { "maxLength": 4096, "type": "string" }, { "type": "null" } ], "description": "Optional metadata string (JSON-encoded by convention).", "title": "Metadata" }, "success_url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "description": "Optional success redirect URL. Has no effect once the qualification session reaches a terminal status.", "title": "Success Url" }, "user_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Your stable, opaque identifier for the shopper. Can only be set when the qualification session does not already have one \u2014 attempting to overwrite an existing value returns the `user_id_already_set` error. To correct a previously set value, contact Truemed support.", "title": "User Id" } }, "required": [ "idempotency_key" ], "title": "UpdateQualificationSessionRequest", "type": "object" }, "UpdateQualificationSessionResponse": { "properties": { "qualification_session_id": { "description": "The qualification_session_id that was updated (echoed from the path param).", "title": "Qualification Session Id", "type": "string" }, "status": { "$ref": "#/components/schemas/QualificationSessionStatusSummary", "description": "Current status summary of the qualification session. This endpoint does not change the status.\n\nOne of:\n- `pending` \u2014 The session was created; the shopper hasn't completed the survey yet.\n- `processing` \u2014 The shopper completed the survey and it is under review.\n- `approved` \u2014 The shopper holds a valid Letter of Medical Necessity covering the items in this order.\n- `rejected` \u2014 The shopper is ineligible for a Letter of Medical Necessity for the items in this order." } }, "required": [ "qualification_session_id", "status" ], "title": "UpdateQualificationSessionResponse", "type": "object" }, "UpdatedOrderItemsRequest": { "properties": { "name": { "description": "The name of the order item", "title": "Name", "type": "string" }, "sku": { "description": "The SKU of the item", "title": "Sku", "type": "string" } }, "required": [ "name", "sku" ], "title": "UpdatedOrderItemsRequest", "type": "object" }, "UserDetails": { "properties": { "business_id": { "description": "The unique business ID of the user.", "title": "Business Id", "type": "string" }, "email": { "description": "The email of the user who executed the payment.", "title": "Email", "type": "string" }, "name": { "description": "The name of the user who executed the payment.", "title": "Name", "type": "string" } }, "required": [ "business_id", "email", "name" ], "title": "UserDetails", "type": "object" } }, "securitySchemes": { "truemed-api-key-rest": { "description": "Sales channel API key for merchant server-to-server authentication", "in": "header", "name": "x-truemed-api-key", "type": "apiKey" }, "truemed-api-key-webhook": { "description": "API key for webhook authentication (sent by Truemed)", "in": "header", "name": "x-truemed-api-key", "type": "apiKey" } } } }