{ "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.2.0" }, "servers": [ { "description": "Development server", "url": "https://dev-api.truemed.com" }, { "description": "Production server", "url": "https://api.truemed.com" } ], "tags": [ { "description": "APIs for creating and managing payment sessions, including authorization, capture, void, and cancellation operations", "name": "Payment Sessions" }, { "description": "APIs for creating and managing payment tokens for stored payment methods and subscription billing", "name": "Payment Tokens" }, { "description": "APIs for creating and managing qualification sessions to determine HSA/FSA eligibility", "name": "Qualification Sessions" }, { "description": "APIs for creating and managing catalog items", "name": "Product Catalog" } ], "paths": { "/payments/v1/create_payment_session": { "post": { "deprecated": false, "description": "Create a payment session to begin the \"Pay with Truemed\" checkout flow. Call this endpoint after the customer clicks \"Checkout with Truemed\" or similar. The customer is redirected to Truemed to complete a health survey and enter HSA/FSA card details, then redirected back to your site via the provided `success_url` or `failure_url`.\n\nThe outcome is communicated asynchronously via the\n[`payment_session_complete`](/api-reference/payment-sessions/payment-session-completed-webhook) webhook.\n\n## Request Notes\n\n- `total_amount` **(Required)**: The total amount in cents to charge the user, inclusive of discounts, shipping, taxes, and other fees being collected by the partner\n - **IMPORTANT**: total_amount must equal the sum of:\n - `payment.amount_details.total_additional_charges`\n - `payment.amount_details.total_discounts`\n - For each order_item, the sum of:\n - `item.quantity * item.price`\n - `item.amount_details.total_additional_charges`\n - `item.amount_details.total_discounts`\n- `amount_details` **(Required)**: [Read further here](/guides/payment-sessions/itemized-fees-and-discounts)\n- `success_url` **(Required)**: Where to redirect the user to after Truemed successfully processes a payment\n - This is often used to display an order confirmation screen, or similar\n - **Templating**:\n - We support limited templating of this URL parameter. Any part of the URL string containing `{{payment_session_id}}` will be replaced by the `id` (UUID) returned by this call.\n - **IMPORTANT**: The template variable must be EXACTLY `{{payment_session_id}}` - no spaces around the braces on either side.\n - For unattended payment flows using payment tokens, the meaning of the `success_url` is slightly different. In such cases a payment may fail because the stored payment methods are expired or otherwise declined. When those failures occur, we will return a 422 status with a `redirect_url` to our page for updating stored payment methods. Merchants should email or otherwise notify users of the need to update their stored payment methods using this url. When users successfully complete that page, they will be redirected to the `success_url` provided here.\n- `failure_url` **(Required)**: When the payment fails in an irrecoverable way, or the user is ineligible to spend HSA/FSA funds on the purchase\n - We attempt to recover from incorrect CVV, or other card detail errors by prompting the user for retry\n - The exact failure reason will be communicated in the call to the partner's `payment_session_complete` callback\n - **Templating**:\n - We support limited templating of this URL parameter. Any part of the URL string containing `{{payment_session_id}}` will be replaced by the `id` (UUID) returned by this call.\n - **IMPORTANT**: The template variable must be EXACTLY `{{payment_session_id}}` - no spaces around the braces on either side.\n - For unattended payment flows using payment tokens, the meaning of the `failure_url` is slightly different. In such cases a payment may fail because the stored payment methods are expired or otherwise declined. When those failures occur, we will return a 422 status with a `redirect_url` to our page for updating stored payment methods. Merchants should email or otherwise notify users of the need to update their stored payment methods using this url. When users start but cancel the update before fully completing the process, they will be redirected to the `failure_url` provided here.\n- `customer_state` **(Optional)**: The 2-letter ISO 3166-2:US code for a region, _without the_ US- _prefix_. For example, California should be provided as CA and Rhode Island as RI\n - If `customer_state` is provided, the state of residence question in the health survey will be prefilled with the full state name that corresponds to the ISO code.\n- `metadata` **(Optional)**: - Will be echoed back in the webhook and detail view if present.\n - **IMPORTANT**: This must be a string. If you want to include JSON, encode it as a string.\n - **IMPORTANT**: DO NOT INCLUDE sensitive information in this field.\n- `kind` **(Optional)**: one of the following:\n - `one_time_payment` **(DEFAULT)**: The charge is not a subscription related charge. This is the default if this field is not set.\n - `authorization`: A `one_time_payment` authorization hold only, must be manually captured or voided with a follow up API call.\n - **NOTE: We don't support authorization holds for subscriptions**\n- `payment_token` **(Conditionally required)**: the ID returned by Truemed on initial recurring charges (when `tokenize=True`).\n - When `payment_token` is provided, customer identity is derived from the token's user. Any `customer_email` or `customer_name` values in the request are ignored.\n- `tokenize` **(Optional)**: `True` or `False` - set to `True` to enable subsequent charges. Must be `False` if `payment_token` is provided.\n- `display_next_bill_info` **(Optional)**: Partners should only provide this field if they want to initiate a free trial subscription for the customer. The information in this object will be displayed on Truemed's checkout page to provide more context to the customer when submitting their payment method(s)\n - `total_amount`: The amount in cents the customer will be charged when the free trial period ends\n - `date`: A YYYY-MM-DD string indicating the date the free trial period ends\n - **IMPORTANT**: This field requires `tokenize=true` and `total_amount=0` (free trial subscriptions only)\n\n### iFrame Payment Session\n\nIf `use_iframe` is set to `true`, `redirect_url` will be iframe-compatible. Refer to iFrame Payment Session for a guide on handling the communication between the iframe and the parent as well as examples.\n\n## Response Notes\n\n### Success Case\n\nHTTP Status: `200`\n\n- `id` - the unique ID for this checkout session. This same ID will be returned if the endpoint is called with the same `idempotency_key`\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\n - `ServerError`: There was an internal server error.\n - Requests can be retried as long as the `idempotency-key` is the same.\n - `SessionPending`: A charge to the existing payment method is unable to be processed because the user has yet to enter a payment method.\n - This is only possible when creating a charge using a `payment_token` before the user has finished the initial checkout (for the `payment_session` created with `tokenize=True`).\n - `TokenizeNotSupported`: Both `tokenize=True` and `payment_token` were set. You can't tokenize a payment session if the session is being billed back to a prior one using a `payment_token`.\n - `FeatureNotEnabled`: A required merchant feature (e.g., Stripe configuration) is not enabled\n- `message`: A human-readable description of the error\n\n### Unprocessable Entity\n\nHTTP Status: `422`\n\nIf a `payment_token` was provided and the `token` requires customer intervention before it can be used again, a `422` will be returned.\n\n- `next_action`: The action the customer must take. Can be one of the following:\n - `UpdatePaymentMethod`: Customer must enter a new payment method.\n - `TakeHealthSurvey`: Customer must retake the health survey\n- `redirect_url`: Contains a URI through which the customer can correct the `payment_token`.", "operationId": "createPaymentSession", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentSessionRequest" } } }, "description": "Request body for CreatePaymentSessionRequest", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentSessionResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "featurenotenabled": { "summary": "FeatureNotEnabled example", "value": { "error": "FeatureNotEnabled", "message": "Bad Request" } }, "idempotencyviolation": { "summary": "IdempotencyViolation example", "value": { "error": "IdempotencyViolation", "message": "Bad Request" } }, "invalidrequestparameter": { "summary": "InvalidRequestParameter example", "value": { "error": "InvalidRequestParameter", "message": "Bad Request" } }, "missingrequiredparameter": { "summary": "MissingRequiredParameter example", "value": { "error": "MissingRequiredParameter", "message": "Bad Request" } }, "orderitemsinvalid": { "summary": "OrderItemsInvalid example", "value": { "error": "OrderItemsInvalid", "message": "Bad Request" } }, "sessionpending": { "summary": "SessionPending example", "value": { "error": "SessionPending", "message": "Bad Request" } }, "tokenizenotsupported": { "summary": "TokenizeNotSupported example", "value": { "error": "TokenizeNotSupported", "message": "Bad Request" } }, "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "properties": { "error": { "enum": [ "FeatureNotEnabled", "IdempotencyViolation", "InvalidRequestParameter", "MissingRequiredParameter", "OrderItemsInvalid", "SessionPending", "TokenizeNotSupported", "TotalAmountInvalid", "ValidationError" ], "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "type": "object" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Page not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Create a new payment session for HSA/FSA checkout", "tags": [ "Payment Sessions" ] } }, "/payments/v1/payment_session/{business_id}": { "get": { "deprecated": false, "description": "Get the status of a payment session based on the payment session id.\n\n## Request Notes\n\nTo get the status of a Payment Session object, call the detail view with the ID of the\npayment session returned by the `create_payment_session` endpoint.\n\n## Response Notes\n\n- `status` - the status of the initial payment, an enum with one of the following values:\n - `captured` - payment has completed\n - `canceled` - payment was canceled before the user entered payment information via a call\n to our cancel API.\n - `pending` - payment has not been successfully completed yet.\n - `processing` - the customer has entered their payment information, but it is under review\n by Truemed\n - Any customer facing communication should indicate successful payment at this point,\n such as on the `success_url`.\n - The merchant should not fulfill the order until the Payment Session Webhook indicates\n that the payment has been captured.\n - `rejected` - While in the `processing` state, Truemed reviewed and rejected the payment\n session.\n - The merchant should not fulfill these orders, and should communicate failure to the\n user via email.\n - `authorized` - an auth hold has been placed on the customer's card.\n - `authorization_voided` - the auth hold has been voided via a call to our Void Session api.\n - `authorization_expired` - the auth hold has expired and we were not able to re-auth the\n transaction. This state is only possible after a call to our Manual Capture api, and is\n only set after we attempt a re-auth hold on the existing payment method.\n- `status_summary` - a summary of the overall payment session. This includes refunds and\n disputes, and is an enum of the following values:\n - `Incomplete` - Customer started checkout but did not complete\n - `Authorized` - Auth hold placed on customer's payment method\n - `Captured` - Payment has been processed\n - `Partially Captured` - The payment has been partially processed\n - `Refunded` - The full amount charged in this order has been refunded to customer\n - `Partially Refunded` - Part of the original order has been refunded to the customer\n - `Disputed` - The transaction has been disputed by the customer\n - `Voided` - The payment was voided by the partner\n - `Expired` - The partner did not capture an authorized session before it expired\n- `order_items` - a list of order items, with the following fields per item:\n - `item_id` - The item_id that uniquely identifies this item. If the client specified one\n when creating the Payment Session, that item_id will be returned.\n - `name` - the name of the item\n - `price` - the unit price in cents charged for the item\n - `quantity` - the number of this item in the cart\n - `sku` - the partner's SKU for the item\n - `total_refundable` **(Optional)** - If the Payment Session has been captured, this value\n will be the remaining amount refundable for this item. Otherwise it will not be included.\n - `quantity_refundable` **(Optional)** - If the Payment Session has been captured, this\n value will be the remaining quantity refundable for this item. Otherwise it will not be\n included.\n - `total_capturable` **(Optional)** - If the Payment Session is an authorization and is\n currently authorized, this value will be the remaining amount capturable for this item.\n Otherwise it will not be included.\n - `quantity_capturable` **(Optional)** - If the Payment Session is an authorization and is\n currently authorized, this value will be the remaining quantity capturable for this item.\n Otherwise it will not be included.\n- `capture_amount` **(Optional)** - the amount of funds actually captured.\n - For payment sessions of `kind=one_time_payment` this field will always be present and\n will be the same as `authorize_amount`.\n - For payment sessions of `kind=authorization` this field will not be present until the\n funds have been captured (via a call to Manual Capture).", "operationId": "retrievePaymentSession", "parameters": [ { "deprecated": false, "description": "The payment session ID.", "in": "path", "name": "business_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSessionDetailResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "missingfield": { "summary": "MissingField example", "value": { "error": "MissingField", "message": "Bad Request" } }, "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "properties": { "error": { "enum": [ "MissingField", "TotalAmountInvalid", "ValidationError" ], "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "type": "object" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "invalidpaymentid": { "summary": "InvalidPaymentId example", "value": { "error": "InvalidPaymentId", "message": "Payment not found." } }, "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Resource not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Retrieve the current status of a payment session", "tags": [ "Payment Sessions" ] } }, "/payments/v1/payment_sessions": { "get": { "deprecated": false, "description": "All payment sessions created with the Create payment session API call can be listed\nvia a GET to `/payments/v1/payment_sessions`.\n\nBy default, all payment sessions, including those that are pending, created as auth\nholds and those that have been manually voided or captured will be listed. Options are\nprovided for granular filtering, pagination, and search.\n\n## Pagination\n\nAll results are paginated, with 30 per page. The response field `pagination` contains\ninformation on how many payment sessions there are and how many pages are available\nfor the filtered query.\n\n## Sorting\n\nPayment sessions are sorted by the date they are created, with newer ones being returned first.\n\n# Response Notes\n\nThe response is an array of payment sessions in the `payment_sessions` key. A few things to point out about\nthe response payload:\n\n- `order_items` **(Optional)** - The list of the current state of the order items passed into\n `create_payment_session` if `include_order_items` is True\n - `total_refundable` **(Optional)** - If the Payment Session has been captured, this value\n will be the remaining amount refundable for this item. Otherwise it will not be included.\n - `quantity_refundable` **(Optional)** - If the Payment Session has been captured, this\n value will be the remaining quantity refundable for this item. Otherwise it will not be\n included.\n - `total_capturable` **(Optional)** - If the Payment Session is an authorization and is\n currently authorized, this value will be the remaining amount capturable for this item.\n Otherwise it will not be included.\n - `quantity_capturable` **(Optional)** - If the Payment Session is an authorization and is\n currently authorized, this value will be the remaining quantity capturable for this item.\n Otherwise it will not be included.\n- `authorized_on` - the date the payment was authorized in ISO 8601 format\n - example: \"2024-06-13T16:03:07.473Z\"\n - For `kind`: `one_time_payment`, this will be the same as `captured_on`\n- `refund_amount` **(Optional)** - int\n - Only present when `summarize_refunds=True` is included in the request.\n - The sum of processed refunds for the payment session, **in cents**\n- `truemed_fee` **(Optional)** - decimal - **in dollars**\n - Only present when `include_truemed_fee=True` is included in the request.\n - The fee collected by truemed for this payment session.\n\nThe response also includes a `pagination` object:\n\n```\n{\n \"pagination\": {\n \"current_page\": 1,\n \"page_size\": 30,\n \"count\": 54,\n \"last_page\": 2\n },\n \"payment_sessions\": [\n ]\n}\n```\n\n- `current_page` - the page requested. If none was provided, this will default to 1.\n- `page_size` - the number of `payment_session`'s per page, which is always 30.\n- `count` - the total number of `payment_session`'s matching the filters provided.\n- `last_page` - the last page.\n - You can iterate through pages by providing integers up to `last_page` in the `page`\n parameter.", "operationId": "listPaymentSession", "parameters": [ { "allowReserved": false, "deprecated": false, "description": "Optional field indicating which page to access. Defaults to 1.", "in": "query", "name": "page", "required": false, "schema": { "type": "integer" } }, { "allowReserved": false, "deprecated": false, "description": "Optional field indicating the number of records per page. Defaults to 30.", "in": "query", "name": "page_size", "required": false, "schema": { "type": "integer" } }, { "allowReserved": false, "deprecated": false, "description": "Filter out pending payment sessions.", "in": "query", "name": "filter_pending", "required": false, "schema": { "type": "boolean" } }, { "allowReserved": false, "deprecated": false, "description": "Filter out voided payment sessions.", "in": "query", "name": "filter_voided", "required": false, "schema": { "type": "boolean" } }, { "allowReserved": false, "deprecated": false, "description": "Include metadata field in the response.", "in": "query", "name": "include_metadata", "required": false, "schema": { "type": "boolean" } }, { "allowReserved": false, "deprecated": false, "description": "Include order items in the response.", "in": "query", "name": "include_order_items", "required": false, "schema": { "type": "boolean" } }, { "allowReserved": false, "deprecated": false, "description": "Search by payment session ID, user business ID, email, or name.", "in": "query", "name": "search", "required": false, "schema": { "type": "string" } }, { "allowReserved": false, "deprecated": false, "description": "Filter payment sessions created on or after this date (ISO 8601 format).", "in": "query", "name": "created_on_start", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "allowReserved": false, "deprecated": false, "description": "Filter payment sessions created on or before this date (ISO 8601 format).", "in": "query", "name": "created_on_end", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "allowReserved": false, "deprecated": false, "description": "Filter payment sessions captured on or after this date (ISO 8601 format).", "in": "query", "name": "captured_on_start", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "allowReserved": false, "deprecated": false, "description": "Filter payment sessions captured on or before this date (ISO 8601 format).", "in": "query", "name": "captured_on_end", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "allowReserved": false, "deprecated": false, "description": "Include refund details in the response (default: true).", "in": "query", "name": "include_refunds", "required": false, "schema": { "type": "boolean" } }, { "allowReserved": false, "deprecated": false, "description": "Include dispute details in the response (default: true).", "in": "query", "name": "include_disputes", "required": false, "schema": { "type": "boolean" } }, { "allowReserved": false, "deprecated": false, "description": "Filter by payment kind (comma-separated list: one_time_payment, authorization).", "explode": false, "in": "query", "name": "kind", "required": false, "schema": { "items": { "type": "string" }, "type": "array" }, "style": "form" }, { "allowReserved": false, "deprecated": false, "description": "Filter by payment session status (comma-separated list).", "explode": false, "in": "query", "name": "status", "required": false, "schema": { "items": { "type": "string" }, "type": "array" }, "style": "form" }, { "allowReserved": false, "deprecated": false, "description": "Include refund_amount summary instead of full refund details.", "in": "query", "name": "summarize_refunds", "required": false, "schema": { "type": "boolean" } }, { "allowReserved": false, "deprecated": false, "description": "Include Truemed fee in the response.", "in": "query", "name": "include_truemed_fee", "required": false, "schema": { "type": "boolean" } }, { "allowReserved": false, "deprecated": false, "description": "Filter payment sessions by payment token ID.", "in": "query", "name": "payment_token", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSessionListResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Page not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "List payment sessions with filtering and pagination", "tags": [ "Payment Sessions" ] } }, "/payments/v1/payment_session/{business_id}/capture": { "post": { "deprecated": false, "description": "The `capture_payment_session` endpoint should be called after [`create_payment_session`](/api-reference/payment-sessions/create-payment-session)\nhas been called with `kind` of `authorization` as outlined in [Manual/Delayed Capture](/guides/payment-sessions/manual-delayed-capture).\n\nThe failure or success status is communicated to the partner via a [`payment_session_complete`](/api-reference/payment-sessions/payment-session-completed-webhook)\nwebhook as before.\n\n## Request Notes\n\n\nThe `total_amount` field will often not be the sum of the `order_item[*].price` fields, as you may be charging additional\nfees or including taxes.\n\n\n- **`total_amount`** *(Required)* - The total amount in cents to charge the user, inclusive of taxes and fees being collected by the partner. **Must be less than or equal to the `total_amount` passed in when creating the payment session.**\n - If an amount more than the initial authorization should be captured, void the initial auth hold and create a new one.\n\n## Response Notes\n\n### Success Case\n\nHTTP Status: `200`\n\n- **`id`** - The unique ID for this session capture. This same ID will be returned if the endpoint is called with the same `idempotency_key`. Associate this id with your internal representation of a checkout session, if applicable.\n\n### Bad Request\n\nHTTP Status: `400`\n\nIf a field is missing or the request otherwise can't be processed, we'll return a `400` with the following fields:\n\n- **`error`** - can be one of:\n - `MissingField`: One of the required fields is not present in the request.\n - `TotalAmountInvalid`: The `total_amount` field is either not greater than or equal to the sum of the `order_item` `amount` fields, is 0, is negative, or is greater than the `total_amount` passed in when creating the payment session.\n - `PaymentSessionDoesNotExist`: The `payment_session_id` does not exist.\n - `ServerError`: There was an internal server error. Requests can be retried as long as the `idempotency_key` is the same.\n - `SessionVoided`: The session has already been voided via a call to [`/payment_session/{payment_session_id}/void`](/api-reference/payment-sessions/void-payment-session).\n - `SessionExpired`: The auth hold has expired and we were unable to recharge the customer for the amount requested.\n - `SessionPending`: The user hasn't completed the Truemed checkout flow (survey, CC entry form).\n - `SessionCaptured`: You're attempting to capture a payment_session that has already been captured. This error **will never** be returned if reissuing a capture call **with the same idempotency key** - the return value will be the same as the first call.\n - `ImmediateCapture`: The caller is attempting to void a payment_session that wasn't created with `kind=authorization`.\n- **`message`** - Indication of which field was missing, details on how the total amount was invalid, or details on voided sessions.", "operationId": "capturePaymentSession", "parameters": [ { "deprecated": false, "description": "The UUID of the payment session returned by create_payment_session.", "in": "path", "name": "business_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSessionCaptureRequest" } } }, "description": "Request body for PaymentSessionCaptureRequest", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSessionCaptureResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "immediatecapture": { "summary": "ImmediateCapture example", "value": { "error": "ImmediateCapture", "message": "This session uses kind=one_time_payment and was automatically captured. Manual capture is only available for sessions created with kind=authorization." } }, "sessioncaptured": { "summary": "SessionCaptured example", "value": { "error": "SessionCaptured", "message": "Cannot capture a payment that has already been captured." } }, "sessionexpired": { "summary": "SessionExpired example", "value": { "error": "SessionExpired", "message": "The auth hold for this payment session has expired." } }, "sessionpending": { "summary": "SessionPending example", "value": { "error": "SessionPending", "message": "Session is still pending." } }, "sessionvoided": { "summary": "SessionVoided example", "value": { "error": "SessionVoided", "message": "Session has been voided." } }, "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "properties": { "error": { "enum": [ "ImmediateCapture", "SessionCaptured", "SessionExpired", "SessionPending", "SessionVoided", "TotalAmountInvalid", "ValidationError" ], "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "type": "object" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Resource not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Capture a previously authorized payment session", "tags": [ "Payment Sessions" ] } }, "/payments/v1/payment_session/{business_id}/cancel": { "post": { "deprecated": false, "description": "The `cancel` API exists so that merchant partners can manage cart lifecycles.\nIn an ideal world, the customer experience would roughly be outlined by:\n\n\n \n The customer browses your store and adds items to their shopping cart.\n \n \n The customer clicks the \"Checkout with Truemed\" button to begin the payment process.\n \n \n The partner calls `create_payment_session`, and an inventory lock is placed on the items in the cart to ensure they can be fulfilled when payment is captured.\n \n \n The customer completes the survey and enters payment information in the Truemed interface.\n \n \n The merchant listens for the Partner webhook callback and fulfills the inventory locked above.\n \n\n\n## Deviations from the Happy Path\n\nIn the flow above, there are a few steps the customer can take that would void the\nexisting session.\n\nThe customer could:\n\n- **Navigate away from Truemed during the survey, and modify their cart.** This\n dictates a new idempotency key (e.g.: a new `payment_session`). As part of clean up\n and to ensure the customer can't navigate back to the now outdated survey link, the\n old payment session must be canceled.\n- **Take too long to complete the survey and finalize payment.** The merchant may wish\n to cancel the `payment_session` and release the lock on inventory as it appears the\n customer is no longer interested in making the purchase.\n\n## Customer Experience for Canceled Sessions\n\nIf this API is used to cancel a pending session, the customer will be shown a page\nindicating that the checkout session has timed out and a link will be provided to\n\"Go back to checkout\" which will return them to the `failure_url` provided in\n`create_payment_session`.\n\nThe page presented by the `failure_url` should be generic and display a relevant\nmessage asking the customer to checkout again if it has been too long.\n\n\"Too long\" is defined by our merchant partners depending on their inventory management.\nWe recommend 48-72 hours as customers will sometimes move funds into their HSA prior to\ncompleting checkout.\n\n# API Overview\n\nThe `cancel_payment_session` endpoint can be called after `create_payment_session` has\nbeen called, but before the customer has entered their payment information, for either\n`kind=authorization` or `kind=one_time_payment`.\n\nThe failure or success status is communicated to the partner via a webhook\n`payment_session_complete` as before.\n\n## Request Notes\n\nThere are no required fields for the request body, you simply call the endpoint with\nthe `payment_session_id` in the URL. The cancel API can be called repeatedly without an\nidempotency key and the same result will be returned.\n\n**Important** - you will only get a single callback queued on successful cancelation\n(albeit, invoked multiple times in the case of failures) as outlined in Partner webhook,\neven if you call the cancel endpoint multiple times.\n\n## Response Notes\n\n### Success Case\n\nHTTP Status: `200`\n\nNote: `order_items.sku` - the partner's SKU for the item. The value of this field will\nbe the SKU provided by the partner in the [`create_payment_session`](/api-reference/payment-sessions/create-payment-session)\nrequest. If the partner does not provide a SKU value for an item on creation of the payment, this\nkey will not be present.\n\n### Failure Case\n\nHTTP Status: `400`\n\nIf a field is missing or the request otherwise can't be processed, we'll return a `400`\nwith the following fields:\n\n- `error` - can be one of:\n - `InvalidPaymentId` - the `payment_session_id` does not exist.\n - `ServerError` - There was an internal server error. Requests can be retried.\n - `SessionCaptured` - The session has already been captured via a call to\n `/payment_session/{payment_session_id}/capture` and can no longer be canceled. In\n this case, to return funds to the customer, you'll need to issue a refund.\n - `SessionAuthorized` - The session has already been authorized. The user has\n completed the survey and entered their credit card information. In this case, the\n session should be voided via the Void Session API, and the customer should be\n informed that their order has been canceled.\n- `message` - Details on the above conditions.", "operationId": "cancelPaymentSession", "parameters": [ { "deprecated": false, "description": "The payment session ID to cancel.", "in": "path", "name": "business_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSessionCancelResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "sessionauthorized": { "summary": "SessionAuthorized example", "value": { "error": "SessionAuthorized", "message": "Payment session has been authorized, it must be voided, not canceled." } }, "sessioncaptured": { "summary": "SessionCaptured example", "value": { "error": "SessionCaptured", "message": "Payment session has already been captured." } }, "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "properties": { "error": { "enum": [ "SessionAuthorized", "SessionCaptured", "TotalAmountInvalid", "ValidationError" ], "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "type": "object" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Resource not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Cancel a pending payment session before completion", "tags": [ "Payment Sessions" ] } }, "/payments/v1/payment_session/{business_id}/void": { "post": { "deprecated": false, "description": "The `void_payment_session` endpoint should be called after\n[`create_payment_session`](/api-reference/payment-sessions/create-payment-session)\nhas been called with `kind` of `authorization` as outlined in [Create Payment Session\n(Manual Capture)](/guides/payment-sessions/manual-delayed-capture).\n\nThe failure or success status is communicated to the partner via a\n[`payment_session_complete`](/api-reference/payment-sessions/payment-session-completed-webhook) webhook as before.\n\n## Response Notes\n\n### Success Case\n\nHTTP Status: `200`\n\n- `id` - the unique ID for this void session. This same ID will be returned if the endpoint\n is called with the same `idempotency_key`\n - Associate this id with your internal representation of a checkout session, if applicable\n\n### Failure Case:\n\nHTTP Status: `400`\n\nIf a field is missing or the request is otherwise can't be processed, we'll return a `400`\nwith the following fields:\n\n- `error` - can be one of:\n - `MissingField`: one of the required fields is not present in the request\n - `PaymentSessionDoesNotExist` - the `payment_session_id` does not exist.\n - `ServerError`: There was an internal server error.\n - Requests can be retried as long as the `idempotency-key` is the same.\n - `SessionCaptured` - The session has already been captured via a call to\n [`/payment_session/{payment_session_id}/capture`](/api-reference/payment-sessions/capture-payment-session)\n and can no longer be voided.\n - In this case, to return funds to the customer, you'll need to issue a refund.\n - `SessionPending` - The survey hasn't been completed by the customer, and no auth hold\n has been placed, so there is no auth hold to void yet.\n - `ImmediateCapture` - The caller is attempting to void a payment_session that wasn't\n created with `kind=authorization`\n- `message`:\n - Indication of one of the following:\n - Which field was missing\n - Details on how the total amount was invalid\n - Details on captured sessions.", "operationId": "voidPaymentSession", "parameters": [ { "deprecated": false, "description": "The UUID of the payment session returned by create_payment_session.", "in": "path", "name": "business_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSessionVoidRequest" } } }, "description": "Request body for PaymentSessionVoidRequest", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSessionVoidResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "immediatecapture": { "summary": "ImmediateCapture example", "value": { "error": "ImmediateCapture", "message": "This session uses kind=one_time_payment and cannot be voided. Void is only available for sessions created with kind=authorization. To reverse a captured payment, use the refund endpoint." } }, "sessioncaptured": { "summary": "SessionCaptured example", "value": { "error": "SessionCaptured", "message": "Session has already been captured." } }, "sessionnotauthorized": { "summary": "SessionNotAuthorized example", "value": { "error": "SessionNotAuthorized", "message": "Cannot void a payment that has not been authorized." } }, "sessionvoided": { "summary": "SessionVoided example", "value": { "error": "SessionVoided", "message": "Cannot void a payment that has already been voided." } }, "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "properties": { "error": { "enum": [ "ImmediateCapture", "SessionCaptured", "SessionNotAuthorized", "SessionVoided", "TotalAmountInvalid", "ValidationError" ], "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "type": "object" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Resource not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Void an authorized payment session before capture", "tags": [ "Payment Sessions" ] } }, "/payments/v1/refund": { "post": { "deprecated": false, "description": "Use this endpoint to refund payments Truemed has already processed on your behalf. Partial refunds are supported.\n\n## Request Notes\n\n\nThe amount requested must be less than or equal to the total amount that the\npayment was originally created with.\n\n\n## Response Notes\n\n### Bad Request\n\nHTTP Status: `400`\n\nIf a field is missing or the request is otherwise can't be processed, we'll return a `400`\nwith the following fields:\n\n- `error` - can be one of:\n - `MissingField`: one of the required fields is not present in the request\n - `AmountInvalid`: the `amount` field is negative, 0, or greater than the amount remaining\n available to refund on the payment\n - `InvalidPaymentId`: requesting to refund a payment that does not exist\n - `ChargeDisputed`: Payment session has a pending dispute. Can't refund until the dispute is\n resolved. Lost disputes reduce the remaining refundable amount but no longer block refunds\n of the undisputed remainder.\n - `NoSessionCaptures`: The payment session can't be refunded because there haven't been any\n funds captured.\n- `message`:\n - Indication of one of the following:\n - Which field was missing\n - Details on how the amount was invalid\n - Invalid payment id", "operationId": "createRefund", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRefundRequest" } } }, "description": "Request body for CreateRefundRequest", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRefundResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Page not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Create a full or partial refund for a captured payment", "tags": [ "Payment Sessions" ] } }, "/api/v1/payment_tokens/create": { "post": { "deprecated": false, "description": "Payment tokens can be created outside of the\n[`create_payment_session`](/api-reference/payment-sessions/create-payment-session) API call. This is most\ncommonly used to support existing subscription customers, allowing them to move their subscriptions\nto their HSA/FSA. Use [`create_payment_session`](/api-reference/payment-sessions/create-payment-session)\nwith `tokenize=True` to create a subscription as part of a checkout flow, such as the first order in a subscription,\nor free trials.\n\n\nFor early access, contact your Truemed sales engineer.\n\n\n# Overview\n\nThis endpoint supports creating a `payment_token` outside of the\n[`create_payment_session`](/api-reference/payment-sessions/create-payment-session) flow,\nand is commonly used to support giving the option to existing subscribers to pay with their\nHSA/FSA. This endpoint can also be used to \"store a payment method with Truemed\" inside of a\nuser dashboard. Subscription free-trials are possible with this endpoint, though we recommend\nusing [`create_payment_session`](/api-reference/payment-sessions/create-payment-session) for trials\nfor consistency with the standard checkout experience.\n\nThis endpoint returns **the ID of a new `provision_token_request`, NOT a new `payment_token`**.\nThe `payment_token` itself will be available upon receipt of the\n[`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook with the corresponding\n`provision_token_request_id`. In order to support backfills in the case of unforeseen downtime\n(a webhook that goes unacknowledged, or is missed), you can also query the status of the\n`provision_token_request` directly as outlined in our\n[`retrieve_provision_token_request`](/api-reference/payment-tokens/retrieve-payment-token-provision-request) docs.\n\n\nPartners only receive valid `payment_tokens` via the\n[`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook. A payment token can't be issued\nuntil the user successfully completes the tele-health survey and/or enters payment information.\nA callback is used to indicate the customer has completed token setup with Truemed.\n\n\nThe diagram below outlines the customer flow when using this endpoint:\n\n\n \n The merchant partner calls `create_payment_token` and receives a `redirect_url`.\n \n \n The customer is redirected to the `redirect_url` and completes the tele-health survey and enters payment information.\n \n \n The customer is redirected to the `success_url` provided by the merchant during the initial call to `create_payment_token`.\n \n \n Truemed issues a [`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook including the newly provisioned `payment_token`. Customer email and name are included along with the `metadata` field to aid in linking to existing data in the partner's backend.\n \n\n\n```mermaid\nsequenceDiagram\n participant User\n participant Partner\n participant Truemed\n\n User->>Partner: Add HSA/FSA card option\n Partner->>Truemed: create_payment_token request\n Truemed-->>Partner: redirect_url response\n Partner-->>User: Redirect to redirect_url\n User->>Truemed: Complete eligibility survey\n Note over User: User eligible for HSA/FSA\n Truemed-->>User: Show payment method form\n User->>Truemed: Enter HSA/FSA card details\n Note over User: Payment method stored\n Truemed->>Partner: payment_token_callback webhook\n Truemed-->>User: Redirect to success_url\n```\n\n\nThe webhook/callback is invoked at the same time the user is being redirected to the\n`success_url` - we don't guarantee that it will be called before the redirect.\n\n\n\n**The customer must be in the flow** when calling this endpoint, typically from within a\nsubscription management dashboard.\n\n\n**Primary Use Cases for this Endpoint:**\n\n- **Supporting existing customers**\n - You may have existing subscriptions customers that want to move their subscription over to\n their HSA/FSA card. Providing a \"use your HSA/FSA via Truemed\" button within a subscription\n management dashboard powered by this endpoint allows you to do that.\n- **Store payment method with Truemed**\n - Allow customers to add an HSA to their account for future use\n- **Free-trial support (non preferred)**\n - Allowing customers to qualify for a given subscription and store their payment info for\n future use.\n - \u26a0\ufe0f **We recommend using `create_payment_session` with `tokenize=True` for free trials** as\n outlined in the main subscription guide to reflect the fact that the customer is \"checking\n out\", though at no-cost.\n\n\nAll subscription related fields here are to enhance the customer experience, you'll need your\nown subscription management system.\n\n\n## Request Notes\n\n- **success_url** (Required): Where to redirect the user to after the customer successfully\n completes the tele-health survey and their payment method(s) have been stored.\n - This is often used to display a confirmation screen, or similar\n- **failure_url** (Required): When the user opts to not complete the tele-health survey or selects\n \"cancel\" during the process, or when the user is ineligible to spend HSA/FSA funds on the items\n in the request.\n - We attempt to recover from incorrect CVV, or other card detail errors by prompting the user\n for retry\n- **customer_state** (Optional): The 2-letter ISO 3166-2:US code for a region, without the `US-`\n prefix. For example, California should be provided as `CA` and Rhode Island as `RI`.\n - If `customer_state` is provided, the state of residence question in the health survey will be\n prefilled with the full state name that corresponds to the ISO code.\n- **metadata** (Optional): Will be echoed back in the\n [`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook and detail endpoint if present.\n - **Important**: This must be a string. If you want to include JSON, encode it as a string.\n - **Important**: DO NOT INCLUDE sensitive information in this field.\n- **use_iframe** (Optional): Optional query parameter that can be used to modify the response's\n `redirect_url` so it can be used and communicated with in an iframe.\n\n## iFrame Support\n\nIf `use_iframe` is set to `true`, `redirect_url` will be iframe-compatible. Partners can create\nan iframe and set the `src` to `redirect_url` and this will render Truemed's survey and checkout\nflow in the iframe.\n\nWhen using iframes, the flow completion is communicated via `postMessage`. The parent window\nshould listen for messages from the iframe. The message will contain:\n\n- **success**: Returns `true` if checkout flow was successful on Truemed's end, `false` if\n otherwise\n- **redirectUrl**: String that will be set to `success_url` from the original request body if\n `success` is `true` or set to `failure_url` if `success` is `false`.\n - Only need to be used if redirect is desired or can handle success and failure differently\n\n## Response Notes\n\n### Success Case\n\n**HTTP Status: 200:**\n\n- **provision_token_request_id**: A UUID that represents this creation request.\n - This ID is returned along with the provisioned `payment_token` in the\n [`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook.\n - You can query the status of this request using the\n [`retrieve_provision_token_request`](/api-reference/payment-tokens/retrieve-payment-token-provision-request) endpoint.\n- **redirect_url**: Contains a URI through which the customer can complete the `payment_token`.\n\n### Bad Request\n\n**HTTP Status: 400**\n\nIf a field is missing or the request otherwise can't be processed, we'll return a 400 with the\nfollowing fields:\n\n- **error**: Can be one of:\n - `MissingField`: One of the required fields is not present in the request\n - `IdempotencyViolation`: An `idempotency_key` was reused with different request parameters or\n the customer email specified in the request already has a payment token provisioned. Check to\n see if a [`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook was already received for\n this customer. To update, use the [`update_payment_token`](/api-reference/payment-tokens/update-payment-token)\n endpoint.\n - `WaitingForVerification`: If the lmn verification process has started, you cannot attempt to\n call this endpoint again for the same customer email. If you receive this error, please wait\n for the [`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook and then use the\n [`update_payment_token`](/api-reference/payment-tokens/update-payment-token) endpoint.\n - `ServerError`: There was an internal server error.\n - Requests can be retried as long as the `idempotency_key` is the same.\n - `ValidationError`: There was an issue with the request. Check the `message` field for the\n exact issue.\n- **message**: Detailed string explaining the reason for the failure.", "operationId": "createPaymentToken", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentTokenRequest" } } }, "description": "Request body for CreatePaymentTokenRequest", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentTokenResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "featurenotenabled": { "summary": "FeatureNotEnabled example", "value": { "error": "FeatureNotEnabled", "message": "Bad Request" } }, "idempotencyviolation": { "summary": "IdempotencyViolation example", "value": { "error": "IdempotencyViolation", "message": "The same idempotency key was used for different requests" } }, "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } }, "waitingforverification": { "summary": "WaitingForVerification example", "value": { "error": "WaitingForVerification", "message": "The lmn verification process is ongoing." } } }, "schema": { "properties": { "error": { "enum": [ "FeatureNotEnabled", "IdempotencyViolation", "TotalAmountInvalid", "ValidationError", "WaitingForVerification" ], "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "type": "object" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Page not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Create a payment token for recurring billing", "tags": [ "Payment Tokens" ] } }, "/api/v1/payment_tokens/{payment_token}": { "get": { "deprecated": false, "description": "Get data back for a given `payment_token`.\n\nThis endpoint returns details about the `payment_token` specified in the URL path.\nThis endpoint can be used to populate information on a user facing dashboard,\nsuch as the last 4 of the card(s) on file and the expiration dates.\n\nPartners should store expiration dates of cards on file and preemptively encourage\nusers to update their payment methods (using a call to\n[`update_payment_token`](/api-reference/payment-tokens/update-payment-token)) to avoid the failure scenarios\noutlined in our [subscriptions guide](/guides/subscriptions/subsequent-billing-periods).\n\n## Request Notes\n\n**Path Params:**\n- **payment_token** (Required): The `payment_token` string provided by the\n [`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook.", "operationId": "retrievePaymentToken", "parameters": [ { "deprecated": false, "description": "The payment token to get details for", "in": "path", "name": "payment_token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentTokenResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "invalidtoken": { "summary": "InvalidToken example", "value": { "error": "InvalidToken", "message": "Payment Token not found" } }, "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Resource not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Retrieve details of a stored payment token", "tags": [ "Payment Tokens" ] } }, "/api/v1/payment_tokens": { "get": { "deprecated": false, "description": "Lists all payment tokens created with the [`create_payment_token`](/api-reference/payment-tokens/create-payment-token)\nand [`create_payment_session`](/api-reference/payment-sessions/create-payment-session) endpoints.\n\nThis endpoint returns a paginated view of all payment tokens\nassociated with the API key used in the request header, sorted by their `created_at`\ndate in descending order. Optional search fields are provided to aid in finding the\ntoken or tokens associated with a given user.", "operationId": "listPaymentToken", "parameters": [ { "allowReserved": false, "deprecated": false, "description": "Optional field indicating which page to access. Defaults to 1.", "in": "query", "name": "page", "required": false, "schema": { "type": "integer" } }, { "allowReserved": false, "deprecated": false, "description": "Optional field indicating the number of records per page. Defaults to 30.", "in": "query", "name": "page_size", "required": false, "schema": { "type": "integer" } }, { "allowReserved": false, "deprecated": false, "description": "The email to search for. Partial matches supported, using 'includes' semantics.", "in": "query", "name": "email", "required": false, "schema": { "type": "string" } }, { "allowReserved": false, "deprecated": false, "description": "The name to search for. Partial matches supported, using 'includes' semantics.", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "allowReserved": false, "deprecated": false, "description": "Filter payment tokens with cards expiring on or before this month (YYYY-MM format, e.g., '2024-06')", "in": "query", "name": "card_expires_before", "required": false, "schema": { "type": "string" } }, { "allowReserved": false, "deprecated": false, "description": "Filter payment tokens with lmns expiring on or before this month (YYYY-MM-DD) format, e.g., '2024-06-15')", "in": "query", "name": "lmn_expires_before", "required": false, "schema": { "format": "date", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentTokenListResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Page not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "List payment tokens with filtering and pagination", "tags": [ "Payment Tokens" ] } }, "/api/v1/payment_tokens/{payment_token}/update": { "post": { "deprecated": false, "description": "Endpoint allowing your customers to update their payment method(s) and/or requalify\nafter a cart change.\n\n## Overview\n\nThe `update_payment_token` endpoint is available for partners to call when customers\nchange the items in their subscription or when they want to update their card(s) on\nfile.\n\nIf `update_card_info=False` and only the `order_items` are being updated, the user\n**may or may not need to retake the tele-health survey** depending on a variety of\nfactors. The `next_action` field in the response body will indicate what the customer\nmust do next, and a `redirect_url` will be provided if the customer needs to take action.\n\nIf you call this endpoint and the `next_action` is not `None`, and a `redirect_url` is\npresent, we don't guarantee you can invoke\n[`create_payment_session`](/api-reference/payment-sessions/create-payment-session) with the `payment_token` until the user\nhas completed the action and you've received the\n[`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook.\n\n\nThe customer must be in the flow when calling this endpoint, typically from within a\nsubscription management dashboard.\n\n\n**Primary Use Cases for this Endpoint:**\n\n- Allowing customers to update their card(s) on file with Truemed\n- Ensuring that the user is still eligible to use their HSA/FSA after a cart/subscription\n change.\n - If the customer must requalify by retaking the tele-health survey, the `next_action`\n will be `HealthSurvey`, which can be taken by redirecting the customer to the\n `redirect_url`.\n\n\nAll subscription related fields here are to enhance the customer experience, a dedicated\nsubscription management system is needed on the partner's side.\n\n\nThe diagram below outlines the customer flow when using this endpoint:\n\n\n \n Partner invokes `update_payment_token` triggered by a customer action. The customer is either updating their payment method(s) or has made a change to the items in their subscription.\n \n \n The partner redirects the customer to the `redirect_url` if `next_action` is not `None`. The customer completes the required action on Truemed's site.\n \n \n The customer is redirected to the `success_url` upon completion of the next action on Truemed's site.\n \n \n Truemed issues a [`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook indicating that the `payment_token` has been updated.\n \n\n\n```mermaid\nsequenceDiagram\n participant User\n participant Partner\n participant Truemed\n\n User->>Partner: Update payment method or cart\n Partner->>Truemed: update_payment_token request\n Truemed-->>Partner: redirect_url response\n Partner-->>User: Redirect to redirect_url (if needed)\n User->>Truemed: Complete survey or update card\n Note over User: User eligible or card updated\n Truemed->>Partner: payment_token_updated webhook\n Truemed-->>User: Redirect to success_url\n```\n\n\nThe webhook/callback is invoked at the same time the user is being redirected\nto the `success_url` - we don't guarantee that it will be called before the redirect.\n\n\n## Request Notes\n\n- **update_card_info** (Optional): boolean - Indicates if this request is to update the\n card(s) on file.\n - If set to `True`, the response will always include `redirect_url` so the user can\n update their payment method(s) on file with Truemed.\n- **order_items** (Optional): An array of `order_item` objects, each with the following\n fields:\n - **name** (Required): string - the name of the item.\n - **sku** (Required): sku - the SKU or id for this product.\n - **NOTES**: This should only be supplied when the user is changing the items associated\n with a given subscription\n- **success_url** (Required): Where to redirect the user to after the customer successfully\n completes the tele-health survey and/or updates their payment method(s).\n - This is often used to display a confirmation screen, or similar\n- **failure_url** (Required): When the user opts to not complete the tele-health survey or\n selects \"cancel\" during the process, or when the user is ineligible to spend HSA/FSA funds\n on the items in the request.\n - We attempt to recover from incorrect CVV, or other card detail errors by prompting the\n user for retry\n- **use_iframe** (Optional): Optional query parameter that can be used to modify the\n response's `redirect_url` so it can be used and communicated with in an iframe.\n- **metadata** (Optional): Any additional data supplied by the partner. This will be echoed\n back in the `payment_token_updated` webhook after the `update_payment_token` flow is\n complete.\n - **Important**: This must be a string. If you want to include JSON, encode it as a string.\n - **Important**: DO NOT INCLUDE sensitive information in this field.\n\n## iFrame Support\n\nIf `use_iframe` is set to `true`, `redirect_url` will be iframe-compatible. Partners can\ncreate an iframe and set the `src` to `redirect_url` and this will render Truemed's survey\nand checkout flow in the iframe.\n\nWhen using iframes, the flow completion is communicated via `postMessage`:\n\n- **success** - Returns `true` if checkout flow was successful on Truemed's end, `false` if\n otherwise\n- **redirectUrl** - string that will be set to `success_url` from the original request body\n if `success` is `true` or set to `failure_url` if `success` is `false`. Only need to be\n used if redirect is desired or can handle success and failure differently.\n\n## Response Notes\n\n### Success Case\n\n**HTTP Status: 200:**\n\n- **next_action**: The action the customer must take. Can be one of the following:\n - `UpdatePaymentMethod`: Customer must enter a new payment method.\n - `HealthSurvey`: Customer must take the health survey\n - `None`: There is no other action needed at this time.\n- **redirect_url**: Contains a URI through which the customer can complete the\n `payment_token`. If `next_action=None`, this field won't be present.\n\n### Bad Request\n\n**HTTP Status: 400**\n\nIf a field is missing or the request otherwise can't be processed, we'll return a 400 with\nthe following fields:\n\n- **error**: Can be one of:\n - `MissingField`: One of the required fields is not present in the request\n - `IdempotencyViolation`: An `idempotency_key` was reused with different request parameters\n - `ServerError`: There was an internal server error.\n - Requests can be retried as long as the `idempotency_key` is the same.\n - `InvalidToken`: The requested token was not found\n - `IneligibleItemAdded`: A new item is ineligible for HSA/FSA spend. Can be returned when\n requesting to update the items associated with a customer's `payment_token`\n- **message**: Indication of one of the following:\n - Which field was missing\n - Details on how the total amount was invalid", "operationId": "updatePaymentToken", "parameters": [ { "deprecated": false, "description": "The payment token to update", "in": "path", "name": "payment_token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePaymentTokenRequest" } } }, "description": "Request body for UpdatePaymentTokenRequest", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePaymentTokenResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "featurenotenabled": { "summary": "FeatureNotEnabled example", "value": { "error": "FeatureNotEnabled", "message": "Bad Request" } }, "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "invalidtoken": { "summary": "InvalidToken example", "value": { "error": "InvalidToken", "message": "Payment Token not found" } }, "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Resource not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Update metadata on a stored payment token", "tags": [ "Payment Tokens" ] } }, "/api/v1/payment_tokens/{payment_token}/delete": { "post": { "deprecated": false, "description": "Invoke this endpoint to invalidate a `payment_token`.\n\nThe delete endpoint removes the `payment_token` after which the token will no longer\nwork for calls to [`create_payment_session`](/api-reference/payment-sessions/create-payment-session).\n\nThe request body should be empty.\n\n\n## Response Notes\n\n### Success Case\n\n**HTTP Status: 204** - No content is returned on successful deletion.\n\n### Error Cases\n\n**HTTP Status: 404** - If the `payment_token` is not found or does not belong to the\nrequesting sales channel.", "operationId": "deletePaymentToken", "parameters": [ { "deprecated": false, "description": "The payment token to delete.", "in": "path", "name": "payment_token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentTokenDeleteResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "featurenotenabled": { "summary": "FeatureNotEnabled example", "value": { "error": "FeatureNotEnabled", "message": "Bad Request" } }, "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Resource not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Delete a stored payment token and its associated methods", "tags": [ "Payment Tokens" ] } }, "/api/v1/payment_tokens/provision_request/{provision_token_request_id}": { "get": { "deprecated": false, "description": "Check the status of a [`create_payment_token`](/api-reference/payment-tokens/create-payment-token)\nor [`update_payment_token`](/api-reference/payment-tokens/update-payment-token) API calls.\n\nThe `retrieve_provision_token_request` endpoint returns details about the request to\ncreate or update a `payment_token`. This endpoint is only provided as a fall back to\nthe [`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook and is only necessary\nfor as fallback for the [`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook.\n\n## Request Notes\n\n**Path Params:**\n- **provision_token_request_id** (Required): The `provision_token_request_id` string\n returned by Truemed to the partner either:\n - in response to a [`create_payment_token`](/api-reference/payment-tokens/create-payment-token) request\n - in a response to a [`update_payment_token`](/api-reference/payment-tokens/update-payment-token) request\n\n## Response Notes\n\n### Success Case\n\n**HTTP Status: 200**\n\n- **payment_token** (Optional): string - the `payment_token` created as part of the\n `provision_request`, if one exists. Null otherwise.\n - Use the [`retrieve_payment_token`](/api-reference/payment-tokens/retrieve-payment-token) endpoint to get\n more information on the token.\n- **metadata**: (Optional) - returned if supplied in the call to\n [`create_payment_token`](/api-reference/payment-tokens/create-payment-token).", "operationId": "retrievePaymentTokenProvisionRequest", "parameters": [ { "deprecated": false, "description": "The ID of a ProvisionTokenRequest returned via create_payment_token", "in": "path", "name": "provision_token_request_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentTokenProvisionRequestDetailResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "featurenotenabled": { "summary": "FeatureNotEnabled example", "value": { "error": "FeatureNotEnabled", "message": "Bad Request" } }, "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Provision request not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Retrieve the status of a payment token provision request", "tags": [ "Payment Tokens" ] } }, "/api/v1/qualification_session/{qualification_session_id}": { "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.\n\n## Response Notes\n\n- `status` - the status of the qualification session, an enum with one of the\n following values:\n - `pending` - the User has not yet 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 for the\n items specified in the `create_qualification_session` API call's `order_items`\n field.\n - `rejected` - the user is ineligible to receive a Letter-of-Medical-Necessity for\n the items specified in the `create_qualification_session` API call's\n `order_items` field.", "operationId": "retrieveQualificationSession", "parameters": [ { "deprecated": false, "description": "The qualification session ID from the URL path", "in": "path", "name": "qualification_session_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QualificationSessionResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Qualification session not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Retrieve details and eligibility result of a qualification session", "tags": [ "Qualification Sessions" ] } }, "/api/v1/qualification_sessions": { "get": { "deprecated": false, "description": "Returns a paginated view of all Qualification Sessions associated with the API key used\nin the request header, sorted by their `created_at` date. Optional search fields are provided\nto aid in finding the session or sessions associated with a given user.\n\n## Request Notes\n\nQuery Params:\n\n- `status` (Optional): enum - filter Qualification Sessions by one of the following\n values:\n - `pending` - incomplete sessions (the user hasn't finished the survey)\n - `processing` - survey answers are under review\n - `approved` - the user qualified\n - `rejected` - the user did not qualify\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 supplied status(es). Can supply multiple separated by commas. Statuses: pending, processing, approved, rejected.", "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" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QualificationSessionListResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Page not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "List qualification sessions with filtering and pagination", "tags": [ "Qualification Sessions" ] } }, "/api/v1/product_catalog/truemed_checkout_method": { "post": { "deprecated": false, "description": "This endpoint is intended to be used to make yes/no decisions about whether to display Truemed as a checkout option for a given set of items. It is limited in that it does not determine whether or not an order containing the items will truly be eligible for Truemed checkout because it does not receive prices, discounts nor additional charges. Any new items received will be created and subsequently categorized.", "operationId": "truemedCheckoutMethod", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TruemedCheckoutMethodRequest" } } }, "description": "Request body for TruemedCheckoutMethodRequest", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TruemedCheckoutMethodResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Page not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Check if Truemed checkout is available for a cart", "tags": [ "Product Catalog" ] } }, "/api/v1/product_catalog/items/create": { "post": { "deprecated": false, "description": "Create a catalog item. The product will not be immediately categorized.", "operationId": "createItem", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateItemRequest" } } }, "description": "Request body for CreateItemRequest", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateItemResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Page not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "409": { "content": { "application/json": { "examples": { "conflict": { "summary": "Conflict example", "value": { "error": "Conflict", "message": "Catalog Item with this SKU already exists." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Conflict" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Create a new item in the product catalog", "tags": [ "Product Catalog" ] } }, "/api/v1/product_catalog/items/update": { "post": { "deprecated": false, "description": "Update an item in the product catalog. The product will not be immediately re-categorized.", "operationId": "updateItem", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateItemRequest" } } }, "description": "Request body for UpdateItemRequest", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateItemResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "No catalog item found with the provided SKU." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Update an existing item in the product catalog", "tags": [ "Product Catalog" ] } }, "/api/v1/product_catalog/items/detail": { "post": { "deprecated": false, "description": "Retrieve details of a catalog item by SKU.", "operationId": "getItemDetail", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailItemRequest" } } }, "description": "Request body for DetailItemRequest", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailItemResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "examples": { "totalamountinvalid": { "summary": "TotalAmountInvalid example", "value": { "error": "TotalAmountInvalid", "message": "Bad Request" } }, "validationerror": { "summary": "ValidationError example", "value": { "error": "ValidationError", "message": "Bad Request" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "notfound": { "summary": "NotFound example", "value": { "error": "NotFound", "message": "Page not found" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "405": { "content": { "application/json": { "examples": { "methodnotallowed": { "summary": "MethodNotAllowed example", "value": { "error": "MethodNotAllowed", "message": "Method not allowed" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Method Not Allowed" }, "500": { "content": { "application/json": { "examples": { "servererror": { "summary": "ServerError example", "value": { "error": "ServerError", "message": "Internal server error" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "examples": { "notimplemented": { "summary": "NotImplemented example", "value": { "error": "NotImplemented", "message": "Not Implemented" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" } }, "security": [ { "truemed-api-key-rest": [] } ], "summary": "Retrieve details and eligibility status of a catalog item", "tags": [ "Product Catalog" ] } } }, "webhooks": { "paymentsessioncompleted": { "post": { "deprecated": false, "description": "The partner is required to implement an endpoint that Truemed can send requests to inform\nof the checkout status.\n\nWe'll call the `payment_session_complete` webhook once each time the `status` of the\n`payment_session` changes, including sessions that have been canceled, voided, and captured.\nFor delayed capture, we'll issue the webhook call for authorization (when the customer first\nsuccessfully enters card information), and again after the partner has manually captured funds\nvia the capture api.\n\nIn successful payment cases, we'll first issue a webhook indicating that the `payment_session`\nhas transition from `pending` to `processing`, after which you can expect a webhook\ntransitioning from `processing` to `captured` (in the default / immediate capture cases), and\nto `authorized` in the case of [Manual/Delayed Capture](/guides/payment-sessions/manual-delayed-capture).\n\n\nOrders should not be fulfilled until a webhook is received with a status\nof `captured`.\n\n\n**Authentication**: Partners should verify the request comes from Truemed by checking that\nthe API key is present in the `x-truemed-api-key` HTTP header.\n\n## Request Notes\n\nHeaders:\n\n- `x-truemed-api-key` - The partner's API key.\n\nNotable fields:\n\n- `status` - the status of the payment from Truemed's perspective\n - `captured` - payment has completed\n - `canceled` - payment was canceled before the user entered payment information via a call\n to our cancel API.\n - `pending` - payment has not been successfully completed yet.\n - `processing` - the customer has entered their payment information, but it is under review\n by Truemed\n - Any customer facing communication should indicate successful payment at this point,\n such as on the `success_url`.\n - The merchant should not fulfill the order until the Payment Session Webhook indicates\n that the payment has been captured.\n - `rejected` - While in the `processing` state, Truemed reviewed and rejected the payment\n session.\n - The merchant should not fulfill these orders, and should communicate failure to the\n user via email.\n - `authorized` - an auth hold has been placed on the customer's card.\n - `authorization_voided` - the auth hold has been voided via a call to our Void Session api.\n - `authorization_expired` - the auth hold has expired and we were not able to re-auth the\n transaction. This state is only possible after a call to our Manual Capture api, and is\n only set after we attempt a re-auth hold on the existing payment method.\n- `capture_amount` **(Optional)** - the amount of funds actually captured.\n - For payment sessions of `kind=one_time_payment` this field will always be present and\n will be the same as `authorize_amount`.\n - For payment sessions of `kind=authorization` this field will not be present until the\n funds have been captured (via a call to Manual Capture).\n- `order_items` - a list of order items, with the following fields per item:\n - `total_refundable` **(Optional)** - If the Payment Session has been captured, this value\n will be the remaining amount refundable for this item. Otherwise it will not be included.\n - `quantity_refundable` **(Optional)** - If the Payment Session has been captured, this\n value will be the remaining quantity refundable for this item. Otherwise it will not be\n included.\n - `total_capturable` **(Optional)** - If the Payment Session is an authorization and is\n currently authorized, this value will be the remaining amount capturable for this item.\n Otherwise it will not be included.\n - `quantity_capturable` **(Optional)** - If the Payment Session is an authorization and is\n currently authorized, this value will be the remaining quantity capturable for this item.\n Otherwise it will not be included.\n- `payment_token` **(Optional)** - Optional string indicating the `payment_token` used for\n the payment session. This field will be set only if the partner provided `tokenize=True` or\n a `payment_token` in the `create_payment_session` request, as outlined in our Subscriptions\n Flow\n\n## Response Body Documentation\n\n### Success Case\n\nHTTP Status: `204`\n\nThe partner does not need to include any content in the body\n\n### Failure Case\n\nTruemed will retry the requests to your backend with backoff for up to 7 days", "operationId": "paymentSessionCompletedWebhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusUpdateWebhookPayload" } } }, "description": "Webhook payload for paymentsessioncompleted", "required": true }, "responses": { "204": { "description": "Webhook received successfully (HTTP 204 No Content)" }, "400": { "description": "Invalid payload or authentication failure" }, "500": { "description": "Server error processing webhook" } }, "security": [ { "truemed-api-key-webhook": [] } ], "summary": "Payment Session Complete Webhook", "tags": [ "Payment Sessions" ] } }, "paymenttokenupdated": { "post": { "deprecated": false, "description": "The partner is required to implement an endpoint that Truemed requests to inform the partner\nof updates made to payment tokens which back customer subscriptions.\n\nThe `payment_token_updated` webhook is invoked when:\n\n1. A `payment_token` is provisioned using [`create_payment_session`](/api-reference/payment-sessions/create-payment-session)\n2. A customer updates their payment token due to one of the failure cases outlined in the\n subscriptions guide, or as part of [`update_payment_token`](/api-reference/payment-tokens/update-payment-token)\n3. A `payment_token` is provisioned using [`create_payment_token`](/api-reference/payment-tokens/create-payment-token)\n\nThe request body includes the `payment_token`, and one of 3 optional IDs mapping back to the\noriginating entity (`payment_session_id`, `failed_payment_session_id`, or\n`provision_token_request_id`).\n\nOnce you receive this webhook, the `payment_token` can successfully be used in subsequent\ncalls to [`create_payment_session`](/api-reference/payment-sessions/create-payment-session).\n\n**Authentication**: Partners should verify the request comes from Truemed by checking that\nthe API key is present in the `x-truemed-api-key` HTTP header.\n\n## Request Notes\n\n- `payment_token`: the `payment_token` returned to the partner by Truemed in response to a\n [`create_payment_session`](/api-reference/payment-sessions/create-payment-session) request\n when `tokenize` was set to `True`\n- `payment_session_id`: **(Optional)** the `id` of the `payment_session` returned by\n `create_payment_session`\n - This is used if the `payment_token` was provisioned as part of a `create_payment_session`\n with `tokenize=true`.\n- `failed_payment_session_id`: **(Optional)** the `id` returned to the partner by Truemed in\n response to a `create_payment_session` request\n - Only present if the `payment_token` was used in [`create_payment_session`](/api-reference/payment-sessions/create-payment-session)\n and failed to be charged as outlined in the failure cases in the [Subscriptions Guide](/guides/subscriptions/overview).\n- `provision_token_request_id`: **(Optional)**\n - Present when provisioning/updating a `payment_token` with a call to\n [`create_payment_token`](/api-reference/payment-tokens/create-payment-token) or\n [`update_payment_token`](/api-reference/payment-tokens/update-payment-token)\n\n## Response Notes\n\n### Success Case\n\nHTTP Status: `204`\n\nThe partner does not need to include any content in the body, but MUST respond with `204`.\n\n### Failure Case\n\nTruemed will retry the requests to your backend with backoff for up to 7 days", "operationId": "paymentTokenUpdatedWebhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentTokenUpdatedWebhookPayload" } } }, "description": "Webhook payload for paymenttokenupdated", "required": true }, "responses": { "204": { "description": "Webhook received successfully (HTTP 204 No Content)" }, "400": { "description": "Invalid payload or authentication failure" }, "500": { "description": "Server error processing webhook" } }, "security": [ { "truemed-api-key-webhook": [] } ], "summary": "Payment Token Updated Webhook", "tags": [ "Payment Tokens" ] } }, "productcatalogitemeligibilityupdated": { "post": { "deprecated": false, "description": "The partner can implement an endpoint that Truemed calls when the HSA/FSA eligibility status\nof an item changes.\n\nThis webhook is triggered when:\n\n1. An item's eligibility is updated (e.g., from `ineligible` to `eligible_with_lmn`)\n2. An item is reviewed and its eligibility status is determined\n\n**Authentication**: Partners should verify the request comes from Truemed by checking that\nthe `x-truemed-api-key` HTTP header matches their API key.\n\n## Request Notes\n\nThe webhook payload follows an envelope structure:\n\n- `event_type` - The event type identifier: `product_catalog.item.eligibility_updated`\n- `timestamp` - ISO-8601 timestamp of when the event occurred\n- `data.object` - The item details including:\n - `sku` - The SKU of the item\n - `name` - The name of the item\n - `eligibility` - The HSA/FSA eligibility status:\n - `eligible` - Item is default eligible for HSA/FSA\n - `eligible_with_lmn` - Item is eligible with a Letter of Medical Necessity\n - `ineligible` - Item is not eligible for HSA/FSA\n - `reviewed_at` - ISO-8601 timestamp of when the item was last reviewed\n\n## Response Notes\n\n### Success Case\n\nHTTP Status: `204`\n\nThe partner does not need to include any content in the body.\n\n### Failure Case\n\nTruemed will retry the requests to your backend with backoff for up to 7 days", "operationId": "productCatalogItemEligibilityUpdatedWebhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCatalogItemEligibilityUpdatedWebhookPayload" } } }, "description": "Webhook payload for productcatalogitemeligibilityupdated", "required": true }, "responses": { "204": { "description": "Webhook received successfully (HTTP 204 No Content)" }, "400": { "description": "Invalid payload or authentication failure" }, "500": { "description": "Server error processing webhook" } }, "security": [ { "truemed-api-key-webhook": [] } ], "summary": "Item Eligibility Updated Webhook", "tags": [ "Product Catalog" ] } }, "qualificationstatusupdated": { "post": { "deprecated": false, "description": "The partner is required to implement an endpoint that Truemed requests to inform the partner\nof the `qualification_session` status.\n\nThe `qualification_session_complete` webhook will only be called once for each qualification\nsession, on status change to `approved`, or `rejected`.\n\n**Authentication**: Partners should verify the request comes from Truemed by checking that\nthe API key is present in the `x-truemed-api-key` HTTP header.\n\n## Request Notes\n\n- `status` - the status of the qualification session, an enum with one of the following\n values:\n - `pending` - the user hasn't has not completed the survey\n - `processing` - the user has completed the session and it is under review\n - `approved` - the user has been issued a Letter-of-Medical-Necessity\n - `rejected` - the user is ineligible to receive a Letter-of-Medical-Necessity\n- `expires_at`: **(Optional)** - the datetime at which the Letter-of-Medical-Necessity expires\n - If the Letter-of-Medical-Necessity hasn't been issued, this field will be `null`.\n- `user_id`: **(Optional)** - the `user_id` provided in the qualification session redirect\n URL param\n - This field will be `null` if `user_id` wasn't provided in the URL for creation.\n- `source`: **(Optional)** - the `source` provided in the qualification session redirect URL\n param\n - This field will be `null` if `source` wasn't provided in the URL for creation.\n\n## Response Notes\n\n### Success Case\n\nHTTP Status: `204`\n\nThe partner does not need to include any content in the body.\n\n### Failure Case\n\nTruemed will retry the requests to your backend with backoff for up to 7 days", "operationId": "qualificationStatusUpdatedWebhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QualificationSessionStatusUpdatedWebhookPayload" } } }, "description": "Webhook payload for qualificationstatusupdated", "required": true }, "responses": { "204": { "description": "Webhook received successfully (HTTP 204 No Content)" }, "400": { "description": "Invalid payload or authentication failure" }, "500": { "description": "Server error processing webhook" } }, "security": [ { "truemed-api-key-webhook": [] } ], "summary": "Qualification Session Complete Webhook", "tags": [ "Qualification Sessions" ] } } }, "components": { "schemas": { "Address": { "properties": { "city": { "description": "City for address", "title": "City", "type": "string" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "2-letter ISO 3166 for address", "title": "Country" }, "line1": { "description": "First line of address", "title": "Line1", "type": "string" }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Second line of address", "title": "Line2" }, "postal_code": { "description": "Zip code for address", "title": "Postal Code", "type": "string" }, "state": { "description": "State for address", "title": "State", "type": "string" } }, "required": [ "line1", "city", "state", "postal_code" ], "title": "Address", "type": "object" }, "CaptureItemDetails": { "properties": { "item_id": { "description": "ID that uniquely identifies the item within the Payment; optionally specified when creating the payment and retrievable from payment session status or list payment sessions.", "title": "Item Id", "type": "string" }, "quantity": { "description": "The quantity to capture for this order_item, up to the quantity_capturable for the item, retrievable from payment session status or list payment sessions.", "title": "Quantity", "type": "integer" }, "total": { "description": "The total amount in cents to capture for this order_item, up to the total_capturable for the item, retrievable from payment session status or list payment sessions.", "title": "Total", "type": "integer" } }, "required": [ "item_id", "quantity", "total" ], "title": "CaptureItemDetails", "type": "object" }, "CaptureWebhookPayload": { "properties": { "capture_amount": { "description": "The amount captured in cents", "title": "Capture Amount", "type": "integer" }, "captured_at": { "description": "ISO-8601 timestamp of when the capture occurred", "title": "Captured At", "type": "string" } }, "required": [ "captured_at", "capture_amount" ], "title": "CaptureWebhookPayload", "type": "object" }, "CatalogItemEligibility": { "description": "HSA/FSA eligibility status for catalog items.", "enum": [ "eligible", "eligible_with_lmn", "ineligible" ], "title": "CatalogItemEligibility", "type": "string" }, "CreateItemRequest": { "properties": { "description": { "description": "The description of the item.", "title": "Description", "type": "string" }, "gtin": { "description": "The GTIN of the catalog item.", "title": "Gtin", "type": "string" }, "image_urls": { "description": "An array of image URLs of the item.", "items": { "type": "string" }, "maxItems": 10, "minItems": 1, "title": "Image Urls", "type": "array" }, "metadata": { "description": "Optional metadata string for the catalog item.", "title": "Metadata", "type": "string" }, "name": { "description": "The name of the catalog item.", "title": "Name", "type": "string" }, "product_id": { "description": "The product ID of the product which this catalog item is a variant of.", "title": "Product Id", "type": "string" }, "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" }, "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": "Allows the endpoint to be called multiple times, and must be unique to the checkout session.", "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/truemed__integrations__one_time_payments__types__PaymentSessionOrderItem__1" }, "title": "Order Items", "type": "array" }, "payment_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ID returned by Truemed on initial recurring charges (when tokenize=True).", "title": "Payment Token" }, "shipping_address": { "anyOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "null" } ], "description": "The shipping address for the payment session." }, "shipping_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The first and last name of the person for shipping (used for better fraud detection).", "title": "Shipping Name" }, "success_url": { "description": "Where to redirect the user to after Truemed successfully processes a payment.", "maxLength": 4096, "title": "Success Url", "type": "string" }, "survey_config": { "anyOf": [ { "$ref": "#/components/schemas/SurveyConfig" }, { "type": "null" } ], "description": "Allows the partner to customize the health survey." }, "tokenize": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": false, "description": "True or False - set to True to enable subsequent charges.", "title": "Tokenize" }, "total_amount": { "description": "The total amount in cents to charge the user, inclusive of discounts, shipping, taxes, and other fees being collected by the partner.", "title": "Total Amount", "type": "integer" }, "use_iframe": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": false, "description": "Optional query parameter that can be used to modify the response's redirect_url so it can be used and communicated with in an iframe.", "title": "Use Iframe" } }, "required": [ "total_amount", "order_items", "success_url", "failure_url", "idempotency_key", "customer_name", "customer_email", "amount_details" ], "title": "CreatePaymentSessionRequest", "type": "object" }, "CreatePaymentSessionResponse": { "properties": { "authorization_expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "The latest UTC time at which the authorization is valid for capture. Null until the session has an authorized transaction. When the transaction has multiple active payments (e.g. HSA + credit), this is the earliest expiration across them.", "title": "Authorization Expires At" }, "id": { "description": "The unique ID for this checkout session.", "title": "Id", "type": "string" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional message for the response.", "title": "Message" }, "next_action": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The next action required for the payment.", "title": "Next Action" }, "payment_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The payment token for recurring payments.", "title": "Payment Token" }, "redirect_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The URL that the partner should redirect the customer to.", "title": "Redirect Url" } }, "required": [ "id" ], "title": "CreatePaymentSessionResponse", "type": "object" }, "CreatePaymentTokenRequest": { "properties": { "customer_email": { "description": "The customer's email", "title": "Customer Email", "type": "string" }, "customer_name": { "description": "The customer's full name", "title": "Customer Name", "type": "string" }, "customer_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Set this to pre-fill the answer to the State of Residence question in the health survey. The 2-letter ISO 3166-2:US code for a region, without the US- prefix", "examples": [ "AZ", "CO", "TX" ], "title": "Customer State" }, "failure_url": { "description": "Where Truemed should redirect the customer if they decide to cancel the checkout", "title": "Failure Url", "type": "string" }, "idempotency_key": { "description": "A unique ID that allows safely retrying the request without performing the same operation twice", "title": "Idempotency Key", "type": "string" }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A JSON string containing any custom key-value pairs. This string will be returned in the payment_session_complete webhook if provided", "title": "Metadata" }, "order_items": { "description": "The initial list of items for this subscription", "items": { "$ref": "#/components/schemas/PaymentTokenOrderItemSku" }, "minItems": 1, "title": "Order Items", "type": "array" }, "success_url": { "description": "Where Truemed should redirect the customer after successfully completing checkout", "title": "Success Url", "type": "string" }, "use_iframe": { "default": false, "description": "Set to true to allow the Truemed checkout flow to be surfaced via an iframe", "title": "Use Iframe", "type": "boolean" } }, "required": [ "idempotency_key", "success_url", "failure_url", "order_items", "customer_email", "customer_name" ], "title": "CreatePaymentTokenRequest", "type": "object" }, "CreatePaymentTokenResponse": { "properties": { "provision_token_request_id": { "description": "A UUID that represents this creation request", "title": "Provision Token Request Id", "type": "string" }, "redirect_url": { "description": "Contains a URI through which the customer can complete the payment token provisioning", "title": "Redirect Url", "type": "string" } }, "required": [ "provision_token_request_id", "redirect_url" ], "title": "CreatePaymentTokenResponse", "type": "object" }, "CreateRefundRequest": { "properties": { "amount": { "description": "The amount you wish to refund in cents. Cannot be greater than the total_amount originally charged.", "title": "Amount", "type": "integer" }, "idempotency_key": { "description": "Allows the endpoint to be called multiple times, and must be unique to the refund request.", "title": "Idempotency Key", "type": "string" }, "item_details": { "description": "A list of items to be refunded.", "items": { "$ref": "#/components/schemas/RefundItemDetails" }, "title": "Item Details", "type": "array" }, "payment_id": { "description": "The id returned to the partner by Truemed in response to a `create_payment_session` request.", "title": "Payment Id", "type": "string" }, "reason": { "$ref": "#/components/schemas/RefundReasons", "description": "Why you are initiating this refund request: customer_request - the customer requested a refund; fraudulent - the payment was fraudulent; duplicate_payment - the user checked out with HSA/FSA multiple times for one purchase." } }, "required": [ "payment_id", "amount", "idempotency_key", "reason", "item_details" ], "title": "CreateRefundRequest", "type": "object" }, "CreateRefundResponse": { "properties": { "refund_id": { "description": "The unique ID for this refund. Multiple refunds can be associated with a single payment, in the case of partial refunds.", "title": "Refund Id", "type": "string" } }, "required": [ "refund_id" ], "title": "CreateRefundResponse", "type": "object" }, "CustomerFacingTransactionStatus": { "enum": [ "Incomplete", "Canceled", "Rejected", "Processing", "Authorized", "Voided", "Expired", "Partially Captured", "Captured", "Partially Refunded", "Refunded", "PartiallyDisputed", "Disputed" ], "title": "CustomerFacingTransactionStatus", "type": "string" }, "DetailItemRequest": { "properties": { "sku": { "description": "The SKU of the catalog item to retrieve.", "title": "Sku", "type": "string" } }, "required": [ "sku" ], "title": "DetailItemRequest", "type": "object" }, "DetailItemResponse": { "properties": { "object": { "$ref": "#/components/schemas/truemed__main__services__catalog_items__types__CatalogItemDetail__1", "description": "The catalog item detail." } }, "required": [ "object" ], "title": "DetailItemResponse", "type": "object" }, "DisputeDetails": { "properties": { "amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": 0, "description": "The original disputed amount in cents. Always reflects what the dispute was filed for, independent of resolution. For Won disputes this stays non-zero even though `withdrawn_amount` becomes 0 after reinstatement, so consumers can show 'this dispute was for $X' regardless of outcome.", "title": "Amount" }, "description": { "description": "Further details about the state of a dispute.", "title": "Description", "type": "string" }, "dispute_id": { "description": "Unique ID of the dispute.", "title": "Dispute Id", "type": "string" }, "disputed_on": { "description": "The date that the dispute was created.", "format": "date-time", "title": "Disputed On", "type": "string" }, "reason": { "$ref": "#/components/schemas/DisputeReason", "description": "Specific reason the dispute was created." }, "resolved_on": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "The date that the dispute was resolved.", "title": "Resolved On" }, "status": { "$ref": "#/components/schemas/DisputeStatusPublic", "description": "Status of this dispute." }, "withdrawn_amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": 0, "description": "The total amount of money withdrawn based on the ruling.", "title": "Withdrawn Amount" } }, "required": [ "dispute_id", "status", "reason", "disputed_on", "description" ], "title": "DisputeDetails", "type": "object" }, "DisputeReason": { "description": "The reason for the dispute.\n\nhttps://docs.stripe.com/api/disputes/object#dispute_object-reason", "enum": [ "bank_cannot_process", "check_returned", "credit_not_processed", "customer_initiated", "debit_not_authorized", "duplicate", "fraudulent", "general", "incorrect_account_details", "insufficient_funds", "product_not_received", "product_unacceptable", "subscription_canceled", "unrecognized" ], "title": "DisputeReason", "type": "string" }, "DisputeStatusPublic": { "description": "The public facing status for the dispute.", "enum": [ "Lost", "Won", "Closed", "Investigating", "Under Review", "Unknown" ], "title": "DisputeStatusPublic", "type": "string" }, "ErrorResponse": { "properties": { "error": { "$ref": "#/components/schemas/ErrorType" }, "message": { "title": "Message", "type": "string" } }, "required": [ "error", "message" ], "title": "ErrorResponse", "type": "object" }, "ErrorType": { "enum": [ "BadRequest", "Unauthorized", "Forbidden", "NotFound", "MethodNotAllowed", "Conflict", "TooManyRequests", "ServerError", "BadGateway", "ServiceUnavailable", "GatewayTimeout", "NotImplemented", "RequestValueError", "ValidationError", "TokenExpired", "InvalidToken", "InvalidCredentials", "StripeInvalidRequestError", "StripeRateLimitError", "StripeError", "PaymentMethodNotFoundError", "CustomerIdNotFoundError", "InvalidPaymentId", "IneligibleItemAdded", "TotalAmountInvalid", "FeatureNotEnabled" ], "title": "ErrorType", "type": "string" }, "NextActionType": { "enum": [ "UpdatePaymentMethod", "TakeHealthSurvey", "None" ], "title": "NextActionType", "type": "string" }, "NextBillInfo": { "properties": { "date": { "format": "date", "title": "Date", "type": "string" }, "total_amount": { "title": "Total Amount", "type": "integer" } }, "required": [ "total_amount", "date" ], "title": "NextBillInfo", "type": "object" }, "PaginationBody": { "properties": { "count": { "description": "The total number of items associated with the provided API key.", "title": "Count", "type": "integer" }, "current_page": { "description": "The page requested. If none was provided, this will default to 1.", "title": "Current Page", "type": "integer" }, "last_page": { "description": "The last page. You can iterate through pages by providing integers up to last_page in the page parameter.", "title": "Last Page", "type": "integer" }, "page_size": { "description": "The number of items per page, which is at most 30.", "title": "Page Size", "type": "integer" } }, "required": [ "current_page", "page_size", "count", "last_page" ], "title": "PaginationBody", "type": "object" }, "PaymentMethodResponse": { "properties": { "expiration": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A MM/YYYY formatted string specifying the month and year the card on file will expire.", "title": "Expiration" }, "last4": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The last 4 digits of the CC number associated with this payment method.", "title": "Last4" }, "payment_method_updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 formatted DateTime object that represents the date and time the `payment_method` was last updated by the customer.", "title": "Payment Method Updated At" } }, "title": "PaymentMethodResponse", "type": "object" }, "PaymentSessionAmountDetail": { "properties": { "amount": { "description": "The amount in cents for this discount or charge.", "title": "Amount", "type": "integer" }, "name": { "description": "The name or description of the discount or charge.", "title": "Name", "type": "string" } }, "required": [ "name", "amount" ], "title": "PaymentSessionAmountDetail", "type": "object" }, "PaymentSessionAmountDetails": { "properties": { "additional_charges_details": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PaymentSessionAmountDetail" }, "type": "array" }, { "type": "null" } ], "description": "An array of individual additional charge line items with names and amounts.", "title": "Additional Charges Details" }, "discounts_details": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PaymentSessionAmountDetail" }, "type": "array" }, { "type": "null" } ], "description": "An array of individual discount line items with names and amounts.", "title": "Discounts Details" }, "total_additional_charges": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The total amount of additional charges (e.g., shipping, tax), in cents.", "title": "Total Additional Charges" }, "total_discounts": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The total amount of discounts applied, in cents.", "title": "Total Discounts" } }, "title": "PaymentSessionAmountDetails", "type": "object" }, "PaymentSessionCancelResponse": { "properties": { "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional field echoed back if present in the call to create_payment_session.", "title": "Metadata" }, "order_items": { "description": "A list of order items.", "items": { "$ref": "#/components/schemas/truemed__integrations__one_time_payments__types__PaymentSessionOrderItem__2" }, "title": "Order Items", "type": "array" }, "status": { "$ref": "#/components/schemas/PaymentSessionStatus", "description": "The status field of the payment_session. When the payment session is pending, it will be marked as `canceled`." } }, "required": [ "status", "order_items" ], "title": "PaymentSessionCancelResponse", "type": "object" }, "PaymentSessionCaptureRequest": { "properties": { "final": { "default": true, "description": "Whether this is the final capture for the payment session. Set to false to allow additional captures up to the authorized amount.", "title": "Final", "type": "boolean" }, "idempotency_key": { "description": "Allows the endpoint to be called multiple times. It must be unique to the capture session.", "title": "Idempotency Key", "type": "string" }, "item_details": { "description": "A list of items being captured in the capture request.", "items": { "$ref": "#/components/schemas/CaptureItemDetails" }, "title": "Item Details", "type": "array" }, "total_amount": { "description": "The total amount in cents to charge the user, inclusive of taxes and fees being collected by the partner. Must be less than or equal to the total_amount passed in when creating the payment session. If an amount more than the initial authorization should be captured, void the initial auth hold and create a new one.", "title": "Total Amount", "type": "integer" } }, "required": [ "total_amount", "idempotency_key", "item_details" ], "title": "PaymentSessionCaptureRequest", "type": "object" }, "PaymentSessionCaptureResponse": { "properties": { "id": { "description": "The unique ID for this session capture. This same ID will be returned if the endpoint is called with the same idempotency_key. Associate this id with your internal representation of a checkout session, if applicable.", "title": "Id", "type": "string" } }, "required": [ "id" ], "title": "PaymentSessionCaptureResponse", "type": "object" }, "PaymentSessionDetailResponse": { "properties": { "amount_details": { "anyOf": [ { "$ref": "#/components/schemas/PaymentSessionAmountDetails" }, { "type": "null" } ], "description": "Detailed breakdown of the payment amount." }, "authorization_expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "The latest UTC time at which the authorization is valid for capture. Null until the session has an authorized transaction. When the transaction has multiple active payments (e.g. HSA + credit), this is the earliest expiration across them.", "title": "Authorization Expires At" }, "authorize_amount": { "description": "The amount the user's card will be authorized for. In the case of `kind=one_time_payment`, this will always the same same as `capture_amount`.", "title": "Authorize Amount", "type": "integer" }, "capture_amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The amount of funds actually captured.", "title": "Capture Amount" }, "created_at": { "description": "The date and time when the payment session was created.", "format": "date-time", "title": "Created At", "type": "string" }, "customer_business_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The business id of the customer.", "title": "Customer Business Id" }, "disputes": { "description": "A list of dispute objects that will be empty if the payment has no associated disputes.", "items": { "$ref": "#/components/schemas/DisputeDetails" }, "title": "Disputes", "type": "array" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The email of the user who executed the payment.", "title": "Email" }, "is_testing": { "description": "Whether the payment was executed in a test environment.", "title": "Is Testing", "type": "boolean" }, "kind": { "$ref": "#/components/schemas/PurchaseKind", "description": "The type of payment session." }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional field echoed back if present in the call to `create_payment_session`.", "title": "Metadata" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The name of the user who executed the payment.", "title": "Name" }, "order_items": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PaymentSessionOrderItemDetails" }, "type": "array" }, { "items": { "$ref": "#/components/schemas/truemed__integrations__one_time_payments__types__PaymentSessionOrderItem__3" }, "type": "array" } ], "description": "A list of order items.", "title": "Order Items" }, "payment_session_id": { "description": "The id of the payment session.", "title": "Payment Session Id", "type": "string" }, "refunds": { "description": "A list of refund objects that will be empty if the payment has no associated refunds.", "items": { "$ref": "#/components/schemas/RefundDetails" }, "title": "Refunds", "type": "array" }, "status": { "$ref": "#/components/schemas/PaymentSessionStatus", "description": "The status of the initial payment." }, "status_summary": { "$ref": "#/components/schemas/CustomerFacingTransactionStatus", "description": "A summary of the overall payment session." }, "stripe_payment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The Stripe payment id.", "title": "Stripe Payment Id" }, "total_amount": { "description": "The total amount captured, in cents.", "title": "Total Amount", "type": "integer" }, "truemed_fee": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" }, { "type": "null" } ], "description": "The fee that Truemed received from the payment session. Will return 0 until the session has been captured.", "title": "Truemed Fee" } }, "required": [ "payment_session_id", "status", "total_amount", "authorize_amount", "refunds", "disputes", "status_summary", "is_testing", "created_at", "order_items", "kind" ], "title": "PaymentSessionDetailResponse", "type": "object" }, "PaymentSessionDetails": { "properties": { "amount_details": { "anyOf": [ { "$ref": "#/components/schemas/PaymentSessionAmountDetails" }, { "type": "null" } ], "description": "Detailed breakdown of the payment amount including discounts and charges." }, "authorize_amount": { "description": "The total_amount passed into `create_payment_session`.", "title": "Authorize Amount", "type": "integer" }, "authorized_on": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "The date the payment was authorized in ISO 8601 format. Example: \"2024-06-13T16:03:07.473Z\". For kind: one_time_payment, this will be the same as captured_on.", "title": "Authorized On" }, "capture_amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "For one time payments, same as authorize_amount. Otherwise, the captured amount.", "title": "Capture Amount" }, "captured_on": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "The date the payment was captured in ISO 8601 format. Example: \"2024-06-13T16:03:07.473Z\".", "title": "Captured On" }, "created_at": { "description": "The date the payment session was created in ISO 8601 format. Example: \"2024-06-13T16:03:07.473Z\".", "format": "date-time", "title": "Created At", "type": "string" }, "disputes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/DisputeDetails" }, "type": "array" }, { "type": "null" } ], "description": "An array of dispute objects. Included if include_disputes is True (by default).", "title": "Disputes" }, "id": { "description": "The UUID returned by `create_payment_session`.", "title": "Id", "type": "string" }, "idempotency_key": { "description": "The idempotency key passed into create_payment_session.", "title": "Idempotency Key", "type": "string" }, "is_testing": { "description": "The testing flag.", "title": "Is Testing", "type": "boolean" }, "kind": { "$ref": "#/components/schemas/PurchaseKind", "description": "The payment kind, either one_time_payment or authorization." }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The raw `metadata` field passed into `create_payment_session`.", "title": "Metadata" }, "order_items": { "anyOf": [ { "items": { "$ref": "#/components/schemas/truemed__integrations__one_time_payments__types__PaymentSessionOrderItem__4" }, "type": "array" }, { "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": { "$ref": "#/components/schemas/PaginationBody", "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" }, "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_capturable": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The total amount in cents that can still be captured for this item.", "title": "Total Capturable" }, "total_refundable": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The total amount in cents that can be refunded for this item.", "title": "Total Refundable" } }, "required": [ "name", "quantity", "price", "item_id", "quantity_capturable", "total_capturable", "quantity_refundable", "total_refundable", "sku" ], "title": "PaymentSessionOrderItemDetails", "type": "object" }, "PaymentSessionStatus": { "enum": [ "pending", "canceled", "processing", "rejected", "authorized", "authorization_expired", "authorization_voided", "partially_captured", "captured" ], "title": "PaymentSessionStatus", "type": "string" }, "PaymentSessionVoidRequest": { "properties": { "idempotency_key": { "description": "Allows the endpoint to be called multiple times. It must be unique to the void session call.", "title": "Idempotency Key", "type": "string" } }, "required": [ "idempotency_key" ], "title": "PaymentSessionVoidRequest", "type": "object" }, "PaymentSessionVoidResponse": { "properties": { "id": { "description": "The unique ID for this void session. This same ID will be returned if the endpoint is called with the same idempotency_key. Associate this id with your internal representation of a checkout session, if applicable.", "title": "Id", "type": "string" } }, "required": [ "id" ], "title": "PaymentSessionVoidResponse", "type": "object" }, "PaymentTokenDeleteResponse": { "properties": {}, "title": "PaymentTokenDeleteResponse", "type": "object" }, "PaymentTokenListResponse": { "properties": { "pagination": { "$ref": "#/components/schemas/PaginationBody", "description": "A pagination object with information about the current page, page size, total count, and last page." }, "payment_tokens": { "description": "An array of `payment_token` objects.", "items": { "$ref": "#/components/schemas/PaymentTokenResponse" }, "title": "Payment Tokens", "type": "array" } }, "required": [ "payment_tokens" ], "title": "PaymentTokenListResponse", "type": "object" }, "PaymentTokenOrderItemSku": { "properties": { "sku": { "description": "The SKU of the item as configured in your catalog", "title": "Sku", "type": "string" } }, "required": [ "sku" ], "title": "PaymentTokenOrderItemSku", "type": "object" }, "PaymentTokenProvisionRequestDetailResponse": { "properties": { "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The metadata string you provided as part of the create_payment_token request for the ProvisionTokenRequest. Will be null if no metadata was provided", "title": "Metadata" }, "payment_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The PaymentToken created as part of create_payment_token for the ProvisionTokenRequest. Will be null if the PaymentToken has not been provisioned yet", "title": "Payment Token" } }, "required": [ "payment_token", "metadata" ], "title": "PaymentTokenProvisionRequestDetailResponse", "type": "object" }, "PaymentTokenResponse": { "properties": { "created_at": { "description": "ISO 8601 formatted date and time the `payment_token` was created at.", "title": "Created At", "type": "string" }, "customer_email": { "description": "The email address for the customer associated with this `payment_token`.", "title": "Customer Email", "type": "string" }, "customer_name": { "description": "The first and last name of the customer associated with this `payment_token`.", "title": "Customer Name", "type": "string" }, "lmn_expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 formatted date when the earliest LMN associated with this payment token expires. Null if no verified LMN exists. Partners should prompt users to re-qualify before this date.", "title": "Lmn Expires At" }, "payment_methods": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PaymentMethodResponse" }, "type": "array" }, { "type": "null" } ], "description": "An optional array of payment_method objects.", "title": "Payment Methods" }, "payment_token": { "description": "The payment token identifier.", "title": "Payment Token", "type": "string" } }, "required": [ "payment_token", "customer_email", "customer_name", "created_at" ], "title": "PaymentTokenResponse", "type": "object" }, "PaymentTokenUpdatedWebhookPayload": { "properties": { "failed_payment_session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional payment session ID that failed, triggering token update", "title": "Failed Payment Session Id" }, "lmn_expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional ISO-8601 timestamp of when the LMN expires", "title": "Lmn Expires At" }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional metadata associated with the payment token", "title": "Metadata" }, "payment_methods": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PaymentMethodResponse" }, "type": "array" }, { "type": "null" } ], "description": "Optional list of available payment methods for the token", "title": "Payment Methods" }, "payment_session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional payment session ID associated with the token update", "title": "Payment Session Id" }, "payment_token": { "description": "The payment token identifier", "title": "Payment Token", "type": "string" }, "provision_token_request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional provision token request ID", "title": "Provision Token Request Id" } }, "required": [ "payment_token" ], "title": "PaymentTokenUpdatedWebhookPayload", "type": "object" }, "ProductCatalogItemEligibilityUpdatedWebhookData": { "description": "Data field for product catalog item eligibility webhook.", "properties": { "object": { "$ref": "#/components/schemas/truemed__main__services__catalog_items__types__CatalogItemDetail__2", "description": "The catalog item with updated eligibility information." } }, "required": [ "object" ], "title": "ProductCatalogItemEligibilityUpdatedWebhookData", "type": "object" }, "ProductCatalogItemEligibilityUpdatedWebhookPayload": { "properties": { "data": { "$ref": "#/components/schemas/ProductCatalogItemEligibilityUpdatedWebhookData", "description": "The webhook payload data." }, "event_type": { "description": "The type of event that triggered this webhook (e.g., 'product_catalog.item.eligibility_updated').", "title": "Event Type", "type": "string" }, "timestamp": { "description": "ISO-8601 timestamp of when the event occurred.", "title": "Timestamp", "type": "string" } }, "required": [ "event_type", "timestamp", "data" ], "title": "ProductCatalogItemEligibilityUpdatedWebhookPayload", "type": "object" }, "PurchaseKind": { "description": "Enum for the kind of payment\n\nThis determines how the payment will be captured\n- OneTimePayment means captured by Truemed automatically\n- Authorization means manually captured by the requesting merchant", "enum": [ "one_time_payment", "authorization" ], "title": "PurchaseKind", "type": "string" }, "QualificationSessionListResponse": { "properties": { "pagination": { "$ref": "#/components/schemas/PaginationBody", "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" }, "QualificationSessionResponse": { "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The email address of the consumer who completed the qualification session.", "title": "Email" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "The datetime at which the Letter-of-Medical-Necessity expires.", "title": "Expires At" }, "qualification_session_id": { "description": "The id of the payment session.", "title": "Qualification Session Id", "type": "string" }, "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 initial payment." }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The user_id provided in the qualification session redirect URL param.", "title": "User Id" } }, "required": [ "qualification_session_id", "status" ], "title": "QualificationSessionResponse", "type": "object" }, "QualificationSessionStatusSummary": { "description": "This enum is used to summarize the status of the qualification session.\n\nIt abstracts the internal nuances of the qualification session and LMN verification status. It is\nto be used by merchants external to Truemed.", "enum": [ "pending", "processing", "approved", "rejected" ], "title": "QualificationSessionStatusSummary", "type": "string" }, "QualificationSessionStatusUpdatedWebhookPayload": { "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The email address of the consumer who completed the qualification session.", "title": "Email" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "An optional datetime at which the Letter-of-Medical-Necessity expires.", "title": "Expires At" }, "qualification_session_id": { "description": "The qualification_session_id returned by Truemed to the partner in 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" }, "RefundDetails": { "properties": { "amount": { "description": "The amount refunded, in cents.", "title": "Amount", "type": "integer" }, "id": { "description": "The UUID of the refund.", "title": "Id", "type": "string" }, "refunded_on": { "description": "The date the refund was made in ISO 8601 format. Example: \"2024-06-13T16:03:08.386Z\"", "format": "date-time", "title": "Refunded On", "type": "string" }, "truemed_fee_returned": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": 0, "description": "The amount of Truemed fees returned with this refund, in cents.", "title": "Truemed Fee Returned" } }, "required": [ "id", "amount", "refunded_on" ], "title": "RefundDetails", "type": "object" }, "RefundItemDetails": { "properties": { "item_id": { "description": "ID that uniquely identifies the item within the Payment; optionally specified when creating the payment and retrievable from payment session status or list payment sessions.", "title": "Item Id", "type": "string" }, "quantity": { "description": "The quantity of this particular item to being refunded of this item, up to `quantity_refundable` from payment session status or list payment sessions.", "title": "Quantity", "type": "integer" }, "total": { "description": "The total amount in cents of this particular item to being refunded of this item, up to `total_refundable` from payment session status or list payment sessions.", "title": "Total", "type": "integer" } }, "required": [ "item_id", "quantity", "total" ], "title": "RefundItemDetails", "type": "object" }, "RefundReasons": { "enum": [ "customer_request", "duplicate_payment", "fraudulent" ], "title": "RefundReasons", "type": "string" }, "StatusUpdateWebhookPayload": { "properties": { "authorize_amount": { "description": "The amount the user's card will be authorized for. In the case of `kind=one_time_payment`, this will always be the same as `capture_amount`", "title": "Authorize Amount", "type": "integer" }, "capture_amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The amount of funds actually captured. For payment sessions of `kind=one_time_payment` this field will always be present and will be the same as `authorize_amount`. For payment sessions of `kind=authorization` this field will not be present until the funds have been captured", "title": "Capture Amount" }, "captures": { "description": "List of capture details for the payment session", "items": { "$ref": "#/components/schemas/CaptureWebhookPayload" }, "title": "Captures", "type": "array" }, "created_at": { "description": "ISO-8601 timestamp of when the payment session was created", "title": "Created At", "type": "string" }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional field echoed back if present in the call to create_payment_session", "title": "Metadata" }, "order_items": { "anyOf": [ { "items": { "$ref": "#/components/schemas/truemed__integrations__one_time_payments__types__PaymentSessionOrderItem__3" }, "type": "array" }, { "items": { "$ref": "#/components/schemas/PaymentSessionOrderItemDetails" }, "type": "array" } ], "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)", "title": "Order Items" }, "payment_id": { "description": "The id returned to the partner by Truemed in response to a `create_payment_session` request", "title": "Payment Id", "type": "string" }, "payment_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional string indicating the payment_token used for the payment session. This field will be set only if the partner provided tokenize=True or a payment_token in the create_payment_session request", "title": "Payment Token" }, "status": { "$ref": "#/components/schemas/PaymentSessionStatus", "description": "The status of the payment from Truemed's perspective. Can be: captured, canceled, pending, processing, rejected, authorized, authorization_voided, authorization_expired" } }, "required": [ "payment_id", "status", "authorize_amount", "created_at", "captures", "order_items" ], "title": "StatusUpdateWebhookPayload", "type": "object" }, "SurveyConfig": { "properties": { "hide_back_to_checkout_cta": { "description": "Provide as true to hide the 'Back to checkout' CTA in the survey if the user fails to qualify.", "title": "Hide Back To Checkout Cta", "type": "boolean" } }, "required": [ "hide_back_to_checkout_cta" ], "title": "SurveyConfig", "type": "object" }, "TruemedCheckoutMethodItemInfo": { "properties": { "name": { "description": "The name of the catalog item.", "title": "Name", "type": "string" }, "product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The product ID of the parent product which this catalog item is a variant of.", "title": "Product Id" }, "sku": { "description": "The SKU of the catalog item.", "title": "Sku", "type": "string" } }, "required": [ "sku", "name" ], "title": "TruemedCheckoutMethodItemInfo", "type": "object" }, "TruemedCheckoutMethodRequest": { "properties": { "items": { "description": "The items to check eligibility for.", "items": { "$ref": "#/components/schemas/TruemedCheckoutMethodItemInfo" }, "maxItems": 1000, "minItems": 1, "title": "Items", "type": "array" } }, "required": [ "items" ], "title": "TruemedCheckoutMethodRequest", "type": "object" }, "TruemedCheckoutMethodResponse": { "properties": { "enabled": { "description": "Whether the set of items is enabled for checkout with Truemed.", "title": "Enabled", "type": "boolean" } }, "required": [ "enabled" ], "title": "TruemedCheckoutMethodResponse", "type": "object" }, "UpdateItemRequest": { "properties": { "description": { "description": "The description of the item.", "title": "Description", "type": "string" }, "gtin": { "description": "The GTIN of the catalog item.", "title": "Gtin", "type": "string" }, "image_urls": { "description": "An array of image URLs of the item.", "items": { "type": "string" }, "maxItems": 10, "minItems": 1, "title": "Image Urls", "type": "array" }, "metadata": { "description": "Optional metadata string for the catalog item.", "title": "Metadata", "type": "string" }, "name": { "description": "The name of the catalog item.", "title": "Name", "type": "string" }, "product_id": { "description": "The product ID of the product which this catalog item is a variant of.", "title": "Product Id", "type": "string" }, "sku": { "description": "The SKU of the catalog item.", "title": "Sku", "type": "string" }, "url": { "description": "The display page URL for the item.", "title": "Url", "type": "string" } }, "required": [ "sku", "name", "description", "url", "image_urls" ], "title": "UpdateItemRequest", "type": "object" }, "UpdateItemResponse": { "properties": {}, "title": "UpdateItemResponse", "type": "object" }, "UpdatePaymentTokenRequest": { "properties": { "failure_url": { "description": "Where Truemed should redirect the customer after unsuccessfully completing the next action. In the case of a health survey, this applies to the user clicking the back or cancel buttons on the survey.", "title": "Failure Url", "type": "string" }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Merchants can use this free-form field to store extra information with the payment token", "title": "Metadata" }, "order_items": { "anyOf": [ { "items": { "$ref": "#/components/schemas/UpdatedOrderItemsRequest" }, "type": "array" }, { "type": "null" } ], "description": "Updated list of items for this subscription", "title": "Order Items" }, "renew_eligibility": { "default": false, "description": "Set to true to allow the customer to requalify within 30 days of LMN expiration. Use lmn_expires_at from Retrieve or List Payment Token responses or the Payment Token Updated Webhook payload to identify upcoming expirations. This is helpful to avoid interruptions to ongoing subscriptions.", "title": "Renew Eligibility", "type": "boolean" }, "success_url": { "description": "Where Truemed should redirect the customer after successfully completing the next action", "title": "Success Url", "type": "string" }, "update_card_info": { "default": false, "description": "Set to true to allow the Truemed checkout flow to update the user's card information", "title": "Update Card Info", "type": "boolean" }, "use_iframe": { "default": false, "description": "If true, the customer should be redirected to the `redirect_url` using an iframe.", "title": "Use Iframe", "type": "boolean" } }, "required": [ "success_url", "failure_url" ], "title": "UpdatePaymentTokenRequest", "type": "object" }, "UpdatePaymentTokenResponse": { "properties": { "next_action": { "$ref": "#/components/schemas/NextActionType", "description": "Next action required for this payment token, if any." }, "redirect_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A URI through which the customer can correct the payment_token.", "title": "Redirect Url" } }, "required": [ "next_action", "redirect_url" ], "title": "UpdatePaymentTokenResponse", "type": "object" }, "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" }, "truemed__integrations__one_time_payments__types__PaymentSessionOrderItem__1": { "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" }, "truemed__integrations__one_time_payments__types__PaymentSessionOrderItem__2": { "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" }, "truemed__integrations__one_time_payments__types__PaymentSessionOrderItem__3": { "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": { "anyOf": [ { "$ref": "#/components/schemas/PaymentSessionAmountDetails" }, { "type": "null" } ], "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": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The SKU (Stock Keeping Unit) for this item.", "title": "Sku" } }, "required": [ "name", "quantity" ], "title": "PaymentSessionOrderItem", "type": "object" }, "truemed__integrations__one_time_payments__types__PaymentSessionOrderItem__4": { "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" }, "truemed__main__services__catalog_items__types__CatalogItemDetail__1": { "properties": { "created_at": { "description": "The date and time the catalog item was created.", "format": "date-time", "title": "Created At", "type": "string" }, "description": { "description": "An optional description of the catalog item.", "title": "Description", "type": "string" }, "eligibility": { "anyOf": [ { "$ref": "#/components/schemas/CatalogItemEligibility" }, { "type": "null" } ], "description": "HSA/FSA eligibility status for the catalog item." }, "gtin": { "description": "The GTIN of the catalog item.", "title": "Gtin", "type": "string" }, "image_urls": { "description": "Optional array of image URLs associated with the catalog item.", "items": { "type": "string" }, "title": "Image Urls", "type": "array" }, "metadata": { "description": "Optional metadata string for the catalog item.", "title": "Metadata", "type": "string" }, "name": { "description": "The name of the catalog item.", "title": "Name", "type": "string" }, "product_id": { "description": "The product ID of the product which this catalog item is a variant of.", "title": "Product Id", "type": "string" }, "reviewed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "The date and time the catalog item was last reviewed.", "title": "Reviewed At" }, "sku": { "description": "The SKU of the catalog item.", "title": "Sku", "type": "string" }, "url": { "description": "An optional display page URL for the catalog item.", "title": "Url", "type": "string" } }, "required": [ "sku", "name", "created_at" ], "title": "CatalogItemDetail", "type": "object" }, "truemed__main__services__catalog_items__types__CatalogItemDetail__2": { "description": "Catalog item detail response with eligibility information.", "properties": { "created_at": { "description": "The date and time the catalog item was created.", "format": "date-time", "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "An optional description of the catalog item.", "title": "Description" }, "eligibility": { "anyOf": [ { "$ref": "#/components/schemas/CatalogItemEligibility" }, { "type": "null" } ], "description": "HSA/FSA eligibility status for the catalog item." }, "gtin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The GTIN of the catalog item.", "title": "Gtin" }, "image_urls": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Optional array of image URLs associated with the catalog item.", "title": "Image Urls" }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional metadata string for the catalog item.", "title": "Metadata" }, "name": { "description": "The name of the catalog item.", "title": "Name", "type": "string" }, "product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The product ID of the product which this catalog item is a variant of.", "title": "Product Id" }, "reviewed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "The date and time the catalog item was last reviewed.", "title": "Reviewed At" }, "sku": { "description": "The SKU of the catalog item.", "title": "Sku", "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "An optional display page URL for the catalog item.", "title": "Url" } }, "required": [ "sku", "name", "created_at" ], "title": "CatalogItemDetail", "type": "object" } }, "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" } } } }