> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://developers.truemed.com/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.truemed.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.truemed.com/_mcp/server.

# Payment Session Complete Webhook

POST 

The partner is required to implement an endpoint that Truemed can send requests to inform
of the checkout status.

We'll call the `payment_session_complete` webhook once each time the `status` of the
`payment_session` changes, including sessions that have been canceled, voided, and captured.
For delayed capture, we'll issue the webhook call for authorization (when the customer first
successfully enters card information), and again after the partner has manually captured funds
via the capture api.

In successful payment cases, we'll first issue a webhook indicating that the `payment_session`
has transition from `pending` to `processing`, after which you can expect a webhook
transitioning from `processing` to `captured` (in the default / immediate capture cases), and
to `authorized` in the case of [Manual/Delayed Capture](/guides/payment-sessions/manual-delayed-capture).

Orders should not be fulfilled until a webhook is received with a status
of `captured`.

**Authentication**: Partners should verify the request comes from Truemed by checking that
the API key is present in the `x-truemed-api-key` HTTP header.

## Request Notes

Headers:

* `x-truemed-api-key` - The partner's API key.

Notable fields:

* `status` - the status of the payment from Truemed's perspective
  * `captured` - payment has completed
  * `canceled` - payment was canceled before the user entered payment information via a call
    to our cancel API.
  * `pending` - payment has not been successfully completed yet.
  * `processing` - the customer has entered their payment information, but it is under review
    by Truemed
    * Any customer facing communication should indicate successful payment at this point,
      such as on the `success_url`.
    * The merchant should not fulfill the order until the Payment Session Webhook indicates
      that the payment has been captured.
  * `rejected` - While in the `processing` state, Truemed reviewed and rejected the payment
    session.
    * The merchant should not fulfill these orders, and should communicate failure to the
      user via email.
  * `authorized` - an auth hold has been placed on the customer's card.
  * `authorization_voided` - the auth hold has been voided via a call to our Void Session api.
  * `authorization_expired` - the auth hold has expired and we were not able to re-auth the
    transaction. This state is only possible after a call to our Manual Capture api, and is
    only set after we attempt a re-auth hold on the existing payment method.
* `capture_amount` **(Optional)** - 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 (via a call to Manual Capture).
* `order_items` - a list of order items, with the following fields per item:
  * `total_refundable` **(Optional)** - If the Payment Session has been captured, this value
    will be the remaining amount refundable for this item. Otherwise it will not be included.
  * `quantity_refundable` **(Optional)** - If the Payment Session has been captured, this
    value will be the remaining quantity refundable for this item. Otherwise it will not be
    included.
  * `total_capturable` **(Optional)** - If the Payment Session is an authorization and is
    currently authorized, this value will be the remaining amount capturable for this item.
    Otherwise it will not be included.
  * `quantity_capturable` **(Optional)** - If the Payment Session is an authorization and is
    currently authorized, this value will be the remaining quantity capturable for this item.
    Otherwise it will not be included.
* `payment_token` **(Optional)** - 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, as outlined in our Subscriptions
  Flow

## Response Body Documentation

### Success Case

HTTP Status: `204`

The partner does not need to include any content in the body

### Failure Case

Truemed will retry the requests to your backend with backoff for up to 7 days

Reference: https://developers.truemed.com/api-reference/payment-sessions/payment-session-completed-webhook

## Request

### Payload

- `authorize_amount` (integer, required) — 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`
- `captures` (list of CaptureWebhookPayload, required) — List of capture details for the payment session
- `created_at` (string, required) — ISO-8601 timestamp of when the payment session was created
- `order_items` (list of PaymentSessionOrderItemDetails, required) — 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)
- `payment_id` (string, required) — The id returned to the partner by Truemed in response to a `create_payment_session` request
- `status` (enum, required) — The status of the payment from Truemed's perspective. Can be: captured, canceled, pending, processing, rejected, authorized, authorization_voided, authorization_expired
  - Allowed values: `pending`, `canceled`, `processing`, `rejected`, `authorized`, `authorization_expired`, `authorization_voided`, `partially_captured`, `captured`
- `capture_amount` (integer, optional, nullable) — 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
- `metadata` (string, optional, nullable) — Optional field echoed back if present in the call to create_payment_session
- `payment_token` (string, optional, nullable) — 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

## Types

### CaptureWebhookPayload

- `capture_amount` (integer, required) — The amount captured in cents
- `captured_at` (string, required) — ISO-8601 timestamp of when the capture occurred
- `id` (string, required) — The stable id of this capture, used to target a refund against it via `capture_id`.

### PaymentSessionOrderItemDetails

- `name` (string, required) — The name of the item.
- `price` (integer, required) — The unit price in cents charged for the item.
- `quantity` (integer, required) — The number of this item in the cart.
- `total` (integer, required) — The post-discount, post-charge line total in cents — `(price × quantity) + total_additional_charges - total_discounts`. Use this when displaying the per-item total or when computing capture `item_details.total` for a fresh capture.
- `amount` (integer, optional, nullable) — The total amount for this line item in cents (quantity × price).
- `amount_details` (PaymentSessionAmountDetails, optional, nullable) — Itemized discounts and charges applied to this specific item.
- `item_id` (string, optional, nullable) — Optional unique identifier for this item provided by the merchant.
- `quantity_capturable` (integer, optional, nullable) — The quantity of this item that can still be captured (for manual capture authorizations).
- `quantity_refundable` (integer, optional, nullable) — The quantity of this item that can be refunded.
- `sku` (string, optional, nullable) — The SKU (Stock Keeping Unit) for this item.
- `total_capturable` (integer, optional, nullable) — The total amount in cents that can still be captured for this item.
- `total_refundable` (integer, optional, nullable) — The total amount in cents that can be refunded for this item. Truemed tracks this per item, so an order-level charge or discount appears in none of them: when the session carried a top-level `amount_details`, the sum of `total_refundable` across items falls below the session's refundable amount.

### PaymentSessionAmountDetails

- `additional_charges_details` (list of PaymentSessionAmountDetail, optional, nullable) — An array of individual additional charge line items with names and amounts.
- `discounts_details` (list of PaymentSessionAmountDetail, optional, nullable) — An array of individual discount line items with names and amounts.
- `total_additional_charges` (integer, optional, nullable) — The total amount of additional charges (e.g., shipping, tax), in cents.
- `total_discounts` (integer, optional, nullable) — The total amount of discounts applied, in cents.

### PaymentSessionAmountDetail

- `amount` (integer, required) — The amount in cents for this discount or charge.
- `name` (string, required) — The name or description of the discount or charge.