Webhooks

The Payments API publishes webhooks to notify your application of asynchronous events on the payments you initiate. Each webhook is delivered as a POST request to a URL registered against your Zepto account, with a JSON body describing the event.

Payout lifecycle

Every payout ends with a single payments_payout.finalised event. Statuses on the left, the webhook on the right:

payout ─┬─► settled ───────────────────────────────► payments_payout.finalised
        │
        ├─► cancelled ─────────────────────────────► payments_payout.finalised
        │
        └─► failed ──► any debited funds returned ─► payments_payout.finalised

body.status tells you how the payout ended: settled when the funds are available to the creditor, cancelled when the payout was cancelled, or failed with the reasons in body.errors.

For a failed payout, payments_payout.finalised is only sent once any funds debited for it are back in the debtor's account, so it is always safe to retry the payout or arrange a fallback payment when it arrives. Until then, fetching the payout may already show status: failed with timing.finalised_at still null; finalised_at is set when payments_payout.finalised is sent.

Delivery

Each payout publishes payments_payout.finalised once. Deliveries are identified by the payout's uid.

Payload

Every event is delivered in the same envelope: a data object identifying the payout and the event, with the event-specific detail in body.

{
  "data": {
    "uid": "payout-uid-123",
    "type": "payments_payout.finalised",
    "published_at": "2026-05-07T02:34:57Z",
    "metadata": { "order_id": "abc-123" },
    "body": {
      "status": "failed",
      "errors": [
        {
          "code": "ZIS99",
          "title": "Unknown Payment Error",
          "detail": "An unknown error occurred while processing the payment. Please contact Zepto for assistance."
        }
      ]
    }
  }
}

• uid — The unique identifier you supplied when creating the payout.
• type — The type of event that triggered the webhook.
• published_at — When the event was published by Zepto.
• metadata — The metadata you supplied when creating the payout.
• body — Event-specific details. For payments_payout.finalised: status (settled or failed) and errors (empty unless status is failed).

Each event, its payload schema, and when it is sent are documented under the Callbacks section of the Create Payout endpoint (POST /payments/payouts).