Webhooks for API payment gateway

When an API gateway order changes payment state, Zenofy POSTs JSON to the webhook URL configured on the product (not per API request).

Configure URL and optional secret in the merchant app when creating or editing an API Gateway product (External software integration section).

These events are separate from order webhooks (Integrations → Webhook for standard products) and from SaaS subscription webhooks (Software/SaaS products).

Failed deliveries are retried automatically (exponential backoff). Verify authenticity with the optional product webhook secret.

Configuration

Webhook URL is required before POST /checkout/order-api-gateway will succeed. Webhook secret is optional; when set, each request includes X-Signature: sha256=<hex> (HMAC-SHA256 of the raw JSON body).

Outbound HTTP request

POST · Content-Type: application/json

POST https://your-server.com/webhooks/zenofy HTTP/1.1
Content-Type: application/json
X-Event: payment.succeeded
X-Signature: sha256=abc123...

{ ... }

Signature verification

Compute HMAC-SHA256 of the raw request body using your product webhook secret. Compare to header X-Signature (prefix sha256=). Event name is also in header X-Event (e.g. payment.succeeded).

Event types

EventWhen
payment.succeededOrder marked paid.
payment.refundedOrder marked refunded.
payment.chargebackOrder marked chargeback (admin).

JSON body fields

  • event — event type (same as X-Event)
  • payment_id — stable id derived from the order (e.g. pay_…)
  • checkout_id — order id (same as checkout_id from create API)
  • reference — your reference from the create request, if any
  • amount — integer minor units
  • currency — ISO code
  • status — succeeded, refunded, or chargeback
  • customer — name, email
  • payment_method — alias such as mpesa, card
  • paid_at — when the order was paid (refund/chargeback events include this too)
  • refunded_at — on payment.refunded
  • chargeback_at — on payment.chargeback

Sample JSON bodies

payment.succeeded (illustrative)

{
  "event": "payment.succeeded",
  "payment_id": "pay_12abcd01",
  "checkout_id": "673f92b2c3d94a0012abcd01",
  "reference": "inv-2026-0042",
  "amount": 2500,
  "currency": "MZN",
  "status": "succeeded",
  "customer": {
    "name": "João Silva",
    "email": "buyer@example.com"
  },
  "payment_method": "mpesa",
  "paid_at": "2026-05-19T11:22:00+02:00"
}

payment.refunded (illustrative)

{
  "event": "payment.refunded",
  "payment_id": "pay_12abcd01",
  "checkout_id": "673f92b2c3d94a0012abcd01",
  "reference": "inv-2026-0042",
  "amount": 2500,
  "currency": "MZN",
  "status": "refunded",
  "customer": {
    "name": "João Silva",
    "email": "buyer@example.com"
  },
  "payment_method": "mpesa",
  "paid_at": "2026-05-19T11:22:00+02:00",
  "refunded_at": "2026-05-20T09:00:00+02:00"
}

← Create API gateway order (POST)

All tutorials