> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://docs-dev.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://docs-dev.truemed.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-dev.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://docs-dev.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, in the order the captures were made.
- `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
- `multicapture_available` (boolean, optional, nullable) — Whether this session can be captured more than once. Truemed requests multi-capture for sessions created with `request_multicapture: true`, and the card network confirms it for each transaction; this is `true` only when every card the customer paid with supports it. When it's `false`, a `final: false` capture is rejected. Present once authorized, for sessions created with `request_multicapture: true`.
- `order_level_charges_remaining` (integer, optional, nullable) — Order-level shipping, tax and fees that no capture has collected yet, in cents. 0 once the session closes; refunds don't add back to it. Multi-capture sessions only, once authorized.
- `order_level_discounts_remaining` (integer, optional, nullable) — Order-level discounts that no capture has applied yet, in cents. 0 once the session closes; refunds don't add back to it. Multi-capture sessions only, once authorized.
- `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`.
- `amount_details` (PaymentSessionAmountDetails, optional, nullable) — The order-level charges and discounts this capture declared, as sent: empty when only its items declared, absent when nothing was declared.
- `item_details` (list of CapturedItemDetails, optional, nullable) — The per-item breakdown of this capture (empty for amount-only captures). Multi-capture sessions only.
- `order_level_captured` (integer, optional, nullable) — The order-level money this capture collected beyond its items' totals, in cents: order-level charges minus order-level discounts. `item_details[].total` plus this is `capture_amount`. Multi-capture sessions only.

### 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.
- `max_capture_amount` (integer, optional, nullable) — This item's allocated share of the session, in cents: its `total` plus `order_level_charges_share` minus `order_level_discounts_share`. Not a hard limit: an inferred capture may also collect order-level money the session still owes. Multi-capture sessions only, once authorized.
- `max_capture_amount_remaining` (integer, optional, nullable) — What's left of `max_capture_amount` after earlier captures of this item, in cents. 0 once all its units are captured or the session closes, and while the session awaits LMN verification.
- `order_level_charges_share` (integer, optional, nullable) — This item's share of the session's order-level shipping, tax and fees, in cents.
- `order_level_discounts_share` (integer, optional, nullable) — This item's share of the session's order-level discounts, in cents. A discount a capture declares on an item moves to that item.
- `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.

### CapturedItemDetails

- `item_id` (string, required) — 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. On a multi-capture session, list each item once per request.
- `quantity` (integer, required) — The units of this item the capture recorded.
- `total` (integer, required) — What the capture collected for these units, in cents, including the order-level money declared on the item (`order_level_captured`).
- `amount_details` (PaymentSessionAmountDetails, optional, nullable) — The charges and discounts the capture declared on this item, as sent: empty when it declared none of its own, absent when the capture was inferred.
- `order_level_captured` (integer, optional, nullable) — The order-level money this capture declared on this item beyond what the item was created for, in cents, included in `total`. Refundable with the item.

### 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.