Event types
Every event ZyloPay sends, the object it carries, and an example payload.
Each event type always carries the same object type in data.object. The body of a webhook delivery is exactly the event object, the same as GET /v1/events/{id}.
Subscribe with exact types, a family such as payment_intent.*, or * for everything. ping is sent only on request (a test event) and cannot be subscribed to.
Delivery headers
ZyloPay-Signaturestringrequiredt=<unix seconds>,v1=<hex HMAC-SHA256>(onev1per active secret).ZyloPay-Event-IdstringrequiredThe event ID; deduplicate on it.
ZyloPay-Event-TypestringrequiredZyloPay-Delivery-IdstringrequiredZyloPay-Delivery-Attemptintegerrequired
Summary
kyb.status_changed
The business verification status changed (for example pending → approved). Sent in both modes.
data.object is a kyb_verification.
payment.refunded
A refund of the payment succeeded; amount_refunded and status changed (previous_attributes).
data.object is a payment.
payment.succeeded
A payment settled on-chain and was indexed. Fires once per payment, whatever created it (terminal or API).
data.object is a payment.
payment_intent.canceled
The payment intent was canceled (by you, the cashier, the payer declining the confirmation, or expiry). Nothing was charged.
data.object is a payment_intent.
payment_intent.created
A payment intent was created through the API for a terminal.
data.object is a payment_intent.
payment_intent.payment_failed
A payment attempt was declined or failed; nothing was charged. last_payment_error says why. The intent can be retried until it expires.
data.object is a payment_intent.
payment_intent.processing
The settlement was broadcast but its outcome is not known yet. Never retry: ZyloPay resolves it and sends payment_intent.succeeded or payment_intent.payment_failed.
data.object is a payment_intent.
payment_intent.requires_action
The payment is held until the payer confirms it in the ZyloPay app (step-up). next_action says why and until when.
data.object is a payment_intent.
payment_intent.succeeded
The payment settled. payment names the settled payment once indexed (see payment.succeeded).
data.object is a payment_intent.
ping
A test event sent from the dashboard or POST /v1/webhook_endpoints/{id}/test.
data.object is a webhook_endpoint.
refund.created
A refund was created and sent (status pending).
data.object is a refund.
refund.failed
The refund did not happen (nothing moved). failure_code says why.
data.object is a refund.
refund.succeeded
The refund was mined; the funds are back with the payer.
data.object is a refund.
terminal.created
A terminal was provisioned.
data.object is a terminal.
terminal.deactivated
A terminal was deactivated; its key stops working.
data.object is a terminal.
terminal.deleted
A deactivated terminal was deleted.
data.object is a terminal.