Payment Lifecycle Webhook Events

Available from v1.0.10

Calmony Pay now fires webhook events at every key stage of the payment lifecycle. This lets your application react to payment outcomes in real time — trigger fulfilment, update your database, send receipts, or notify third-party services — without polling the API.

Events Reference

payment_intent.succeeded

Fired after a Payment Intent is confirmed and the charge is successfully captured.

{
  "id": "evt_...",
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_...",
      "object": "payment_intent",
      "amount": 2000,
      "currency": "gbp",
      "status": "succeeded"
    }
  }
}

---

payment_intent.payment_failed

Fired after a Payment Intent confirm attempt fails. Inspect last_payment_error on the Payment Intent object for the failure reason.

{
  "id": "evt_...",
  "type": "payment_intent.payment_failed",
  "data": {
    "object": {
      "id": "pi_...",
      "object": "payment_intent",
      "status": "requires_payment_method",
      "last_payment_error": {
        "code": "card_declined",
        "message": "Your card was declined."
      }
    }
  }
}

---

payment_method.attached

Fired after a Payment Method is attached to a Customer.

{
  "id": "evt_...",
  "type": "payment_method.attached",
  "data": {
    "object": {
      "id": "pm_...",
      "object": "payment_method",
      "type": "card",
      "customer": "cus_..."
    }
  }
}

---

checkout.session.completed

Fired after a Checkout Session is completed by the customer.

{
  "id": "evt_...",
  "type": "checkout.session.completed",
  "data": {
    "object": {
      "id": "cs_...",
      "object": "checkout.session",
      "payment_status": "paid",
      "customer": "cus_..."
    }
  }
}

---

Envelope Format

All webhook events are delivered using the Stripe envelope format. Each event object contains:

Field	Description
id	Unique event identifier (evt_...)
type	The event type string (e.g. payment_intent.succeeded)
data.object	The full resource object at the time of the event

This means any existing Stripe webhook library or listener (e.g. stripe.webhooks.constructEvent()) will work with Calmony Pay webhook payloads without modification.

Registering a Webhook Endpoint

Configure your endpoint URL to receive these events via the Calmony Pay dashboard or API. Your endpoint should:

1. Accept POST requests with a JSON body.
2. Return a 2xx HTTP status promptly to acknowledge receipt.
3. Process events asynchronously if your handler logic is time-consuming.

Handling Events Reliably

• Idempotency: Events may be delivered more than once. Use the event id to deduplicate.
• Ordering: Events are not guaranteed to arrive in order. Use the resource's own state (e.g. payment_intent.status) as the source of truth.
• Failures: If your endpoint does not return 2xx, delivery will be retried with exponential back-off.