payment.succeeded

Use payment.succeeded for payment reconciliation. Inspect the full schema before handling the payload.

Example payload

This fixture comes from the public specification, not a live delivery.

{
  "id": "evt_1a2b3c4d5e6f",
  "type": "payment.succeeded",
  "created": 1705689600,
  "livemode": true,
  "data": {
    "object": {
      "id": "pay_abc123",
      "object": "payment",
      "amount": 2500,
      "currency": "usd",
      "status": "succeeded",
      "customer_id": "cus_xyz789",
      "invoice_id": "inv_def456"
    }
  }
}

Handler contract

1. Verify the raw signature and validate the envelope.
2. Commit a unique inbox entry for the merchant and event ID before acknowledging.
3. Resolve truncated references and reconcile the current resource state.
4. Apply business changes using a business idempotency key.
5. Record completion durably; retry worker failures independently.

Use the complete receiver. A check-then-fulfil-then-mark sequence can duplicate effects during concurrent delivery or after a crash.

If invoice processing owns fulfilment, use this event for reconciliation only. Preserve the monetary units in the schema; do not use floating-point arithmetic for amounts.

Browse related events.

Owner: david · Reviewed 5 Sep 2026