{
"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.13.3"
},
"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": "APIs for listing and inspecting card disputes and accepting a loss.",
"name": "Disputes"
},
{
"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": "Tell Truemed what you sell, and learn what may qualify for HSA/FSA spending before a shopper reaches checkout. Truemed reviews what you send, reports each eligibility decision on a webhook, and lets you read it back at any time.",
"name": "Product Catalog"
},
{
"description": "Read which items can be charged to an HSA/FSA card. **Catalog eligibility** answers it for your catalog as a whole; **customer eligibility** answers it for one customer, keyed on either their payment token or the provision request that preceded it. Mark eligible items before checkout so the split across cards is never a surprise, and read when a customer's coverage expires so you can prompt them to requalify on your own schedule.",
"name": "Eligibility"
},
{
"description": "APIs for uploading and retrieving files (e.g. dispute evidence) referenced by other resources.",
"name": "Files"
},
{
"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- `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- `request_multicapture` **(Optional)**: `True` or `False` - set to `True` to opt this authorization into [multiple partial captures](/guides/setup/api/payment-sessions/manual-delayed-capture#capturing-in-multiple-parts).\n - **IMPORTANT**: This field requires multi-capture to be enabled on your sales channel, and cannot be combined with `tokenize=true` or `payment_token`. Otherwise the request fails with `FeatureNotEnabled`.\n - Only meaningful with `kind=authorization`. On a `one_time_payment` the charge captures immediately, so the flag is accepted but does nothing.\n - Requesting multi-capture does not guarantee it. The card network decides at authorization time, so a later capture sent with `final: false` can still be rejected.\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_id`, and 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**How `order_items` is compared.** Line order does not matter, and neither does the order of the entries inside a line's `amount_details`. A cart carrying the same line twice must replay with it twice. `item_id` is part of a line's identity: omit it and Truemed provisions one, so a retry that adds your own id is rejected. Send the same `item_id` on both calls, or omit it on both.\n\nThe `400` carries no payment session `id`. If you lost the original response, find the session with [list payment sessions](/api-reference/payment-sessions/list-payment-session).\n\n### iFrame Payment Session\n\nIf `use_iframe` is set to `true`, `redirect_url` will be iframe-compatible. When the customer\nfinishes, the iframe posts one completion message to your page:\n\n```json\n{ \"success\": true, \"redirectUrl\": \"https://example.com/success\" }\n```\n\n`redirectUrl` echoes the `success_url` or `failure_url` from your request, matching `success`. See\nthe [Embedded Checkout guide](/guides/setup/api/payment-sessions/i-frame-payment-session) for how to\nrender the flow, validate the message's origin, and handle it.\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 is not enabled - for example Stripe configuration, or `request_multicapture=true` on a sales channel without multi-capture enabled or in combination with `tokenize` or `payment_token`\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",
"value": {
"error": "FeatureNotEnabled",
"message": "Bad Request"
}
},
"idempotencyviolation": {
"summary": "IdempotencyViolation",
"value": {
"error": "IdempotencyViolation",
"message": "Bad Request"
}
},
"invalidrequestparameter": {
"summary": "InvalidRequestParameter",
"value": {
"error": "InvalidRequestParameter",
"message": "Bad Request"
}
},
"missingrequiredparameter": {
"summary": "MissingRequiredParameter",
"value": {
"error": "MissingRequiredParameter",
"message": "Bad Request"
}
},
"orderitemsinvalid": {
"summary": "OrderItemsInvalid",
"value": {
"error": "OrderItemsInvalid",
"message": "Bad Request"
}
},
"sessionpending": {
"summary": "SessionPending",
"value": {
"error": "SessionPending",
"message": "Bad Request"
}
},
"tokenizenotsupported": {
"summary": "TokenizeNotSupported",
"value": {
"error": "TokenizeNotSupported",
"message": "Bad Request"
}
},
"totalamountinvalid": {
"summary": "TotalAmountInvalid",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/CreatePaymentSessionBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Page not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"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).\n- `capture_failed_on` **(Optional)** - the time the capture permanently failed. Present only for the\n rare session whose capture could not be completed; null otherwise.\n- `capture_failed_details` **(Optional)** - a generic message indicating the capture could not be\n completed. Null when `capture_failed_on` is null.\n- `capture_failed_amount_collected` **(Optional)** - funds already collected on a partially-charged\n split payment before the capture failed; null otherwise.",
"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",
"value": {
"error": "MissingField",
"message": "Bad Request"
}
},
"totalamountinvalid": {
"summary": "TotalAmountInvalid",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/RetrievePaymentSessionBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"invalidpaymentid": {
"summary": "InvalidPaymentId",
"value": {
"error": "InvalidPaymentId",
"message": "Payment not found."
}
},
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Resource not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/RetrievePaymentSessionNotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error."
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"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",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/ListPaymentSessionBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Page not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"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/setup/api/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- **`item_details`** *(Required)* - The items included in this capture. Each entry references an `item_id` from the payment session's `order_items`, and `total_amount` must equal the sum of the entries' `total` values.\n - A line keeps the same effective per-unit cost (`total / quantity`) across every capture it appears in.\n- **`final`** *(Optional, defaults to `true`)* - Set to `false` to leave the uncaptured remainder of the authorization held for a later capture. This requires [multi-capture](/guides/setup/api/payment-sessions/manual-delayed-capture#capturing-in-multiple-parts): the payment session must have been created with `request_multicapture: true`, and the card network must have granted multi-capture on the authorization. Otherwise the request fails with `ValidationError`.\n - A capture with `final: true` releases whatever is still uncaptured back to the customer.\n - To release the uncaptured remainder without capturing more, send a final capture with `total_amount: 0` and empty `item_details`, or [void the session](/api-reference/payment-sessions/void-payment-session). A zero-amount final capture is accepted only after at least one earlier capture.\n - Order-level shipping, fees, and discounts are only accepted on a single capture that covers the whole order. Under multi-capture, carry them as line items instead.\n\n## Response Notes\n\n### Success Case\n\nHTTP Status: `200`\n\n- **`id`** - The ID of the payment session that was captured, the same value that `create_payment_session` returned.\n- **`capture_id`** - The ID of this capture. Pass it as `capture_id` to [Create Refund](/api-reference/payment-sessions/create-refund) to refund against this capture. The same ID is returned if the endpoint is called again with the same `idempotency_key`. It is omitted for a zero-amount final capture, which only releases the uncaptured remainder.\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 amount still capturable on the payment session. It is also returned when a non-final capture has a zero `total_amount`, when a zero-amount final capture is not preceded by another capture, or when order-level amounts are sent on a capture that does not cover the whole order.\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 - `InvalidItemizedData`: An `item_details` entry is invalid \u2014 a non-positive quantity, a negative total, a quantity or total beyond what remains capturable for that item, or a per-unit cost that differs from the item's existing captures. The `message` names the item and the rejected value.\n - `ValidationError`: The capture is not permitted in this configuration \u2014 for example `final: false` on an authorization that does not have multi-capture.\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",
"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",
"value": {
"error": "SessionCaptured",
"message": "Cannot capture a payment that has already been captured."
}
},
"sessionexpired": {
"summary": "SessionExpired",
"value": {
"error": "SessionExpired",
"message": "The auth hold for this payment session has expired."
}
},
"sessionpending": {
"summary": "SessionPending",
"value": {
"error": "SessionPending",
"message": "Session is still pending."
}
},
"sessionvoided": {
"summary": "SessionVoided",
"value": {
"error": "SessionVoided",
"message": "Session has been voided."
}
},
"totalamountinvalid": {
"summary": "TotalAmountInvalid",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/CapturePaymentSessionBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Resource not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"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",
"value": {
"error": "SessionAuthorized",
"message": "Payment session has been authorized, it must be voided, not canceled."
}
},
"sessioncaptured": {
"summary": "SessionCaptured",
"value": {
"error": "SessionCaptured",
"message": "Payment session has already been captured."
}
},
"totalamountinvalid": {
"summary": "TotalAmountInvalid",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/CancelPaymentSessionBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Resource not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"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/setup/api/payment-sessions/manual-delayed-capture).\n\nOn a [multi-capture](/guides/setup/api/payment-sessions/manual-delayed-capture#capturing-in-multiple-parts)\nsession that is `partially_captured`, a void keeps the amount already captured and releases the\nuncaptured remainder. The session then reports `captured`, and you can refund its captures.\n\nA void is rejected while a capture on the session is still processing. Retry after that capture\ncompletes.\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 received a final capture 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 - `ValidationError` - A capture on the session is still processing. Retry the void after\n that capture completes.\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",
"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",
"value": {
"error": "SessionCaptured",
"message": "Session has already been captured."
}
},
"sessionnotauthorized": {
"summary": "SessionNotAuthorized",
"value": {
"error": "SessionNotAuthorized",
"message": "Cannot void a payment that has not been authorized."
}
},
"sessionvoided": {
"summary": "SessionVoided",
"value": {
"error": "SessionVoided",
"message": "Cannot void a payment that has already been voided."
}
},
"totalamountinvalid": {
"summary": "TotalAmountInvalid",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/VoidPaymentSessionBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Resource not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"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### Itemizing a refund\n\n`amount` is what Truemed refunds. `item_details` tells Truemed how to attribute that amount across\nthe order's lines.\n\n- Set each `item_details[].total` to the amount you are refunding for that line. It cannot exceed\n that item's `total_refundable` from\n [Get Payment Status](/api-reference/payment-sessions/retrieve-payment-session).\n- Set `item_details[].quantity` to 0 to refund dollars without units. Use this for the rest of a line\n after an earlier partial refund already returned its units. The dollars stay on that line, and\n its eligibility determines how Truemed splits the refund across cards.\n- Across all lines, the totals must not sum above `amount`.\n- The totals may sum below `amount`. Truemed applies the remainder to the capture the refund targets.\n\n### Multi-capture sessions\n\nEach refund applies to one capture. Use the `capture_id` from the capture response, or `captures[].id`\nfrom [Get Payment Status](/api-reference/payment-sessions/retrieve-payment-session).\n\n- Pass `capture_id` when the session has more than one capture, or when any capture did not complete.\n- You can refund a capture while the session is still `partially_captured`. Every capture has already\n charged the customer, so the refund returns that money and the uncaptured remainder stays held for\n later captures. While the session is `partially_captured`, pass `capture_id`. Truemed rejects the\n refund if another capture is still processing.\n- To refund shipping or another amount with no line item, target the capture that charged it.\n- To refund more than one capture, send one refund per capture.\n- A refund never frees up authorization. Captures after a refund are still limited to the amount that\n was never captured.\n\n### Order-level charges and discounts\n\n`create_payment_session` accepts an `amount_details` object at the order level, carrying charges and\ndiscounts that belong to the order rather than to any single line. Shipping and tax behave the same\nway.\n\nBecause Truemed tracks `total_refundable` per item, an order-level amount appears in no item's\n`total_refundable`. For a full refund, set `amount` to the full captured amount and each\n`item_details[].total` to that item's `total_refundable`. The item totals then sum below `amount` by\nthe order-level amount, and Truemed applies that remainder to the capture the refund targets.\n\nOn a partial refund, `amount` sets how much of an order-level charge returns. To return none of it,\nset `amount` equal to the sum of your item totals.\n\n### How much returns to the HSA/FSA card\n\nTruemed derives the eligible amount of a refund from the lines you itemize:\n\n- When every itemized line qualifies for HSA/FSA spending, the whole `amount` counts as eligible.\n- Otherwise Truemed pro-rates `amount` by the eligible ratio of the itemized lines.\n- Eligible spending that the regular card paid returns there first. The remaining eligible amount\n returns to the HSA/FSA card, and the rest returns to the regular card.\n- Truemed caps each card's share at its remaining refundable balance. If the regular card cannot\n cover its share, the shortfall returns to the HSA/FSA card within that card's refundable balance.\n\n### Returning an amount that belongs to no item\n\nSome refunds have no line behind them: a goodwill credit for a late delivery, or shipping returned on\nits own. Omit `item_details` and send `amount` alone. An empty `item_details` list is the same request.\n\nWhen a refund names no items, Truemed treats the refund as HSA/FSA-eligible first, up to the remaining\neligible amount. Eligible spending that the regular card paid returns there first. Truemed then uses\nthe HSA/FSA card's refundable balance and returns the rest to the regular card.\nName the lines in `item_details` to allocate the refund by those lines' eligible share.\n\nTwo caps apply either way, both measured against earlier refunds. `amount` cannot exceed what the\norder still has left to return. The refund's eligible amount cannot exceed the eligible amount still\noutstanding. Once no eligible amount remains, later refunds go to the regular card first, subject to\neach card's refundable balance.\n\nItemizing is still worth doing when the refund does follow specific lines. It keeps each line's\nremaining refundable amount accurate and puts the refund against that line on the customer's receipt.\nWithout it the refund is allocated correctly and capped the same way, but it appears as an\norder-level adjustment and the individual lines keep their original refundable amounts.\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 - `ValidationError`: Truemed does not allow the refund in the session's current state. For example,\n `capture_id` is missing on a session with more than one capture, on a session with a capture that\n did not complete, or on a `partially_captured` session. Other causes: another capture or a void is\n still processing, or the session collected no funds.\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",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/CreateRefundBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Page not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"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 `provision_token_request_id` and a `redirect_url`. Persist the `provision_token_request_id` on your customer record before redirecting the customer \u2014 it is what links the `payment_token_updated` webhook back to them.\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`. Link it to existing data in your backend using the `provision_token_request_id` you persisted before the redirect, or the `metadata` you sent on the `create_payment_token` call \u2014 the webhook echoes both. It does not carry the customer's email or name.\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. When the customer\nfinishes, the iframe posts one completion message to your page:\n\n```json\n{ \"success\": true, \"redirectUrl\": \"https://example.com/success\" }\n```\n\n`redirectUrl` echoes the `success_url` or `failure_url` from your request, matching `success`. See\nthe [Embedded Checkout guide](/guides/setup/api/payment-sessions/i-frame-payment-session) for how to\nrender the flow, validate the message's origin, and handle it.\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",
"value": {
"error": "FeatureNotEnabled",
"message": "Bad Request"
}
},
"idempotencyviolation": {
"summary": "IdempotencyViolation",
"value": {
"error": "IdempotencyViolation",
"message": "The same idempotency key was used for different requests"
}
},
"invalidrequestparameter": {
"summary": "InvalidRequestParameter",
"value": {
"error": "InvalidRequestParameter",
"message": "Bad Request"
}
},
"totalamountinvalid": {
"summary": "TotalAmountInvalid",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
},
"waitingforverification": {
"summary": "WaitingForVerification",
"value": {
"error": "WaitingForVerification",
"message": "The lmn verification process is ongoing."
}
}
},
"schema": {
"$ref": "#/components/schemas/CreatePaymentTokenBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Page not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"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",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/RetrievePaymentTokenBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"invalidtoken": {
"summary": "InvalidToken",
"value": {
"error": "InvalidToken",
"message": "Payment Token not found"
}
},
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Resource not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/RetrievePaymentTokenNotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"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 whose `lmn_expires_at` is on or before this date (YYYY-MM-DD format, e.g., '2024-06-15'), including tokens whose LMN has already expired.",
"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",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/ListPaymentTokenBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Page not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"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. When the customer\nfinishes, the iframe posts one completion message to your page:\n\n```json\n{ \"success\": true, \"redirectUrl\": \"https://example.com/success\" }\n```\n\n`redirectUrl` echoes the `success_url` or `failure_url` from your request, matching `success`. See\nthe [Embedded Checkout guide](/guides/setup/api/payment-sessions/i-frame-payment-session) for how to\nrender the flow, validate the message's origin, and handle it.\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",
"value": {
"error": "FeatureNotEnabled",
"message": "Bad Request"
}
},
"totalamountinvalid": {
"summary": "TotalAmountInvalid",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/UpdatePaymentTokenBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"invalidtoken": {
"summary": "InvalidToken",
"value": {
"error": "InvalidToken",
"message": "Payment Token not found"
}
},
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Resource not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/UpdatePaymentTokenNotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"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",
"value": {
"error": "FeatureNotEnabled",
"message": "Bad Request"
}
},
"totalamountinvalid": {
"summary": "TotalAmountInvalid",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/DeletePaymentTokenBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Resource not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"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",
"value": {
"error": "FeatureNotEnabled",
"message": "Bad Request"
}
},
"totalamountinvalid": {
"summary": "TotalAmountInvalid",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/RetrievePaymentTokenProvisionRequestBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Provision request not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"description": "Not Implemented"
}
},
"security": [
{
"truemed-api-key-rest": []
}
],
"summary": "Retrieve the status of a payment token provision request",
"tags": [
"Payment Tokens"
]
}
},
"/api/v1/disputes/{business_id}": {
"get": {
"deprecated": false,
"description": "Retrieve a single dispute by its Truemed `dispute_id`, with everything you need to decide how to respond: its canonical state and phase, the reason code, the disputed amount and currency, the evidence deadline, and the recommended evidence for the dispute's reason. Only disputes on your own sales channel's payments are accessible \u2014 any other ID returns 404.\n\n## Response Notes\n\n`state` is processor-agnostic. Every dispute, whatever the processor, maps to one of eight canonical states:\n\n| State | Meaning |\n|-------|---------|\n| `inquiry` | A pre-dispute warning or retrieval request. Not yet a chargeback; no funds withdrawn. |\n| `needs_response` | An open chargeback awaiting your evidence by `due_by`. The only state you can `accept`. |\n| `under_review` | Evidence submitted; the processor or card network is deciding. |\n| `won` | Resolved in your favor; funds retained. |\n| `lost` | Resolved against you; funds withdrawn. |\n| `accepted` | You conceded the dispute (see Accept Dispute). |\n| `expired` | The evidence deadline passed with no response. |\n| `closed` | An inquiry that resolved without becoming a chargeback \u2014 a favorable no-contest outcome, tracked separately from `won`. |\n\n- `phase` (`inquiry`, `dispute`, `pre_arbitration`, `arbitration`) is **orthogonal** to `state`: it tells you which round of the lifecycle you're in, not whether the dispute is open or resolved.\n- `outcome` is null until the dispute reaches a terminal state (`won`, `lost`, `accepted`, `expired`, `closed`).\n- `amount` is the **original disputed amount in cents** and does not change with the outcome; `currency` is the ISO code.\n- `due_by` is set only while the dispute is challengeable \u2014 it's null for inquiries and for resolved disputes.\n- `evidence_requirements` is the recommended evidence for this dispute's `reason`, resolved by Truemed: a `merchant_explanation` narrative (Markdown) plus categories grouped by weight into `compelling`, `supporting`, and `other`, each entry carrying its canonical `category`, display `label`, helper `description`, and whether it takes free text and/or a file.\n- `counters` is the full chain of evidence submissions (counters) for this dispute across phases.\n- State, amounts, and deadlines are read-only and advance only through processor events. The only writable fields are exposed through Accept Dispute and Update Dispute Metadata.",
"operationId": "retrieveDispute",
"parameters": [
{
"deprecated": false,
"description": "The Truemed dispute ID (UUID).",
"in": "path",
"name": "business_id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"response": {
"summary": "Example",
"value": {
"amount": 8999,
"counters": [
{
"counter_id": "c7b1e2d3-4a5f-4b6c-9d8e-0f1a2b3c4d5e",
"created_at": "2026-01-21T09:15:00Z",
"evidence_items": [
{
"category": "shipping_tracking_number",
"file_ids": [],
"text": "1Z999AA10123456784"
},
{
"category": "shipping_documentation",
"file_ids": [
"f47ac10b-58cc-4372-a567-0e02b2c3d479"
],
"text": null
}
],
"phase": "dispute",
"revision": 3,
"state": "draft",
"submitted_at": null,
"submitted_by": null,
"updated_at": "2026-01-21T09:47:12Z"
}
],
"created_at": "2026-01-20T14:32:00Z",
"currency": "usd",
"dispute_id": "d1f8c2a4-9b3e-4c17-8a2d-5e6f7a8b9c0d",
"due_by": "2026-02-03T23:59:59Z",
"evidence_requirements": {
"compelling": [
{
"category": "shipping_tracking_number",
"description": "Carrier tracking number showing the order was delivered to the cardholder's address.",
"file": false,
"label": "Shipping tracking number",
"text": true
},
{
"category": "service_documentation",
"description": "Records showing the service was rendered, for service-based orders.",
"file": true,
"label": "Service documentation",
"text": true
},
{
"category": "service_date",
"description": "The date the service was provided.",
"file": false,
"label": "Service date",
"text": true
}
],
"merchant_explanation": "The cardholder says the order never arrived. Lead with carrier tracking that shows delivery to the cardholder's address and any signed proof of delivery; for service orders, provide service records and the service date. Supplement with your communications confirming the shipment.",
"other": [
{
"category": "receipt",
"description": "The order receipt or invoice.",
"file": true,
"label": "Receipt",
"text": false
},
{
"category": "customer_signature",
"description": "A signed order form or delivery receipt.",
"file": true,
"label": "Customer signature",
"text": false
}
],
"supporting": [
{
"category": "shipping_documentation",
"description": "Proof of shipment such as a carrier label or packing slip.",
"file": true,
"label": "Shipping documentation",
"text": false
},
{
"category": "customer_communication",
"description": "Emails or messages with the cardholder about the order or its delivery.",
"file": true,
"label": "Customer communication",
"text": true
}
]
},
"metadata": {
"assigned_to": "ops-disputes-team",
"internal_case_id": "OPS-4821"
},
"network_reason_code": "13.1",
"outcome": null,
"payment": {
"order_id": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
},
"phase": "dispute",
"prior_dispute_id": null,
"processor": "STRIPE",
"processor_dispute_id": "du_1Q9XyZ2eZvKYlo2CDeFgHiJk",
"reason": "product_not_received",
"resolved_at": null,
"state": "needs_response"
}
}
},
"schema": {
"$ref": "#/components/schemas/DisputeDetailResource"
}
}
},
"description": "Successful response"
},
"400": {
"content": {
"application/json": {
"examples": {
"totalamountinvalid": {
"summary": "TotalAmountInvalid",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/RetrieveDisputeBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Resource not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"description": "Not Implemented"
}
},
"security": [
{
"truemed-api-key-rest": []
}
],
"summary": "Retrieve a single dispute, including its canonical state, deadlines, and evidence requirements",
"tags": [
"Disputes"
]
}
},
"/api/v1/disputes": {
"get": {
"deprecated": false,
"description": "List the card disputes \u2014 chargebacks and the pre-dispute inquiries that precede them \u2014 raised against payments you've taken through Truemed. Use it to drive a disputes queue in your own dashboard, surface disputes whose evidence deadline is approaching, or reconcile against your records by processor dispute ID. Results are scoped to the sales channel your API key authenticates as: you only ever see disputes on your own payments.\n\nDisputes are returned newest first and paginated with `page` / `page_size` (default 30 per page, max 100). The response `pagination` object reports `current_page`, `page_size`, `total_count`, and `last_page`.\n\n## Request Notes\n\nAll filters are optional and combine with AND:\n\n- `state`, `phase`, `reason` \u2014 exact match on the canonical enums. See the Get Dispute endpoint for the full state model.\n- `amount_gte` / `amount_lte` \u2014 disputed amount in **cents**, inclusive on both bounds.\n- `created_gte` / `created_lte` \u2014 dispute creation time, **inclusive** on both bounds. Pass ISO 8601 datetimes, e.g. `2026-01-01T00:00:00Z`.\n- `due_before` \u2014 only disputes whose evidence deadline (`due_by`) falls **strictly before** this datetime. Disputes with no deadline \u2014 inquiries and already-resolved disputes both have a null `due_by` \u2014 are excluded by this filter. Use it together with `state=needs_response` to build a \"deadline approaching\" view.\n\n## Response Notes\n\nEach item is the same `Dispute` object returned by Get Dispute. Use the stable `dispute_id` (a Truemed UUID) for the detail, accept, and metadata endpoints; use `processor_dispute_id` (e.g. Stripe `du_\u2026`) to reconcile against the processor. State, amounts, and deadlines are read-only \u2014 they advance only through processor events, never through this API.",
"operationId": "listDispute",
"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 by canonical state.",
"in": "query",
"name": "state",
"required": false,
"schema": {
"type": "string"
}
},
{
"allowReserved": false,
"deprecated": false,
"description": "Filter by phase.",
"in": "query",
"name": "phase",
"required": false,
"schema": {
"type": "string"
}
},
{
"allowReserved": false,
"deprecated": false,
"description": "Filter by reason.",
"in": "query",
"name": "reason",
"required": false,
"schema": {
"type": "string"
}
},
{
"allowReserved": false,
"deprecated": false,
"description": "Only disputes with amount >= this (cents).",
"in": "query",
"name": "amount_gte",
"required": false,
"schema": {
"type": "integer"
}
},
{
"allowReserved": false,
"deprecated": false,
"description": "Only disputes with amount <= this (cents).",
"in": "query",
"name": "amount_lte",
"required": false,
"schema": {
"type": "integer"
}
},
{
"allowReserved": false,
"deprecated": false,
"description": "Only disputes created on/after this date.",
"in": "query",
"name": "created_gte",
"required": false,
"schema": {
"format": "date-time",
"type": "string"
}
},
{
"allowReserved": false,
"deprecated": false,
"description": "Only disputes created on/before this date.",
"in": "query",
"name": "created_lte",
"required": false,
"schema": {
"format": "date-time",
"type": "string"
}
},
{
"allowReserved": false,
"deprecated": false,
"description": "Only disputes whose evidence deadline is before this date.",
"in": "query",
"name": "due_before",
"required": false,
"schema": {
"format": "date-time",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"response": {
"summary": "Example",
"value": {
"disputes": [
{
"amount": 8999,
"counters": [],
"created_at": "2026-01-20T14:32:00Z",
"currency": "usd",
"dispute_id": "d1f8c2a4-9b3e-4c17-8a2d-5e6f7a8b9c0d",
"due_by": "2026-02-03T23:59:59Z",
"metadata": {
"internal_case_id": "OPS-4821"
},
"network_reason_code": "13.1",
"outcome": null,
"phase": "dispute",
"prior_dispute_id": null,
"processor": "STRIPE",
"processor_dispute_id": "du_1Q9XyZ2eZvKYlo2CDeFgHiJk",
"reason": "product_not_received",
"resolved_at": null,
"state": "needs_response"
},
{
"amount": 12500,
"counters": [],
"created_at": "2026-01-18T11:02:44Z",
"currency": "usd",
"dispute_id": "a2e9d1b3-7c4f-4a80-b6e1-2f3a4b5c6d7e",
"due_by": null,
"metadata": {},
"network_reason_code": "10.4",
"outcome": null,
"phase": "dispute",
"prior_dispute_id": null,
"processor": "STRIPE",
"processor_dispute_id": "du_1Q8WvU1dYuJXkn1BCdEfGhIj",
"reason": "fraudulent",
"resolved_at": null,
"state": "under_review"
}
],
"pagination": {
"count": 2,
"current_page": 1,
"last_page": 1,
"page_size": 25
}
}
}
},
"schema": {
"$ref": "#/components/schemas/DisputeListResponse"
}
}
},
"description": "Successful response"
},
"400": {
"content": {
"application/json": {
"examples": {
"totalamountinvalid": {
"summary": "TotalAmountInvalid",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/ListDisputeBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Page not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"description": "Not Implemented"
}
},
"security": [
{
"truemed-api-key-rest": []
}
],
"summary": "List disputes for the authenticated sales channel with filtering and pagination",
"tags": [
"Disputes"
]
}
},
"/api/v1/disputes/{business_id}/accept": {
"post": {
"deprecated": false,
"description": "Accept (concede) a dispute when you don't intend to contest it \u2014 for example when the charge was already refunded outside Truemed, or when contesting a low-value chargeback isn't worth the effort. Accepting concedes the disputed amount to the cardholder and closes the dispute with the processor.\n\nThis is **terminal**: the dispute moves to the `accepted` state and cannot be reopened. Only disputes in `needs_response` (an open chargeback awaiting evidence) can be accepted. Inquiries are warnings rather than chargebacks, and disputes already in a terminal state are immutable \u2014 accepting either returns `400`. The call is idempotent: accepting a dispute that's already `accepted` returns its current state instead of erroring, so a retried request is safe.",
"operationId": "acceptDispute",
"parameters": [
{
"deprecated": false,
"description": "The Truemed dispute ID (UUID).",
"in": "path",
"name": "business_id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DisputeResource"
}
}
},
"description": "Successful response"
},
"400": {
"content": {
"application/json": {
"examples": {
"badrequest": {
"summary": "BadRequest",
"value": {
"error": "BadRequest",
"message": "Bad Request"
}
},
"totalamountinvalid": {
"summary": "TotalAmountInvalid",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/AcceptDisputeBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Resource not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"description": "Not Implemented"
}
},
"security": [
{
"truemed-api-key-rest": []
}
],
"summary": "Accept (concede) a dispute, conceding the disputed amount",
"tags": [
"Disputes"
]
}
},
"/api/v1/disputes/{business_id}/counters": {
"post": {
"deprecated": false,
"description": "Start composing your evidence response to a dispute by creating a draft \"counter\". A counter holds your categorized evidence (each item is a canonical evidence category plus free text and/or attached files) for one round of a dispute, and is continuously saved as a draft so you don't lose work before submitting.\n\nThere is **at most one open draft per dispute round**. Calling this when a draft already exists returns that draft rather than creating a duplicate, so it's safe to call on page load. Any attached `file_ids` must reference files you uploaded via the Files API; referencing a file you don't own returns `422`.",
"operationId": "createDisputeCounter",
"parameters": [
{
"deprecated": false,
"description": "The Truemed dispute ID (UUID).",
"in": "path",
"name": "business_id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CounterCreateRequest"
}
}
},
"description": "Request body for CounterCreateRequest",
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CounterResource"
}
}
},
"description": "Successful response"
},
"400": {
"content": {
"application/json": {
"examples": {
"totalamountinvalid": {
"summary": "TotalAmountInvalid",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/CreateDisputeCounterBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Page not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"description": "Not Implemented"
}
},
"security": [
{
"truemed-api-key-rest": []
}
],
"summary": "Create a draft evidence counter for a dispute",
"tags": [
"Disputes"
]
}
},
"/api/v1/disputes/{business_id}/counters/{counter_id}": {
"post": {
"deprecated": false,
"description": "Save a draft counter's evidence. This is a full replacement of the draft's `evidence_items`, built for autosave \u2014 call it as the merchant edits. Only a counter still in the `draft` state can be saved; saving a submitted or withdrawn counter returns `400`.\n\nPass the `revision` you last read. If the counter changed since then (e.g. another tab saved it), the request is rejected with `409` so you can reload rather than silently clobber the newer edit. Any attached `file_ids` must reference files you own, or the save is rejected with `422`.",
"operationId": "updateDisputeCounter",
"parameters": [
{
"deprecated": false,
"description": "The Truemed dispute ID (UUID).",
"in": "path",
"name": "business_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"deprecated": false,
"description": "The Truemed counter ID (UUID).",
"in": "path",
"name": "counter_id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CounterUpsertRequest"
}
}
},
"description": "Request body for CounterUpsertRequest",
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CounterResource"
}
}
},
"description": "Successful response"
},
"400": {
"content": {
"application/json": {
"examples": {
"totalamountinvalid": {
"summary": "TotalAmountInvalid",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/UpdateDisputeCounterBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Resource not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"description": "Not Implemented"
}
},
"security": [
{
"truemed-api-key-rest": []
}
],
"summary": "Save (upsert) a draft evidence counter; optimistic-locked for autosave",
"tags": [
"Disputes"
]
}
},
"/api/v1/disputes/{business_id}/counters/{counter_id}/submit": {
"post": {
"deprecated": false,
"description": "Submit a draft counter's evidence to the payment processor. This is **one-shot and terminal for this round**: the evidence is sent to the processor as your final response, the counter moves to `submitted`, and it can no longer be edited.\n\nOnly a `draft` counter on a dispute that is currently awaiting a response (e.g. Stripe `needs_response`) can be submitted \u2014 otherwise the call returns `400`. Every attached file must both belong to you and have passed a malware scan (`clean`); otherwise the submission is rejected with `422` and nothing is sent. The dispute itself transitions (e.g. to `under_review`) when the processor's webhook confirms receipt, not synchronously here.",
"operationId": "submitDisputeCounter",
"parameters": [
{
"deprecated": false,
"description": "The Truemed dispute ID (UUID).",
"in": "path",
"name": "business_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"deprecated": false,
"description": "The Truemed counter ID (UUID).",
"in": "path",
"name": "counter_id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CounterResource"
}
}
},
"description": "Successful response"
},
"400": {
"content": {
"application/json": {
"examples": {
"totalamountinvalid": {
"summary": "TotalAmountInvalid",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/SubmitDisputeCounterBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Resource not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"description": "Not Implemented"
}
},
"security": [
{
"truemed-api-key-rest": []
}
],
"summary": "Submit a draft evidence counter to the processor (one-shot)",
"tags": [
"Disputes"
]
}
},
"/api/v1/disputes/{business_id}/counters/{counter_id}/withdraw": {
"post": {
"deprecated": false,
"description": "Discard a draft counter you no longer want. The counter moves to `withdrawn` and stops appearing in the dispute's counter list. Only a `draft` can be withdrawn \u2014 withdrawing a submitted counter returns `400` (a submitted response is already with the processor and can't be retracted here).",
"operationId": "withdrawDisputeCounter",
"parameters": [
{
"deprecated": false,
"description": "The Truemed dispute ID (UUID).",
"in": "path",
"name": "business_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"deprecated": false,
"description": "The Truemed counter ID (UUID).",
"in": "path",
"name": "counter_id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CounterResource"
}
}
},
"description": "Successful response"
},
"400": {
"content": {
"application/json": {
"examples": {
"totalamountinvalid": {
"summary": "TotalAmountInvalid",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/WithdrawDisputeCounterBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Resource not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"description": "Not Implemented"
}
},
"security": [
{
"truemed-api-key-rest": []
}
],
"summary": "Withdraw (discard) a draft evidence counter",
"tags": [
"Disputes"
]
}
},
"/api/v1/disputes/{business_id}/metadata": {
"post": {
"deprecated": false,
"description": "Attach your own metadata to a dispute \u2014 an internal case ID, the teammate who owns it, a link to your evidence workspace, free-form notes \u2014 so you can correlate Truemed disputes with your own systems.\n\nThis is a **full replace**, not a merge: the `metadata` object you send overwrites whatever was stored, so include every key you want to keep. Metadata is the only writable part of a dispute; its state, phase, reason, amounts, and deadlines are owned by the processor and are read-only. Scoped to your sales channel \u2014 you can only update metadata on your own disputes.",
"operationId": "updateDisputeMetadata",
"parameters": [
{
"deprecated": false,
"description": "The Truemed dispute ID (UUID).",
"in": "path",
"name": "business_id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DisputeMetadataRequest"
}
}
},
"description": "Request body for DisputeMetadataRequest",
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DisputeResource"
}
}
},
"description": "Successful response"
},
"400": {
"content": {
"application/json": {
"examples": {
"totalamountinvalid": {
"summary": "TotalAmountInvalid",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/UpdateDisputeMetadataBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Resource not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"description": "Not Implemented"
}
},
"security": [
{
"truemed-api-key-rest": []
}
],
"summary": "Update a dispute's metadata (only metadata is mutable)",
"tags": [
"Disputes"
]
}
},
"/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",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/CreateQualificationSessionBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Page not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"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",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/RetrieveQualificationSessionBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Qualification session not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"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",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/ListQualificationSessionBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Page not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"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",
"value": {
"error": "BadRequest",
"message": "IDEMPOTENCY_VIOLATION"
}
},
"totalamountinvalid": {
"summary": "TotalAmountInvalid",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/UpdateQualificationSessionBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Qualification session not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"description": "Not Implemented"
}
},
"security": [
{
"truemed-api-key-rest": []
}
],
"summary": "Update mutable fields on a qualification session",
"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.\n\n### Computing the HSA/FSA-eligible amount\n\nItems eligible only for the margin over an everyday equivalent carry that equivalent's price as `comparable_item_price_cents`:\n\n```\neligible_amount = max(0, unit_price - comparable_item_price_cents) * quantity\n```\n\nIt is absent when the full price is eligible, and when the item cannot be charged to an HSA/FSA card.\n\n### Keeping `comparable_item_price_cents` current\n\nTruemed reviews these prices about monthly. A change fires no webhook and does not advance `updated_at`, so re-read the catalog in full at least monthly. The charged amount is settled at checkout.",
"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 no eligibility 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",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/ListCatalogItemsBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Page not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"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",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/TruemedCheckoutMethodBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Page not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"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",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/CreateItemBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Page not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"409": {
"content": {
"application/json": {
"examples": {
"conflict": {
"summary": "Conflict",
"value": {
"error": "Conflict",
"message": "Catalog Item with this SKU already exists."
}
}
},
"schema": {
"$ref": "#/components/schemas/CreateItemConflictResponse"
}
}
},
"description": "Conflict"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"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",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/UpdateItemBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "No catalog item found with the provided SKU."
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"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",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/GetItemDetailBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Page not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"description": "Not Implemented"
}
},
"security": [
{
"truemed-api-key-rest": []
}
],
"summary": "Retrieve details and eligibility status of a catalog item",
"tags": [
"Product Catalog"
]
}
},
"/api/v1/eligibility": {
"get": {
"deprecated": false,
"description": "Returns every item in your catalog that can be charged to an HSA/FSA card, with no customer in context.\n\nThis is **catalog eligibility** \u2014 a property of the product. An item appears here when its eligibility category\nis HSA/FSA-payable for your merchant account, whether it requires a Letter of Medical Necessity or is\npre-approved and requires none. It is the widest possible answer: everything a customer *could* be eligible\nfor, before anyone has qualified.\n\nWhether a *particular* customer can put one of these items on their HSA/FSA card is a separate question \u2014\n**customer eligibility** \u2014 answered by the keyed forms of this endpoint. Use this form to mark eligible items\nwherever you present your catalog, and a keyed form once you know who is shopping.\n\nBecause no customer is identified, `eligibility_status` and `lmn_expires_at` are both null. Nothing in the response depends\non a customer, so it is safe to cache for as long as your catalog is stable.",
"operationId": "retrieveCatalogEligibility",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EligibilityResponse"
}
}
},
"description": "Successful response"
},
"400": {
"content": {
"application/json": {
"examples": {
"totalamountinvalid": {
"summary": "TotalAmountInvalid",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/RetrieveCatalogEligibilityBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Page not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"description": "Not Implemented"
}
},
"security": [
{
"truemed-api-key-rest": []
}
],
"summary": "Retrieve HSA/FSA catalog eligibility",
"tags": [
"Eligibility"
]
}
},
"/api/v1/eligibility/provision_request/{provision_token_request_id}": {
"get": {
"deprecated": false,
"description": "Returns **customer eligibility** for a customer who does not hold a payment token yet, keyed on the provision\nrequest id you received from `create_payment_token`.\n\nThe token-keyed form and this one answer the same question \u2014 which items *this* customer can charge to their\nHSA/FSA card. Use this one for a customer's first order, where you have a provision request but no token;\nswitch to the token form once the token arrives.\n\nThe two are keyed differently, and that is deliberate. A provision request names a customer and nothing else,\nso this form counts the letters that customer earned on your sales channel. The token form has a token to\ncount letters through as well, and counts both.\n\nThe window this form exists for is the one before a token: the customer has answered the survey, no clinician\nhas decided, so nothing has been minted to key the token form on, and you still need something to present your\ncatalog with. `pending` is the ordinary answer here, where on the token form it is the rare one. In that state\n`items` carries what the survey predicts the letter will cover, intersected with your catalog, and\n`lmn_expires_at` is null because no letter exists yet. Those items are a prediction, not a decision \u2014 present\nthem as provisional. `items` is empty only while the survey itself is unfinished.\n\nOnce a clinician decides, this key keeps working and starts answering exactly as the token-keyed form does:\n`approved`, `expired`, `rejected`, or `never_requested`, with a real coverage date where one exists (inclusive,\nUTC). That makes\nit a reliable poll if the `payment_token.updated` webhook is ever lost \u2014 and unlike the Retrieve Provision Token\nRequest endpoint, whose `payment_token` is null for both outcomes, this one tells a pending letter apart from a\nrejected one.",
"operationId": "retrieveProvisionRequestEligibility",
"parameters": [
{
"deprecated": false,
"description": "The ID of the ProvisionTokenRequest returned by create_payment_token",
"in": "path",
"name": "provision_token_request_id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EligibilityResponse"
}
}
},
"description": "Successful response"
},
"400": {
"content": {
"application/json": {
"examples": {
"totalamountinvalid": {
"summary": "TotalAmountInvalid",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/RetrieveProvisionRequestEligibilityBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Provision request not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"description": "Not Implemented"
}
},
"security": [
{
"truemed-api-key-rest": []
}
],
"summary": "Retrieve HSA/FSA customer eligibility by provision request",
"tags": [
"Eligibility"
]
}
},
"/api/v1/eligibility/token/{token_id}": {
"get": {
"deprecated": false,
"description": "Returns the items *this* customer can charge to their HSA/FSA card, and when that stops being true.\n\nThis is **customer eligibility** \u2014 a property of the person rather than the product. It is catalog eligibility\nnarrowed to one customer: an item appears here only when they hold a verified, unexpired Letter of Medical\nNecessity covering its eligibility category, or when that category is pre-approved and needs no letter at all.\n\n`eligibility_status` and `lmn_expires_at` answer for the payment token you name, not for whoever holds it.\nThey count the letters reachable through the token together with the letters the holder earned on your sales\nchannel. A customer who answers our health survey under a second email address earns their letter on that\naddress while the token stays where it was minted, and counting both is what keeps that letter visible here.\nThe `payment_token.updated` webhook counts the same letters, so a token reads the same way on both surfaces.\nThe provision-request form answers for a customer who holds no token yet, and is keyed on the customer.\n\n`eligibility_status` is a statement of fact, not an instruction, and each value earns a different response from\nyou \u2014 the per-value meanings are listed on the enum. In short: `approved` is the steady state; `expired` is your\nrenewal trigger, while every item keeps charging to the backup card meanwhile; `never_requested` calls for a\nfirst-time qualification prompt rather than a renewal one; `rejected` means suppress the prompt rather than\nsending the customer round again, since we have already emailed them the outcome; and `pending` means wait.\n\n`pending` is rare on this form, because a payment token is normally minted only once a letter has been decided.\nIt appears when a customer who is not currently covered has a survey under review \u2014 a requalification in\nflight, most often.\n\nAn empty `items` list under `approved` is worth reporting to us rather than to your customer: it means a live\nqualification exists but nothing in your catalog falls under it any more, which a re-survey cannot fix.\n\nRead it on whatever schedule suits you; the answer is stable through `lmn_expires_at` (inclusive, UTC).",
"operationId": "retrieveTokenEligibility",
"parameters": [
{
"deprecated": false,
"description": "The payment token returned by create_payment_token, in its prefixed form",
"in": "path",
"name": "token_id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EligibilityResponse"
}
}
},
"description": "Successful response"
},
"400": {
"content": {
"application/json": {
"examples": {
"totalamountinvalid": {
"summary": "TotalAmountInvalid",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/RetrieveTokenEligibilityBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Payment token not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"description": "Not Implemented"
}
},
"security": [
{
"truemed-api-key-rest": []
}
],
"summary": "Retrieve HSA/FSA customer eligibility by payment token",
"tags": [
"Eligibility"
]
}
},
"/api/v1/files/create": {
"post": {
"deprecated": false,
"description": "Creates a file record and returns a presigned upload URL plus the form fields to include in the multipart POST.\n\nUpload the file directly to the returned URL, then reference it by `file_id` from other resources. The upload URL expires 10 minutes after creation, so request it as part of the same flow that performs the upload.\n\nEach `purpose` enforces its own MIME allowlist and maximum file size, validated before the presigned URL is issued \u2014 a `content_type` or `size_bytes` outside the purpose's limits is rejected with a 400.\n\n| Purpose | Allowed content types | Max file size |\n| --- | --- | --- |\n| `dispute_evidence` | `application/pdf`, `image/png`, `image/jpeg`, `image/tiff` | 5 MB |",
"operationId": "createFile",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileCreateRequest"
}
}
},
"description": "Request body for FileCreateRequest",
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileCreateResponse"
}
}
},
"description": "Successful response"
},
"400": {
"content": {
"application/json": {
"examples": {
"totalamountinvalid": {
"summary": "TotalAmountInvalid",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/CreateFileBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Page not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"description": "Not Implemented"
}
},
"security": [
{
"truemed-api-key-rest": []
}
],
"summary": "Create a file and get a presigned upload URL",
"tags": [
"Files"
]
}
},
"/api/v1/files/{file_id}": {
"get": {
"deprecated": false,
"description": "Returns file metadata and, for clean-scanned files, a short-lived presigned download URL scoped to the owning sales channel. Files that are still scanning or quarantined are not downloadable.",
"operationId": "retrieveFile",
"parameters": [
{
"deprecated": false,
"description": "The public file identifier.",
"example": "01920a7e-9c3f-7b21-8e4a-2f6b1d0c5a9e",
"in": "path",
"name": "file_id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileDetailResponse"
}
}
},
"description": "Successful response"
},
"400": {
"content": {
"application/json": {
"examples": {
"totalamountinvalid": {
"summary": "TotalAmountInvalid",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/RetrieveFileBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Resource not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"description": "Not Implemented"
}
},
"security": [
{
"truemed-api-key-rest": []
}
],
"summary": "Retrieve a file and get a presigned download URL",
"tags": [
"Files"
]
}
},
"/api/v1/files": {
"get": {
"deprecated": false,
"description": "Returns metadata (including size) for files owned by the authenticated sales channel, optionally filtered by a set of ids and/or a purpose.",
"operationId": "listFile",
"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": "Comma-separated file ids to fetch, e.g. id1,id2.",
"example": [
"01920a7e-9c3f-7b21-8e4a-2f6b1d0c5a9e",
"01920a80-1d5e-7f34-9c02-7a3b4e6d8f10"
],
"explode": false,
"in": "query",
"name": "ids",
"required": false,
"schema": {
"items": {
"type": "string"
},
"type": "array"
},
"style": "form"
},
{
"allowReserved": false,
"deprecated": false,
"description": "Restrict to files of this purpose, e.g. dispute_evidence.",
"in": "query",
"name": "purpose",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileListResponse"
}
}
},
"description": "Successful response"
},
"400": {
"content": {
"application/json": {
"examples": {
"totalamountinvalid": {
"summary": "TotalAmountInvalid",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/ListFileBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Page not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"description": "Not Implemented"
}
},
"security": [
{
"truemed-api-key-rest": []
}
],
"summary": "List files and their metadata",
"tags": [
"Files"
]
}
},
"/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",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/ListPayoutReconciliationBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Page not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"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",
"value": {
"error": "TotalAmountInvalid",
"message": "Bad Request"
}
},
"validationerror": {
"summary": "ValidationError",
"value": {
"error": "ValidationError",
"message": "Bad Request"
}
}
},
"schema": {
"$ref": "#/components/schemas/ListTransactionReconciliationBadRequestResponse"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"examples": {
"notfound": {
"summary": "NotFound",
"value": {
"error": "NotFound",
"message": "Page not found"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
},
"description": "Not Found"
},
"405": {
"content": {
"application/json": {
"examples": {
"methodnotallowed": {
"summary": "MethodNotAllowed",
"value": {
"error": "MethodNotAllowed",
"message": "Method not allowed"
}
}
},
"schema": {
"$ref": "#/components/schemas/MethodNotAllowedResponse"
}
}
},
"description": "Method Not Allowed"
},
"500": {
"content": {
"application/json": {
"examples": {
"servererror": {
"summary": "ServerError",
"value": {
"error": "ServerError",
"message": "Internal server error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"examples": {
"notimplemented": {
"summary": "NotImplemented",
"value": {
"error": "NotImplemented",
"message": "Not Implemented"
}
}
},
"schema": {
"$ref": "#/components/schemas/NotImplementedResponse"
}
}
},
"description": "Not Implemented"
}
},
"security": [
{
"truemed-api-key-rest": []
}
],
"summary": "List reconciliation transaction rows",
"tags": [
"Reconciliations"
]
}
}
},
"webhooks": {
"disputeclosed": {
"post": {
"deprecated": false,
"description": "Truemed calls your endpoint when a dispute reaches a terminal state \u2014 a chargeback outcome (`won`, `lost`,\n`accepted`, or `expired`) or a surfaced inquiry the bank drops (`closed`). A re-sync of an already-terminal dispute\ndoes not re-fire this event, and an inquiry already terminal the first time Truemed sees it fires nothing at all.\n\n**Authentication**: Requests are HMAC-SHA256 signed. The `x-truemed-signature` header carries a timestamp and\nthe signature in the form `t=,v0=`. Compute HMAC-SHA256 over\n`.` with your webhook signing secret and compare the hex digest to `v0`. Sign the raw body\nbytes exactly as received, since re-serializing the JSON changes the bytes and breaks the signature.\n\n## Payload\n\nThe signed body is the standard Truemed envelope:\n\n- `webhook_delivery_id` - Delivery id (`dlv_\u2026`). Retries of the same event repeat the same value; use it to\n deduplicate.\n- `event_type` - The wire event name (`dispute.created`, `dispute.updated`, or `dispute.closed`).\n- `data` - The full canonical dispute, the same shape returned by `GET /api/v1/disputes/{dispute_id}` \u2014 including\n `dispute_id`, `state`, `phase`, `reason`, `amount`, `due_by`, `counters`, and `metadata`. Null fields are\n omitted. Payloads carry canonical Truemed fields and the public `dispute_id` UUID only, never raw processor\n shapes. Always key your records on `dispute_id`.\n\n(Unsigned legacy endpoints receive the `data` object as the flat top-level body, with no envelope and no\n`event_type`.)\n\nThe model is **notify, then fetch**: the snapshot is complete enough to act on directly, and you can re-fetch the\ndispute for authoritative state when a delivery is delayed or retried out of order.\n\n**Inquiries notify too, with one exception.** A live inquiry fires `dispute.created` / `dispute.updated` just like\na chargeback, so you can respond to pre-empt its escalation. If the bank later drops a surfaced inquiry, the terminal\n`closed` state fires `dispute.closed` \u2014 so `dispute.closed` marks any terminal outcome, whether a chargeback result\n(`won` / `lost` / `accepted` / `expired`) or a dropped inquiry (`closed`). The only silent case is an inquiry that\nopens and closes between webhook deliveries \u2014 already terminal the first time Truemed sees it \u2014 which fires no webhook.\n\n## Response Notes\n\nReturn HTTP `204` with an empty body. Truemed retries failed deliveries with backoff for up to 7 days.",
"operationId": "disputeClosedWebhook",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DisputeWebhookPayload"
}
}
},
"description": "Webhook payload for disputeclosed",
"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": "Dispute Closed Webhook",
"tags": [
"Disputes"
]
}
},
"disputecreated": {
"post": {
"deprecated": false,
"description": "Truemed calls your endpoint when a dispute first becomes visible to you \u2014 a new chargeback, or a live inquiry you\ncan respond to in order to pre-empt its escalation. An inquiry that later escalates into a chargeback phase fires\n`dispute.created` again for the chargeback.\n\n**Authentication**: Requests are HMAC-SHA256 signed. The `x-truemed-signature` header carries a timestamp and\nthe signature in the form `t=,v0=`. Compute HMAC-SHA256 over\n`.` with your webhook signing secret and compare the hex digest to `v0`. Sign the raw body\nbytes exactly as received, since re-serializing the JSON changes the bytes and breaks the signature.\n\n## Payload\n\nThe signed body is the standard Truemed envelope:\n\n- `webhook_delivery_id` - Delivery id (`dlv_\u2026`). Retries of the same event repeat the same value; use it to\n deduplicate.\n- `event_type` - The wire event name (`dispute.created`, `dispute.updated`, or `dispute.closed`).\n- `data` - The full canonical dispute, the same shape returned by `GET /api/v1/disputes/{dispute_id}` \u2014 including\n `dispute_id`, `state`, `phase`, `reason`, `amount`, `due_by`, `counters`, and `metadata`. Null fields are\n omitted. Payloads carry canonical Truemed fields and the public `dispute_id` UUID only, never raw processor\n shapes. Always key your records on `dispute_id`.\n\n(Unsigned legacy endpoints receive the `data` object as the flat top-level body, with no envelope and no\n`event_type`.)\n\nThe model is **notify, then fetch**: the snapshot is complete enough to act on directly, and you can re-fetch the\ndispute for authoritative state when a delivery is delayed or retried out of order.\n\n**Inquiries notify too, with one exception.** A live inquiry fires `dispute.created` / `dispute.updated` just like\na chargeback, so you can respond to pre-empt its escalation. If the bank later drops a surfaced inquiry, the terminal\n`closed` state fires `dispute.closed` \u2014 so `dispute.closed` marks any terminal outcome, whether a chargeback result\n(`won` / `lost` / `accepted` / `expired`) or a dropped inquiry (`closed`). The only silent case is an inquiry that\nopens and closes between webhook deliveries \u2014 already terminal the first time Truemed sees it \u2014 which fires no webhook.\n\n## Response Notes\n\nReturn HTTP `204` with an empty body. Truemed retries failed deliveries with backoff for up to 7 days.",
"operationId": "disputeCreatedWebhook",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DisputeWebhookPayload"
}
}
},
"description": "Webhook payload for disputecreated",
"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": "Dispute Created Webhook",
"tags": [
"Disputes"
]
}
},
"disputeupdated": {
"post": {
"deprecated": false,
"description": "Truemed calls your endpoint when an open dispute's `state` or `phase` changes \u2014 for example, after you\nsubmit evidence and it moves to `under_review`. An update that changes neither `state` nor `phase` is\nsilent.\n\n**Authentication**: Requests are HMAC-SHA256 signed. The `x-truemed-signature` header carries a timestamp and\nthe signature in the form `t=,v0=`. Compute HMAC-SHA256 over\n`.` with your webhook signing secret and compare the hex digest to `v0`. Sign the raw body\nbytes exactly as received, since re-serializing the JSON changes the bytes and breaks the signature.\n\n## Payload\n\nThe signed body is the standard Truemed envelope:\n\n- `webhook_delivery_id` - Delivery id (`dlv_\u2026`). Retries of the same event repeat the same value; use it to\n deduplicate.\n- `event_type` - The wire event name (`dispute.created`, `dispute.updated`, or `dispute.closed`).\n- `data` - The full canonical dispute, the same shape returned by `GET /api/v1/disputes/{dispute_id}` \u2014 including\n `dispute_id`, `state`, `phase`, `reason`, `amount`, `due_by`, `counters`, and `metadata`. Null fields are\n omitted. Payloads carry canonical Truemed fields and the public `dispute_id` UUID only, never raw processor\n shapes. Always key your records on `dispute_id`.\n\n(Unsigned legacy endpoints receive the `data` object as the flat top-level body, with no envelope and no\n`event_type`.)\n\nThe model is **notify, then fetch**: the snapshot is complete enough to act on directly, and you can re-fetch the\ndispute for authoritative state when a delivery is delayed or retried out of order.\n\n**Inquiries notify too, with one exception.** A live inquiry fires `dispute.created` / `dispute.updated` just like\na chargeback, so you can respond to pre-empt its escalation. If the bank later drops a surfaced inquiry, the terminal\n`closed` state fires `dispute.closed` \u2014 so `dispute.closed` marks any terminal outcome, whether a chargeback result\n(`won` / `lost` / `accepted` / `expired`) or a dropped inquiry (`closed`). The only silent case is an inquiry that\nopens and closes between webhook deliveries \u2014 already terminal the first time Truemed sees it \u2014 which fires no webhook.\n\n## Response Notes\n\nReturn HTTP `204` with an empty body. Truemed retries failed deliveries with backoff for up to 7 days.",
"operationId": "disputeUpdatedWebhook",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DisputeWebhookPayload"
}
}
},
"description": "Webhook payload for disputeupdated",
"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": "Dispute Updated Webhook",
"tags": [
"Disputes"
]
}
},
"paymentsessioncapturefailed": {
"post": {
"deprecated": false,
"description": "Truemed sends this webhook when a payment session's capture permanently fails after all\nautomatic retries have been exhausted, meaning the order will not be paid unless you take action.\n\nTerminal capture failures are exceedingly rare \u2014 the vast majority of integrations will never\nreceive this event and do not need to build special handling for it. Subscribe only if you want to\nbe notified in the uncommon case that a payment session can never be captured.\n\nThis is distinct from the `payment_session_complete` webhook: a capture failure is terminal, so you\nwill not receive a later `captured` status for the same session. Do not fulfill the order when you\nreceive this event.\n\nIf part of a split payment was collected before the capture failed, `amount_collected` reports the\namount already charged to the customer; it is null when nothing was collected.\n\n**Authentication**: Verify the request comes from Truemed by checking that the API key is present in\nthe `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- `payment_session_id` - the payment session whose capture failed.\n- `failed_at` - when the capture was determined to have permanently failed.\n- `failure_details` - a generic message indicating the capture could not be completed.\n- `amount_collected` - funds already collected on a partially-charged split payment; null otherwise.",
"operationId": "paymentSessionCaptureFailedWebhook",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CaptureFailedResource"
}
}
},
"description": "Webhook payload for paymentsessioncapturefailed",
"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 Capture Failed Webhook",
"tags": [
"Payment Sessions"
]
}
},
"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)\n4. A customer's letter of medical necessity is rejected, on sales channels configured to provision\n a token anyway. The `payment_token` is still provisioned so the outcome can be matched back to\n the `provision_token_request_id`, but it carries no HSA/FSA eligibility: charges against it\n route entirely to the credit/debit card. Ask your Truemed contact to enable this if you would\n rather take the order on the customer's backup card than lose it.\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- `eligibility_status`: where the customer's clinical eligibility stands at the moment the webhook\n is sent\n - Sent on every `payment_token_updated`, including the card-update and requalification ones, so it\n always describes the customer's current standing rather than only the change that prompted the\n webhook.\n - This is a clinical status, not a payment one. `create_payment_session` returns a `status`\n describing the payment; the two are different vocabularies and the names are kept apart on purpose.\n - It answers *whether* the customer is covered. For *which* of your items that covers, and until\n when, use the eligibility read.\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's eligibility status is first determined\n\n**Authentication**: Signed webhooks are HMAC-SHA256 signed. The `x-truemed-signature` header carries a\ntimestamp and the signature in the form `t=,v0=`. Compute HMAC-SHA256 over\n`.` with your webhook signing secret and compare the hex digest to `v0`. Sign the raw\nbody bytes exactly as received, since re-serializing the JSON changes the bytes and breaks the signature.\nUnsigned (legacy) webhooks instead send the API key verbatim in the `x-truemed-api-key` header.\n\n## Request Notes\n\nThe signed body wraps an event envelope inside the delivery envelope, so the catalog item is at\n`data.data.object`:\n\n```json\n{\n \"webhook_delivery_id\": \"dlv_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n \"event_type\": \"product_catalog.item.eligibility_updated\",\n \"data\": {\n \"event_type\": \"product_catalog.item.eligibility_updated\",\n \"timestamp\": \"2026-01-15T12:00:00Z\",\n \"data\": {\n \"object\": {\n \"sku\": \"ITEM-001\",\n \"name\": \"Compression Knee Brace\",\n \"eligibility\": \"eligible_with_lmn\",\n \"reviewed_at\": \"2026-01-15T11:59:58Z\"\n }\n }\n }\n}\n```\n\nFields:\n\n- `webhook_delivery_id` - Delivery id (`dlv_\u2026`). Retries of the same event repeat the same value; use it to\n deduplicate. Signed deliveries only.\n- `event_type` - The event type identifier: `product_catalog.item.eligibility_updated`. Carried on both the\n delivery envelope and the inner event envelope, with the same value.\n- `data.timestamp` - ISO-8601 timestamp of when the event occurred\n- `data.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's eligibility was last decided\n\nUnsigned (legacy) webhooks receive the inner event envelope as the top-level body \u2014 `{event_type,\ntimestamp, data: {object}}` \u2014 with no `webhook_delivery_id`. The item is at `data.object`.\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": {
"AcceptDisputeBadRequestResponse": {
"properties": {
"error": {
"enum": [
"BadRequest",
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"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"
},
"CancelPaymentSessionBadRequestResponse": {
"properties": {
"error": {
"enum": [
"SessionAuthorized",
"SessionCaptured",
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"CaptureFailedResource": {
"properties": {
"amount_collected": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "The amount of funds already collected on the failed capture. Set when part of a split payment succeeded before the capture failed; null otherwise.",
"title": "Amount Collected"
},
"failed_at": {
"description": "When the capture was determined to have permanently failed.",
"format": "date-time",
"title": "Failed At",
"type": "string"
},
"failure_details": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "A generic message indicating the capture could not be completed.",
"title": "Failure Details"
},
"payment_session_id": {
"description": "The payment session whose capture permanently failed.",
"title": "Payment Session Id",
"type": "string"
}
},
"required": [
"payment_session_id",
"failed_at"
],
"title": "CaptureFailedResource",
"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"
},
"CapturePaymentSessionBadRequestResponse": {
"properties": {
"error": {
"enum": [
"ImmediateCapture",
"SessionCaptured",
"SessionExpired",
"SessionPending",
"SessionVoided",
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"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"
},
"id": {
"description": "The stable id of this capture, used to target a refund against it via `capture_id`.",
"title": "Id",
"type": "string"
}
},
"required": [
"id",
"captured_at",
"capture_amount"
],
"title": "CaptureWebhookPayload",
"type": "object"
},
"CatalogItemDetail": {
"properties": {
"comparable_item_price_cents": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "The amount, in cents, deducted from each unit of this item before any of it can reach an HSA/FSA card.",
"title": "Comparable Item Price Cents"
},
"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's eligibility was last decided. Present whenever `eligibility` is.",
"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"
},
"CounterCreateRequest": {
"properties": {
"evidence_items": {
"default": [],
"description": "Initial categorized evidence for the draft.",
"items": {
"$ref": "#/components/schemas/EvidenceItem"
},
"title": "Evidence Items",
"type": "array"
}
},
"title": "CounterCreateRequest",
"type": "object"
},
"CounterResource": {
"properties": {
"counter_id": {
"description": "Stable Truemed counter ID (UUID).",
"title": "Counter Id",
"type": "string"
},
"created_at": {
"description": "When this counter was created.",
"format": "date-time",
"title": "Created At",
"type": "string"
},
"evidence_items": {
"default": [],
"description": "The categorized evidence captured on this counter.",
"items": {
"$ref": "#/components/schemas/EvidenceItem"
},
"title": "Evidence Items",
"type": "array"
},
"phase": {
"$ref": "#/components/schemas/DisputePhase",
"description": "Dispute phase this counter responds to."
},
"revision": {
"description": "Optimistic-lock revision; echo it back on the next draft save to detect conflicts.",
"title": "Revision",
"type": "integer"
},
"state": {
"$ref": "#/components/schemas/CounterState",
"description": "Counter lifecycle state."
},
"submitted_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "When this counter was submitted to the processor.",
"title": "Submitted At"
},
"submitted_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Email of the dashboard user who submitted this counter; null for drafts or API-key submissions.",
"title": "Submitted By"
},
"updated_at": {
"description": "When this counter was last updated.",
"format": "date-time",
"title": "Updated At",
"type": "string"
}
},
"required": [
"counter_id",
"state",
"phase",
"revision",
"created_at",
"updated_at"
],
"title": "CounterResource",
"type": "object"
},
"CounterState": {
"description": "Lifecycle of a dispute-evidence response (a \"counter\").\n\n`draft` autosaves; `submitted` is terminal-for-this-round (one-shot to the processor); `withdrawn` is a\ndiscarded draft; `superseded` is a prior round's submission once a new phase opens. Only `draft` is mutable.",
"enum": [
"draft",
"submitted",
"withdrawn",
"superseded"
],
"title": "CounterState",
"type": "string"
},
"CounterUpsertRequest": {
"properties": {
"evidence_items": {
"default": [],
"description": "Full replacement of the draft's categorized evidence.",
"items": {
"$ref": "#/components/schemas/EvidenceItem"
},
"title": "Evidence Items",
"type": "array"
},
"revision": {
"description": "The revision you last read; the save is rejected (409) if the counter changed since.",
"title": "Revision",
"type": "integer"
}
},
"required": [
"revision"
],
"title": "CounterUpsertRequest",
"type": "object"
},
"CreateDisputeCounterBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"CreateFileBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"CreateItemBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"CreateItemConflictResponse": {
"properties": {
"error": {
"enum": [
"Conflict"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"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"
},
"CreatePaymentSessionBadRequestResponse": {
"properties": {
"error": {
"enum": [
"FeatureNotEnabled",
"IdempotencyViolation",
"InvalidRequestParameter",
"MissingRequiredParameter",
"OrderItemsInvalid",
"SessionPending",
"TokenizeNotSupported",
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"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"
},
"request_multicapture": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": false,
"description": "Opts this authorization into multiple partial captures. Requires multi-capture to be enabled on your sales channel, and cannot be combined with `tokenize` or `payment_token` \u2014 otherwise the request fails with `FeatureNotEnabled`. Requesting it does not guarantee it: the card network decides, so a later capture with `final: false` can still be rejected. Only meaningful with `kind=authorization`. See [Manual and delayed capture](/guides/setup/api/payment-sessions/manual-delayed-capture#capturing-in-multiple-parts).",
"title": "Request Multicapture"
},
"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"
},
"lmn_expires_at": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"description": "When the Letter of Medical Necessity covering this customer expires (inclusive, UTC). Null for sessions that are not tokenized, and for a customer who holds no letter on this sales channel. While a letter is live this is the earliest expiration among them; once none is, it is when the last one lapsed. This is the same value the customer-eligibility endpoints return, so renewal can be driven off whichever call you already make.",
"title": "Lmn Expires At"
},
"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"
},
"CreatePaymentTokenBadRequestResponse": {
"properties": {
"error": {
"enum": [
"FeatureNotEnabled",
"IdempotencyViolation",
"InvalidRequestParameter",
"TotalAmountInvalid",
"ValidationError",
"WaitingForVerification"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"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 sends the customer when they opt out of HSA/FSA, do not qualify in the survey, or cancel a payment method update. In an iframe, Truemed returns this URL in the completion message instead of navigating.",
"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": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/PaymentTokenOrderItemSku"
},
"minItems": 1,
"type": "array"
},
{
"type": "null"
}
],
"description": "The initial list of items for this subscription. Required unless this sales channel is configured for full-catalog qualification, in which case it may be omitted.",
"title": "Order Items"
},
"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 render the survey and card entry inline on your own page instead of redirecting the customer. The returned redirect_url becomes an iframe src, and the result arrives as a postMessage rather than a redirect. See the Embedded checkout (iFrame) guide.",
"title": "Use Iframe",
"type": "boolean"
}
},
"required": [
"idempotency_key",
"success_url",
"failure_url",
"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"
},
"CreateQualificationSessionBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"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": "Where Truemed sends the customer when they opt out of HSA/FSA or do not qualify in the survey. In an iframe, Truemed returns this URL in the completion message instead of navigating.",
"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 (inclusive, UTC).",
"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"
},
"CreateRefundBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"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"
},
"capture_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The ID of the capture to refund, from `capture_id` in the capture response or `captures[].id` in the payment session status. Each refund applies to exactly one capture. Required when the session has more than one capture or is still `partially_captured`, and optional when a closed session has only one capture.",
"title": "Capture Id"
},
"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": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/RefundItemDetails"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "The items to refund. Truemed pro-rates `amount` by the eligible ratio of these lines to determine the refund's eligible amount. Eligible spending that the regular card paid returns there first. The remaining eligible amount returns to the HSA/FSA card, and the rest returns to the regular card. If the regular card cannot cover its share, the shortfall returns to the HSA/FSA card within its refundable balance. Omit this field, or send an empty list, and Truemed uses eligible-first allocation based on the remaining eligible amount and each card's refundable balance. That refund applies to the order rather than to any line, so each line's `total_refundable` and `quantity_refundable` stay unchanged. If the items sum below `amount`, Truemed applies the remainder to the capture the refund targets.",
"title": "Item Details"
},
"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.\n\nOne of:\n- `customer_request` \u2014 The refund was requested by the customer.\n- `duplicate_payment` \u2014 The charge was a duplicate.\n- `fraudulent` \u2014 The charge was fraudulent; this feeds the fraud signal."
}
},
"required": [
"payment_id",
"amount",
"idempotency_key",
"reason"
],
"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"
},
"DeletePaymentTokenBadRequestResponse": {
"properties": {
"error": {
"enum": [
"FeatureNotEnabled",
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"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"
},
"DisputeDetailResource": {
"properties": {
"amount": {
"description": "The original disputed amount in cents, independent of resolution.",
"title": "Amount",
"type": "integer"
},
"counters": {
"default": [],
"description": "Evidence counters for this dispute (the full chain across phases).",
"items": {
"$ref": "#/components/schemas/CounterResource"
},
"title": "Counters",
"type": "array"
},
"created_at": {
"description": "When the dispute was created.",
"format": "date-time",
"title": "Created At",
"type": "string"
},
"currency": {
"description": "ISO currency code of the disputed amount.",
"title": "Currency",
"type": "string"
},
"dispute_id": {
"description": "Stable Truemed dispute ID (UUID). Use this as the dispute's identifier.",
"title": "Dispute Id",
"type": "string"
},
"due_by": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "Evidence submission deadline, if the dispute is challengeable.",
"title": "Due By"
},
"evidence_requirements": {
"$ref": "#/components/schemas/DisputeEvidenceRequirements",
"default": {
"compelling": [],
"merchant_explanation": "",
"other": [],
"supporting": []
},
"description": "Recommended evidence for this dispute's reason, grouped by weight (compelling / supporting / other), plus Truemed's merchant narrative on how to contest."
},
"metadata": {
"additionalProperties": true,
"default": {},
"description": "Arbitrary merchant-set metadata.",
"title": "Metadata",
"type": "object"
},
"network_reason_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Raw card-network reason code behind the dispute (e.g. Visa `10.4`), if provided.",
"title": "Network Reason Code"
},
"outcome": {
"anyOf": [
{
"$ref": "#/components/schemas/DisputeOutcome"
},
{
"type": "null"
}
],
"description": "Terminal outcome; null until the dispute resolves."
},
"payment": {
"$ref": "#/components/schemas/PaymentSummaryResource",
"description": "Summary of the payment the dispute was filed against."
},
"payment_session_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The Truemed payment session this dispute belongs to. Null for disputes on non-payment-session charges.",
"title": "Payment Session Id"
},
"phase": {
"anyOf": [
{
"$ref": "#/components/schemas/DisputePhase"
},
{
"type": "null"
}
],
"description": "Which round of the dispute (inquiry, dispute, pre-arbitration, arbitration)."
},
"prior_dispute_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Truemed dispute ID (UUID) of the prior round in a pre-arbitration/re-filing chain, if any.",
"title": "Prior Dispute Id"
},
"processor": {
"$ref": "#/components/schemas/IntegrationPlatform",
"description": "Payment processor the dispute originated from."
},
"processor_dispute_id": {
"description": "Raw payment-processor dispute ID (e.g. Stripe `du_\u2026`), for reconciliation.",
"title": "Processor Dispute Id",
"type": "string"
},
"reason": {
"$ref": "#/components/schemas/DisputeReason",
"description": "Canonical reason the dispute was filed."
},
"resolved_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "When the dispute reached a terminal state.",
"title": "Resolved At"
},
"state": {
"$ref": "#/components/schemas/DisputeState",
"description": "Canonical dispute state."
}
},
"required": [
"dispute_id",
"processor_dispute_id",
"processor",
"state",
"reason",
"amount",
"currency",
"created_at",
"payment"
],
"title": "DisputeDetailResource",
"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"
},
"phase": {
"anyOf": [
{
"$ref": "#/components/schemas/DisputePhase"
},
{
"type": "null"
}
],
"description": "Which round of the dispute (inquiry, dispute, pre-arbitration, arbitration)."
},
"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"
},
"state": {
"$ref": "#/components/schemas/DisputeState",
"description": "Canonical dispute state. Finer-grained than `status`: distinguishes `inquiry` and `needs_response` (both surfaced as `Investigating` in `status`)."
},
"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",
"state",
"reason",
"disputed_on",
"description"
],
"title": "DisputeDetails",
"type": "object"
},
"DisputeEvidenceCategorySpec": {
"properties": {
"category": {
"$ref": "#/components/schemas/EvidenceCategory",
"description": "Canonical evidence category."
},
"description": {
"description": "Merchant-facing helper text explaining what to provide; empty when the category has none.",
"title": "Description",
"type": "string"
},
"file": {
"description": "Whether the category accepts a file upload.",
"title": "File",
"type": "boolean"
},
"label": {
"description": "Merchant-facing display label for the category.",
"title": "Label",
"type": "string"
},
"text": {
"description": "Whether the category accepts free text.",
"title": "Text",
"type": "boolean"
}
},
"required": [
"category",
"label",
"description",
"text",
"file"
],
"title": "DisputeEvidenceCategorySpec",
"type": "object"
},
"DisputeEvidenceRequirements": {
"properties": {
"compelling": {
"default": [],
"description": "Evidence most likely to overturn the dispute, in display order.",
"items": {
"$ref": "#/components/schemas/DisputeEvidenceCategorySpec"
},
"title": "Compelling",
"type": "array"
},
"merchant_explanation": {
"default": "",
"description": "Truemed's reason-specific narrative (Markdown) on how to contest this dispute. Empty when the reason has no configured guidance.",
"title": "Merchant Explanation",
"type": "string"
},
"other": {
"default": [],
"description": "Every remaining category the processor accepts, so nothing is unreachable in the form.",
"items": {
"$ref": "#/components/schemas/DisputeEvidenceCategorySpec"
},
"title": "Other",
"type": "array"
},
"supporting": {
"default": [],
"description": "Additional recommended evidence (supporting and context tiers), in display order.",
"items": {
"$ref": "#/components/schemas/DisputeEvidenceCategorySpec"
},
"title": "Supporting",
"type": "array"
}
},
"title": "DisputeEvidenceRequirements",
"type": "object"
},
"DisputeListResponse": {
"properties": {
"disputes": {
"description": "The page of disputes for the authenticated sales channel.",
"items": {
"$ref": "#/components/schemas/DisputeResource"
},
"title": "Disputes",
"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": [
"disputes"
],
"title": "DisputeListResponse",
"type": "object"
},
"DisputeMetadataRequest": {
"properties": {
"metadata": {
"additionalProperties": true,
"description": "Replaces the dispute's metadata. Only metadata is mutable; state/amounts/deadlines are read-only.",
"title": "Metadata",
"type": "object"
}
},
"required": [
"metadata"
],
"title": "DisputeMetadataRequest",
"type": "object"
},
"DisputeOutcome": {
"description": "Denormalized terminal outcome of a dispute; null until terminal.",
"enum": [
"won",
"lost",
"accepted",
"expired",
"closed"
],
"title": "DisputeOutcome",
"type": "string"
},
"DisputePhase": {
"description": "Which round of a dispute this is \u2014 orthogonal to `DisputeState` (comparison doc \u00a74.3/\u00a75).",
"enum": [
"inquiry",
"dispute",
"pre_arbitration",
"arbitration"
],
"title": "DisputePhase",
"type": "string"
},
"DisputeReason": {
"description": "Canonical, card-network dispute reason \u2014 the only reasons Truemed can receive, since it settles\nHSA/FSA card payments over Stripe and never ACH/bank-debit. The enum is the processor-independent\ncontract: each processor adapter maps its native reason vocabulary into this set (Adyen's raw\ncard-scheme reason codes collapse into these buckets), so the enum itself carries no processor specifics.\n\nHuman labels live in `_DISPUTE_REASON_LABELS`, exposed via `.label` \u2014 the single backend contract the\nfrontend and merchant emails hydrate from instead of maintaining their own label maps.",
"enum": [
"credit_not_processed",
"duplicate",
"fraudulent",
"general",
"noncompliant",
"product_not_received",
"product_unacceptable",
"subscription_canceled",
"unrecognized"
],
"title": "DisputeReason",
"type": "string"
},
"DisputeResource": {
"properties": {
"amount": {
"description": "The original disputed amount in cents, independent of resolution.",
"title": "Amount",
"type": "integer"
},
"counters": {
"default": [],
"description": "Evidence counters for this dispute (the full chain across phases).",
"items": {
"$ref": "#/components/schemas/CounterResource"
},
"title": "Counters",
"type": "array"
},
"created_at": {
"description": "When the dispute was created.",
"format": "date-time",
"title": "Created At",
"type": "string"
},
"currency": {
"description": "ISO currency code of the disputed amount.",
"title": "Currency",
"type": "string"
},
"dispute_id": {
"description": "Stable Truemed dispute ID (UUID). Use this as the dispute's identifier.",
"title": "Dispute Id",
"type": "string"
},
"due_by": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "Evidence submission deadline, if the dispute is challengeable.",
"title": "Due By"
},
"metadata": {
"additionalProperties": true,
"default": {},
"description": "Arbitrary merchant-set metadata.",
"title": "Metadata",
"type": "object"
},
"network_reason_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Raw card-network reason code behind the dispute (e.g. Visa `10.4`), if provided.",
"title": "Network Reason Code"
},
"outcome": {
"anyOf": [
{
"$ref": "#/components/schemas/DisputeOutcome"
},
{
"type": "null"
}
],
"description": "Terminal outcome; null until the dispute resolves."
},
"payment_session_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The Truemed payment session this dispute belongs to. Null for disputes on non-payment-session charges.",
"title": "Payment Session Id"
},
"phase": {
"anyOf": [
{
"$ref": "#/components/schemas/DisputePhase"
},
{
"type": "null"
}
],
"description": "Which round of the dispute (inquiry, dispute, pre-arbitration, arbitration)."
},
"prior_dispute_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Truemed dispute ID (UUID) of the prior round in a pre-arbitration/re-filing chain, if any.",
"title": "Prior Dispute Id"
},
"processor": {
"$ref": "#/components/schemas/IntegrationPlatform",
"description": "Payment processor the dispute originated from."
},
"processor_dispute_id": {
"description": "Raw payment-processor dispute ID (e.g. Stripe `du_\u2026`), for reconciliation.",
"title": "Processor Dispute Id",
"type": "string"
},
"reason": {
"$ref": "#/components/schemas/DisputeReason",
"description": "Canonical reason the dispute was filed."
},
"resolved_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "When the dispute reached a terminal state.",
"title": "Resolved At"
},
"state": {
"$ref": "#/components/schemas/DisputeState",
"description": "Canonical dispute state."
}
},
"required": [
"dispute_id",
"processor_dispute_id",
"processor",
"state",
"reason",
"amount",
"currency",
"created_at"
],
"title": "DisputeResource",
"type": "object"
},
"DisputeState": {
"description": "Canonical, processor-agnostic dispute state \u2014 the 8-state model in the Processor Disputes\nComparison doc \u00a74.3. Distinct from the Stripe-shaped `DisputeStatus`: a processor adapter maps\nraw status/eventCodes \u2192 (DisputeState, DisputePhase). `closed` is the favorable no-contest\ninquiry outcome (excluded from win-rate), kept separate from `won`.",
"enum": [
"inquiry",
"needs_response",
"under_review",
"won",
"lost",
"accepted",
"expired",
"closed"
],
"title": "DisputeState",
"type": "string"
},
"DisputeStatusPublic": {
"description": "The public facing status for the dispute.",
"enum": [
"Lost",
"Won",
"Closed",
"Investigating",
"Under Review",
"Unknown"
],
"title": "DisputeStatusPublic",
"type": "string"
},
"DisputeWebhookPayload": {
"properties": {
"data": {
"$ref": "#/components/schemas/DisputeDetailResource",
"description": "The full canonical dispute \u2014 the same shape returned by `GET /api/v1/disputes/{dispute_id}`."
},
"event_type": {
"description": "The event type: `dispute.created`, `dispute.updated`, or `dispute.closed`.",
"title": "Event Type",
"type": "string"
},
"webhook_delivery_id": {
"description": "Deterministic idempotency key for this delivery (`dlv_\u2026`); stable across retries.",
"title": "Webhook Delivery Id",
"type": "string"
}
},
"required": [
"webhook_delivery_id",
"event_type",
"data"
],
"title": "DisputeWebhookPayload",
"type": "object"
},
"EligibilityResponse": {
"properties": {
"eligibility_status": {
"anyOf": [
{
"$ref": "#/components/schemas/EligibilityStatus"
},
{
"type": "null"
}
],
"description": "Where this customer's clinical eligibility stands. Named apart from the payment `status` on other Truemed payloads, which is a different vocabulary. Per-value meanings are listed on the enum. Null for catalog eligibility, which identifies no customer.\n\nOne of:\n- `approved` \u2014 A verified, unexpired letter stands for this customer.\n- `pending` \u2014 A survey is with a clinician; the outcome is not decided yet.\n- `expired` \u2014 The letter that covered this customer has lapsed and not been renewed.\n- `rejected` \u2014 A clinician reviewed this customer's most recent survey and declined it.\n- `never_requested` \u2014 No letter has ever been requested for this customer here."
},
"items": {
"description": "The catalog items that can be charged to an HSA/FSA card, each identified exactly as it is in order_items when you charge.",
"items": {
"type": "string"
},
"title": "Items",
"type": "array"
},
"lmn_expires_at": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"description": "When the letter determining this customer's coverage expires (inclusive, UTC). Null for catalog eligibility, which identifies no customer.",
"title": "Lmn Expires At"
}
},
"required": [
"items"
],
"title": "EligibilityResponse",
"type": "object"
},
"EligibilityStatus": {
"description": "Where a customer's clinical eligibility stands. A statement of fact, never an instruction.",
"enum": [
"approved",
"pending",
"expired",
"rejected",
"never_requested"
],
"title": "EligibilityStatus",
"type": "string",
"x-fern-enum": {
"approved": {
"description": "A verified, unexpired letter stands for this customer."
},
"pending": {
"description": "A survey is with a clinician; the outcome is not decided yet."
},
"expired": {
"description": "The letter that covered this customer has lapsed and not been renewed."
},
"rejected": {
"description": "A clinician reviewed this customer's most recent survey and declined it."
},
"never_requested": {
"description": "No letter has ever been requested for this customer here."
}
}
},
"EvidenceCategory": {
"description": "Canonical evidence categories (comparison doc \u00a74.3). The vocabulary is Stripe-derived (the values match\nStripe's evidence field names today), but each processor adapter maps these to its native evidence fields, so\nthe API/dashboard speak these categories rather than any one processor's schema.\n\nHuman labels live in `_EVIDENCE_CATEGORY_LABELS`, exposed via `.label` \u2014 the backend contract the frontend\nand merchant emails hydrate from instead of hardcoding their own label maps.",
"enum": [
"product_description",
"customer_communication",
"customer_name",
"customer_email",
"customer_purchase_ip",
"customer_signature",
"billing_address",
"receipt",
"shipping_documentation",
"shipping_tracking_number",
"service_documentation",
"service_date",
"access_activity_log",
"refund_policy",
"refund_policy_disclosure",
"refund_refusal_explanation",
"cancellation_policy",
"cancellation_policy_disclosure",
"cancellation_rebuttal",
"duplicate_charge_documentation",
"duplicate_charge_explanation",
"uncategorized"
],
"title": "EvidenceCategory",
"type": "string"
},
"EvidenceItem": {
"properties": {
"category": {
"$ref": "#/components/schemas/EvidenceCategory",
"description": "Canonical evidence category; the adapter maps it to the processor's evidence fields."
},
"file_ids": {
"default": [],
"description": "File IDs (from the Files API) attached for this category; must be owned by you.",
"items": {
"type": "string"
},
"title": "File Ids",
"type": "array"
},
"text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Free-text evidence for this category.",
"title": "Text"
}
},
"required": [
"category"
],
"title": "EvidenceItem",
"type": "object"
},
"FileCreateRequest": {
"properties": {
"content_type": {
"description": "The file's MIME type, e.g. application/pdf. Must be allowed for the given purpose.",
"examples": [
"application/pdf"
],
"title": "Content Type",
"type": "string"
},
"filename": {
"description": "The original filename, e.g. receipt.pdf.",
"examples": [
"receipt.pdf"
],
"maxLength": 255,
"title": "Filename",
"type": "string"
},
"purpose": {
"$ref": "#/components/schemas/FilePurpose",
"description": "The business domain the file is for (e.g. dispute_evidence)."
},
"size_bytes": {
"description": "The file size in bytes. Must be within the per-purpose maximum.",
"examples": [
248193
],
"title": "Size Bytes",
"type": "integer"
}
},
"required": [
"filename",
"content_type",
"size_bytes",
"purpose"
],
"title": "FileCreateRequest",
"type": "object"
},
"FileCreateResponse": {
"properties": {
"expires_at": {
"description": "When the presigned upload URL expires (10 minutes after creation).",
"examples": [
"2026-07-23T19:40:00Z"
],
"format": "date-time",
"title": "Expires At",
"type": "string"
},
"file_id": {
"description": "The public file identifier. Reference this id from other resources.",
"examples": [
"01920a7e-9c3f-7b21-8e4a-2f6b1d0c5a9e"
],
"title": "File Id",
"type": "string"
},
"upload_fields": {
"additionalProperties": {
"type": "string"
},
"description": "Form fields to include in the multipart upload POST, before the file part.",
"examples": [
{
"Content-Type": "application/pdf",
"key": "dev/dispute_evidence/9c1f2e3a-4b5c-6d7e-8f90-1a2b3c4d5e6f/2026-07-23/01920a7e-9c3f-7b21-8e4a-2f6b1d0c5a9e_receipt.pdf",
"policy": "eyJleHBpcmF0aW9uIjoiMjAyNi0wNy0yM1QxOTo0MDowMFoifQ==",
"x-amz-algorithm": "AWS4-HMAC-SHA256",
"x-amz-credential": "AKIAIOSFODNN7EXAMPLE/20260723/us-east-1/s3/aws4_request",
"x-amz-date": "20260723T193000Z",
"x-amz-signature": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b"
}
],
"title": "Upload Fields",
"type": "object"
},
"upload_url": {
"description": "Presigned URL to POST the file to (multipart/form-data).",
"examples": [
"https://dev-dispute-evidence.s3.amazonaws.com/"
],
"title": "Upload Url",
"type": "string"
}
},
"required": [
"file_id",
"upload_url",
"upload_fields",
"expires_at"
],
"title": "FileCreateResponse",
"type": "object"
},
"FileDetailResponse": {
"properties": {
"content_type": {
"description": "The file's MIME type, e.g. application/pdf.",
"examples": [
"application/pdf"
],
"title": "Content Type",
"type": "string"
},
"download_url": {
"description": "Short-lived presigned download URL (5 minutes). Always present in a 200 response; non-clean files return 409 rather than a 200 with this field absent.",
"examples": [
"https://dev-dispute-evidence.s3.amazonaws.com/dev/dispute_evidence/9c1f2e3a-4b5c-6d7e-8f90-1a2b3c4d5e6f/2026-07-23/01920a7e-9c3f-7b21-8e4a-2f6b1d0c5a9e_receipt.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20260723%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260723T193000Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b"
],
"title": "Download Url",
"type": "string"
},
"file_id": {
"description": "The public file identifier.",
"examples": [
"01920a7e-9c3f-7b21-8e4a-2f6b1d0c5a9e"
],
"title": "File Id",
"type": "string"
},
"filename": {
"description": "The stored filename.",
"examples": [
"receipt.pdf"
],
"title": "Filename",
"type": "string"
},
"scan_status": {
"$ref": "#/components/schemas/FileScanStatus",
"description": "Malware-scan status. Downloads are only available once the file is clean.",
"examples": [
"clean"
]
},
"size_bytes": {
"description": "The file size in bytes.",
"examples": [
248193
],
"title": "Size Bytes",
"type": "integer"
}
},
"required": [
"file_id",
"filename",
"size_bytes",
"content_type",
"scan_status",
"download_url"
],
"title": "FileDetailResponse",
"type": "object"
},
"FileListResponse": {
"properties": {
"files": {
"description": "Files owned by the authenticated sales channel matching the filters.",
"items": {
"$ref": "#/components/schemas/FileSummary"
},
"title": "Files",
"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": [
"files"
],
"title": "FileListResponse",
"type": "object"
},
"FilePurpose": {
"description": "Business domain a file belongs to. Extensible \u2014 each value maps to one ``*FileManager``.",
"enum": [
"dispute_evidence"
],
"title": "FilePurpose",
"type": "string"
},
"FileScanStatus": {
"description": "Malware-scan gate. Evidence attach + download only accept ``Clean`` files.",
"enum": [
"pending_scan",
"clean",
"quarantined"
],
"title": "FileScanStatus",
"type": "string"
},
"FileSummary": {
"properties": {
"content_type": {
"description": "The file's MIME type, e.g. application/pdf.",
"examples": [
"application/pdf"
],
"title": "Content Type",
"type": "string"
},
"file_id": {
"description": "The public file identifier.",
"examples": [
"01920a7e-9c3f-7b21-8e4a-2f6b1d0c5a9e"
],
"title": "File Id",
"type": "string"
},
"filename": {
"description": "The stored filename.",
"examples": [
"receipt.pdf"
],
"title": "Filename",
"type": "string"
},
"scan_status": {
"$ref": "#/components/schemas/FileScanStatus",
"description": "Malware-scan status. Downloads are only available once the file is clean.",
"examples": [
"clean"
]
},
"size_bytes": {
"description": "The file size in bytes.",
"examples": [
248193
],
"title": "Size Bytes",
"type": "integer"
}
},
"required": [
"file_id",
"filename",
"size_bytes",
"content_type",
"scan_status"
],
"title": "FileSummary",
"type": "object"
},
"GetItemDetailBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"IntegrationPlatform": {
"description": "Payment platforms supported by the public dispute API.",
"enum": [
"STRIPE",
"FAKE",
"EXTERNAL"
],
"title": "IntegrationPlatform",
"type": "string"
},
"ListCatalogItemsBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"ListDisputeBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"ListFileBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"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"
},
"ListPaymentSessionBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"ListPaymentTokenBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"ListPayoutReconciliationBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"ListQualificationSessionBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"ListTransactionReconciliationBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"MethodNotAllowedResponse": {
"properties": {
"error": {
"enum": [
"MethodNotAllowed"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"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"
},
"NotFoundResponse": {
"properties": {
"error": {
"enum": [
"NotFound"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"NotImplementedResponse": {
"properties": {
"error": {
"enum": [
"NotImplemented"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"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 applied to this response.",
"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"
},
"PaymentSessionCaptureDetails": {
"properties": {
"amount_refundable": {
"description": "The amount in cents still refundable against this capture \u2014 the captured amount net of prior refunds and any dispute-locked funds. Use this as the ceiling for a refund targeting this capture.",
"title": "Amount Refundable",
"type": "integer"
},
"capture_amount": {
"description": "The amount captured in cents for this capture.",
"title": "Capture Amount",
"type": "integer"
},
"captured_at": {
"description": "ISO-8601 timestamp of when this capture completed.",
"title": "Captured At",
"type": "string"
},
"id": {
"description": "The stable id of this capture; pass it as `capture_id` to refund against it.",
"title": "Id",
"type": "string"
},
"item_details": {
"description": "The per-item breakdown of this capture (empty for amount-only captures).",
"items": {
"$ref": "#/components/schemas/CaptureItemDetails"
},
"title": "Item Details",
"type": "array"
}
},
"required": [
"id",
"capture_amount",
"amount_refundable",
"captured_at",
"item_details"
],
"title": "PaymentSessionCaptureDetails",
"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 \u2014 this requires that the session was created with `request_multicapture: true` and that the card network granted multi-capture on the authorization, and otherwise fails with `ValidationError`. A final capture releases any uncaptured remainder of the authorization. To release the remainder without capturing more, send a final capture with `total_amount: 0` (allowed after at least one earlier capture) or void the session.",
"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": {
"capture_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The ID of this capture. Pass it as `capture_id` to the refund endpoint to refund against this capture. The same ID is returned if the endpoint is called again with the same idempotency_key. Omitted for a zero-amount final capture, which only releases the uncaptured remainder and cannot be refunded.",
"title": "Capture Id"
},
"id": {
"description": "The ID of the payment session that was captured, the same value returned by create_payment_session. Use `capture_id` to identify this capture.",
"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"
},
"capture_failed_amount_collected": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "The amount of funds already collected on a capture that permanently failed. Set when part of a split payment succeeded before the capture failed; null otherwise.",
"title": "Capture Failed Amount Collected"
},
"capture_failed_details": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "A generic message indicating the capture could not be completed. Null when capture_failed_on is null.",
"title": "Capture Failed Details"
},
"capture_failed_on": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "The UTC time at which capturing the authorized funds permanently failed. Null unless the capture will not be retried.",
"title": "Capture Failed On"
},
"captures": {
"description": "The completed captures for this payment session, each addressable by `id` when issuing a refund (`capture_id`). Empty until the session has at least one completed capture.",
"items": {
"$ref": "#/components/schemas/PaymentSessionCaptureDetails"
},
"title": "Captures",
"type": "array"
},
"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",
"captures",
"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. Truemed tracks this per item, so an order-level charge or discount appears in none of them: when the session carried a top-level `amount_details`, the sum of `total_refundable` across items falls below the session's refundable amount.",
"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"
},
"PaymentSummaryResource": {
"properties": {
"order_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ID (UUID) of the Truemed payment session or order the disputed payment belongs to. For a payment session it matches `payment_session_id`. Null when the payment has no linked record.",
"title": "Order Id"
}
},
"title": "PaymentSummaryResource",
"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": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 8601 formatted date when this payment token's HSA/FSA coverage ends (inclusive, UTC). Counts letters earned on the token's own sessions and letters its customer earned on this sales channel, matching the date the Payment Token Updated webhook reports for the same token. Null if the customer holds no verified LMN. Prompt the customer to requalify 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": {
"eligibility_status": {
"anyOf": [
{
"$ref": "#/components/schemas/EligibilityStatus"
},
{
"type": "null"
}
],
"description": "Where this customer's clinical eligibility stands at the moment this webhook is sent. Named apart from `status` on a payment session, which is that payment's status rather than the customer's. For which items that covers, and until when, use the eligibility read.\n\nOne of:\n- `approved` \u2014 A verified, unexpired letter stands for this customer.\n- `pending` \u2014 A survey is with a clinician; the outcome is not decided yet.\n- `expired` \u2014 The letter that covered this customer has lapsed and not been renewed.\n- `rejected` \u2014 A clinician reviewed this customer's most recent survey and declined it.\n- `never_requested` \u2014 No letter has ever been requested for this customer here."
},
"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": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional ISO 8601 formatted date when the LMN expires (inclusive, UTC).",
"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"
},
"ProductCatalogItemEligibilityUpdatedEventEnvelope": {
"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": "ProductCatalogItemEligibilityUpdatedEventEnvelope",
"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/ProductCatalogItemEligibilityUpdatedEventEnvelope",
"description": "The event envelope, carrying `event_type` and `timestamp`. The catalog item itself is at `data.data.object`."
},
"event_type": {
"description": "The event type: `product_catalog.item.eligibility_updated`.",
"title": "Event Type",
"type": "string"
},
"webhook_delivery_id": {
"description": "Deterministic idempotency key for this delivery (`dlv_\u2026`); stable across retries.",
"title": "Webhook Delivery Id",
"type": "string"
}
},
"required": [
"webhook_delivery_id",
"event_type",
"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 (inclusive, UTC).",
"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": "Qualification status summary for the **v1** qualification-session surface.\n\nIts wire values are the long-standing v1 contract (`pending`/`processing`/`approved`/`rejected`);\nthe v2 Truemed Session surface uses ``TruemedSessionQualificationStatus`` with its own vocabulary,\nso the two evolve independently and v1 clients keep the values they already depend on.\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 (inclusive, UTC).",
"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 number of units of this item being refunded, up to `quantity_refundable` from payment session status or list payment sessions. Use 0 to refund dollars without units, for example the rest of a line after an earlier partial refund already returned its units.",
"title": "Quantity",
"type": "integer"
},
"total": {
"description": "The amount in cents being refunded for this item, up to `total_refundable` from payment session status or list payment sessions. Across all items these totals must not sum above the refund's `amount`. They may sum below it, and Truemed applies the remainder to the capture the refund targets.",
"title": "Total",
"type": "integer"
}
},
"required": [
"item_id",
"quantity",
"total"
],
"title": "RefundItemDetails",
"type": "object"
},
"RefundReasons": {
"description": "Why a refund was issued. The vocabulary maps to the card networks' standard refund reasons.",
"enum": [
"customer_request",
"duplicate_payment",
"fraudulent"
],
"title": "RefundReasons",
"type": "string",
"x-fern-enum": {
"customer_request": {
"description": "The refund was requested by the customer."
},
"duplicate_payment": {
"description": "The charge was a duplicate."
},
"fraudulent": {
"description": "The charge was fraudulent; this feeds the fraud signal."
}
}
},
"RetrieveCatalogEligibilityBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"RetrieveDisputeBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"RetrieveFileBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"RetrievePaymentSessionBadRequestResponse": {
"properties": {
"error": {
"enum": [
"MissingField",
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"RetrievePaymentSessionNotFoundResponse": {
"properties": {
"error": {
"enum": [
"InvalidPaymentId",
"NotFound"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"RetrievePaymentTokenBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"RetrievePaymentTokenNotFoundResponse": {
"properties": {
"error": {
"enum": [
"InvalidToken",
"NotFound"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"RetrievePaymentTokenProvisionRequestBadRequestResponse": {
"properties": {
"error": {
"enum": [
"FeatureNotEnabled",
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"RetrieveProvisionRequestEligibilityBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"RetrieveQualificationSessionBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"RetrieveTokenEligibilityBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"ServerErrorResponse": {
"properties": {
"error": {
"enum": [
"ServerError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"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"
},
"SubmitDisputeCounterBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"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"
},
"TruemedCheckoutMethodBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"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"
},
"UpdateDisputeCounterBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"UpdateDisputeMetadataBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"UpdateItemBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"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"
},
"UpdatePaymentTokenBadRequestResponse": {
"properties": {
"error": {
"enum": [
"FeatureNotEnabled",
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"UpdatePaymentTokenNotFoundResponse": {
"properties": {
"error": {
"enum": [
"InvalidToken",
"NotFound"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"UpdatePaymentTokenRequest": {
"properties": {
"failure_url": {
"description": "Where Truemed sends the customer when they opt out of HSA/FSA, do not qualify in the survey, or cancel a payment method update. In an iframe, Truemed returns this URL in the completion message instead of navigating.",
"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. Required when `renew_eligibility` is true, or when neither `update_card_info` nor `metadata` is set, unless this sales channel is configured for full-catalog qualification. A full-catalog channel needs at least one of `update_card_info`, `metadata`, `order_items` or `renew_eligibility`. On a full-catalog channel, eligibility is checked against the whole catalog only when `renew_eligibility` is true, and these items do not narrow it.",
"title": "Order Items"
},
"renew_eligibility": {
"default": false,
"description": "Set to true to ask the customer to requalify. The response is `TakeHealthSurvey` when the customer's LMN is missing, rejected, expired, or expires within 30 days, and `None` otherwise. When the token has no backup card and an item needs one, the response is `UpdatePaymentMethod` instead. The items are `order_items`, or the whole catalog on a full-catalog channel. Use lmn_expires_at from Retrieve or List Payment Token responses or the Payment Token Updated Webhook payload to identify upcoming expirations. On a full-catalog channel, this is the only update that can return a survey.",
"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"
},
"UpdateQualificationSessionBadRequestResponse": {
"properties": {
"error": {
"enum": [
"BadRequest",
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"UpdateQualificationSessionRequest": {
"properties": {
"failure_url": {
"anyOf": [
{
"maxLength": 2048,
"type": "string"
},
{
"type": "null"
}
],
"description": "Where Truemed sends the customer when they opt out of HSA/FSA or do not qualify in the survey. If omitted, the current failure URL is unchanged. In an iframe, Truemed returns this URL in the completion message instead of navigating. 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"
},
"VoidPaymentSessionBadRequestResponse": {
"properties": {
"error": {
"enum": [
"ImmediateCapture",
"SessionCaptured",
"SessionNotAuthorized",
"SessionVoided",
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"type": "object"
},
"WithdrawDisputeCounterBadRequestResponse": {
"properties": {
"error": {
"enum": [
"TotalAmountInvalid",
"ValidationError"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"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"
}
}
}
}