> 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 Capture Failed Webhook

POST 

Truemed sends this webhook when a payment session's capture permanently fails after all
automatic retries have been exhausted, meaning the order will not be paid unless you take action.

Terminal capture failures are exceedingly rare — the vast majority of integrations will never
receive this event and do not need to build special handling for it. Subscribe only if you want to
be notified in the uncommon case that a payment session can never be captured.

This is distinct from the `payment_session_complete` webhook: a capture failure is terminal, so you
will not receive a later `captured` status for the same session. Do not fulfill the order when you
receive this event.

If part of a split payment was collected before the capture failed, `amount_collected` reports the
amount already charged to the customer; it is null when nothing was collected.

**Authentication**: 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:

- `payment_session_id` - the payment session whose capture failed.
- `failed_at` - when the capture was determined to have permanently failed.
- `failure_details` - a generic message indicating the capture could not be completed.
- `amount_collected` - funds already collected on a partially-charged split payment; null otherwise.

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

## Request

### Payload

- `failed_at` (datetime, required) — When the capture was determined to have permanently failed.
- `payment_session_id` (string, required) — The payment session whose capture permanently failed.
- `amount_collected` (integer, optional, nullable) — The amount of funds already collected on the failed capture. Set when part of a split payment succeeded before the capture failed; null otherwise.
- `failure_details` (string, optional, nullable) — A generic message indicating the capture could not be completed.