Webhooks and Fulfillment

The payment_session_complete webhook is the fulfillment boundary for Truemed payments. Return URLs help you show the right customer experience, but your backend should update and fulfill orders from webhook statuses.

What to listen for

Subscribe to payment_session_complete in the Developer Dashboard.

The webhook payload includes the fields your order system needs:

Example payload

A captured event for an immediate-capture session. All amounts are integers in cents (12500 = $125.00).

1
{
2
  "payment_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
3
  "status": "captured",
4
  "created_at": "2026-01-15T09:30:00Z",
5
  "authorize_amount": 12500,
6
  "capture_amount": 12500,
7
  "captures": [
8
    { "capture_amount": 12500, "captured_at": "2026-01-15T09:31:12Z" }
9
  ],
10
  "order_items": [
11
    {
12
      "item_id": "line_item_1",
13
      "name": "Recovery Bundle",
14
      "sku": "recovery-bundle",
15
      "price": 12500,
16
      "quantity": 1,
17
      "total": 12500,
18
      "total_refundable": 12500,
19
      "quantity_refundable": 1
20
    }
21
  ],
22
  "metadata": "cart_12345"
23
}

The captures array and capture_amount reflect partial captures—there is no separate partially_captured status. For an authorization session, capture_amount is absent until you capture, and order_items carry total_capturable / quantity_capturable instead of the refundable fields. payment_token (pt_...) appears only if you created the session with tokenize: true or a payment_token.

Fulfillment rules

Webhook handler checklist

1. Verify the request using the webhooks guide.
2. Find the internal order by payment_id or by the metadata you sent when creating the session.
3. Store the latest webhook status on the order.
4. Make fulfillment idempotent so webhook retries do not duplicate shipments, emails, or credits.
5. Return a 2xx response after the event is stored or handled.

Retry behavior

Truemed retries failed webhook deliveries with backoff for up to 7 days. Treat each webhook as at-least-once delivery: your endpoint can receive the same status more than once.

Use your internal order state to make each action idempotent:

Related guides