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

# Accept your first payment

> The shortest path to a working Truemed payment — create a session, redirect the customer, and fulfill from the webhook.

This guide walks through the shortest path to a working Truemed payment: create a payment session,
redirect the customer, listen for `payment_session_complete`, and fulfill only after the payment is
captured.

## What you need first

| What to build               | API reference                                                                                           |
| --------------------------- | ------------------------------------------------------------------------------------------------------- |
| Create the checkout session | [`POST /payments/v1/create_payment_session`](/api-reference/payment-sessions/create-payment-session)    |
| Redirect the customer       | Use the `redirect_url` returned by `create_payment_session`                                             |
| Receive payment updates     | [`payment_session_complete`](/api-reference/payment-sessions/payment-session-completed-webhook) webhook |
| Fulfill the order           | Act when the webhook sends `status: captured`                                                           |

> **Note**
>
> The `success_url` redirect is for customer-facing confirmation. The webhook is the source of truth
> for fulfillment.

## Base URLs

Use the dev base URL to build and test, then switch to production for live payments.

| Environment | Base API URL                               |
| ----------- | ------------------------------------------ |
| Dev         | `https://dev-api.truemed.com/payments/v1/` |
| Production  | `https://api.truemed.com/payments/v1/`     |

## Create a payment session

Create the session from your server when the customer chooses Truemed at checkout. All amounts are
integers in cents—`12500` is \$125.00.

```bash
curl https://dev-api.truemed.com/payments/v1/create_payment_session \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-truemed-api-key: $TRUEMED_API_KEY" \
  -d '{
    "total_amount": 12500,
    "customer_name": "Alex Smith",
    "customer_email": "alex@example.com",
    "success_url": "https://example.com/checkout/success?payment_session_id={{payment_session_id}}",
    "failure_url": "https://example.com/checkout/failure?payment_session_id={{payment_session_id}}",
    "idempotency_key": "cart_12345",
    "order_items": [
      {
        "name": "Recovery Bundle",
        "quantity": 1,
        "sku": "recovery-bundle",
        "price": 12500,
        "amount_details": {}
      }
    ],
    "amount_details": {}
  }'
```

The response includes the payment session `id` and the hosted Truemed `redirect_url`.

```json
{
  "id": "c51f5d44-9f8d-4e9f-bc5f-929a6f9f2f51",
  "redirect_url": "https://app.truemed.com/..."
}
```

Store the `id` with your internal checkout or order record. This is the value sent back as
`payment_id` in the payment session webhook.

## Redirect the customer

Send the customer to the `redirect_url` from the response. Truemed will guide them through the
health survey and HSA/FSA card entry, then redirect them back to your `success_url` or `failure_url`.

If the customer reaches your `success_url`, show an order-received or pending-confirmation message.
Do not ship, activate access, or otherwise fulfill the order from the redirect alone.

> **Tip**
>
> Want customers to stay on your site instead of redirecting away? The same flow can render inline—see
> [Embedded Checkout (iFrame)](/guides/setup/api/payment-sessions/i-frame-payment-session).

## Handle the webhook

Configure a webhook endpoint in the [Developer Dashboard](https://dev.truemed.com/developers/webhooks)
and subscribe to `payment_session_complete`.

Your endpoint should:

1. Verify the webhook using the [webhooks guide](/guides/setup/api/resources/webhooks).
2. Find the order associated with the webhook `payment_id`.
3. Acknowledge receipt with any `2xx` response, typically `204 No Content`.
4. Fulfill only after `status` is `captured`.

For your first payment flow, handle these statuses:

| Webhook status | What it means                                                              | What to do                                                            |
| -------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `processing`   | The customer entered payment details and Truemed is reviewing the payment. | Show the customer an "order placed" confirmation. Do not fulfill yet. |
| `captured`     | The payment cleared review and funds are secured.                          | Fulfill the order.                                                    |
| `rejected`     | The payment failed review after checkout.                                  | Cancel the order and notify the customer.                             |

## Go deeper

| Need                                                                                                                                   | Guide                                                                                                       |
| -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Test approved, rejected, and expired flows in the sandbox                                                                              | [Testing](/guides/setup/api/payment-sessions/testing)                                                       |
| Validate launch readiness                                                                                                              | [Implementation Readiness Checklist](/guides/setup/api/payment-sessions/implementation-readiness-checklist) |
| Webhook verification, retries, and fulfillment rules                                                                                   | [Webhooks and Fulfillment](/guides/setup/api/payment-sessions/webhooks-and-fulfillment)                     |
| All payment statuses and flow diagrams                                                                                                 | [Payment Lifecycle](/guides/setup/api/payment-sessions/payment-lifecycle)                                   |
| [Manual capture](/guides/overview/glossary#manual-capture) instead of [immediate capture](/guides/overview/glossary#immediate-capture) | [Manual/Delayed Capture](/guides/setup/api/payment-sessions/manual-delayed-capture)                         |
| Itemized fees, discounts, shipping, and tax                                                                                            | [Itemized Fees and Discounts](/guides/setup/api/payment-sessions/itemized-fees-and-discounts)               |