> 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 lifecycle

> Every payment session status, what it means, and what to do next.

A payment session moves through statuses as the customer completes checkout, Truemed reviews the
payment, and funds are captured, rejected, authorized, voided, or refunded.

Most [immediate-capture](/guides/overview/glossary#immediate-capture) integrations only need to
handle `processing`, `captured`, and `rejected`. [Manual capture](/guides/overview/glossary#manual-capture)
integrations also need `authorized`, `authorization_voided`, and `authorization_expired`.

## Status reference

| Status                  | What it means                                                                                                            | What to do                                                               |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| `pending`               | The payment session exists, but the customer has not completed checkout.                                                 | Wait for the customer to complete the hosted flow.                       |
| `canceled`              | The payment session was canceled before payment information was entered.                                                 | Keep the order unpaid or let the customer choose another payment method. |
| `processing`            | The customer entered payment details and Truemed is reviewing the payment.                                               | Show an "order placed" confirmation. Do not fulfill yet.                 |
| `authorized`            | An authorization hold was placed for a [manual capture](/guides/overview/glossary#manual-capture) payment.               | Capture or void the payment later.                                       |
| `authorization_voided`  | The authorization hold was voided.                                                                                       | Do not fulfill unless the order was paid another way.                    |
| `authorization_expired` | A capture was attempted, but the authorization hold could no longer be re-secured on the customer's card, so it expired. | Do not fulfill unless the order was paid another way.                    |
| `captured`              | The payment cleared review and funds are secured.                                                                        | Fulfill the order.                                                       |
| `rejected`              | The payment failed review.                                                                                               | Cancel the order and notify the customer.                                |

## Successful immediate-capture flow

```mermaid
sequenceDiagram
    participant User
    participant Merchant
    participant Truemed

    User->>Merchant: Click "Pay with HSA/FSA"
    Merchant->>Truemed: POST /create_payment_session
    Truemed-->>Merchant: redirect_url
    Merchant->>User: Redirect to Truemed
    User->>Truemed: Complete health survey
    User->>Truemed: Enter HSA/FSA card details
    Truemed->>Truemed: Process payment
    Truemed-->>User: Redirect to success_url
    Truemed->>Merchant: payment_session_complete (processing)
    Note over Merchant: Show "order placed" message
    Truemed->>Merchant: payment_session_complete (captured)
    Note over Merchant: Fulfill order
```

## Rejected payment flow

```mermaid
sequenceDiagram
    participant User
    participant Merchant
    participant Truemed

    User->>Merchant: Click "Pay with HSA/FSA"
    Merchant->>Truemed: POST /create_payment_session
    Truemed-->>Merchant: redirect_url
    Merchant->>User: Redirect to Truemed
    User->>Truemed: Complete health survey
    alt Ineligible or payment failed before completion
        Truemed-->>User: Redirect to failure_url
        User->>Merchant: Return to checkout
    else Payment under review, then rejected
        Truemed-->>User: Redirect to success_url
        Truemed->>Merchant: payment_session_complete (processing)
        Truemed->>Merchant: payment_session_complete (rejected)
        Note over Merchant: Cancel order and notify customer
    end
```

## Manual capture flow

For manual capture, create the payment session with `kind: authorization`. Truemed sends
`status: authorized` when the hold is ready. Capture or void the authorization later through the
payment session APIs.

Read [Manual/Delayed Capture](/guides/setup/api/payment-sessions/manual-delayed-capture) for the full flow.

## Related APIs

| Operation                         | API reference                                                                                                        |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Retrieve the latest session state | [`GET /payments/v1/payment_session/{business_id}`](/api-reference/payment-sessions/retrieve-payment-session)         |
| List payment sessions             | [`GET /payments/v1/payment_sessions`](/api-reference/payment-sessions/list-payment-session)                          |
| Capture an authorization          | [`POST /payments/v1/payment_session/{business_id}/capture`](/api-reference/payment-sessions/capture-payment-session) |
| Void an authorization             | [`POST /payments/v1/payment_session/{business_id}/void`](/api-reference/payment-sessions/void-payment-session)       |