API Reference
Webhook event catalog
Implement payment session and transaction event handlers.
Payment session events
Transaction events
Transaction events provide a separate confirmation signal alongside payment session events. Use transactionId from either stream for order reconciliation and support lookups.
Event envelope
Shape
json{
"id": "uuid",
"type": "payment_session.completed",
"createdAt": "2026-08-31T12:00:00.000Z",
"data": { }
}The envelope id matches X-Zippy-Webhook-Id. Merchant-facing data excludes internal gateway IDs and sensitive payer contact information.
Payload fields
Payment session data
| Name | Type | Description |
|---|---|---|
paymentSessionId | uuid | Zippy payment session identifier. |
status | enum | Session status at event time (CREATED, AWAITING_PAYMENT, COMPLETED, EXPIRED, DECLINED, …). |
merchantReference | string | Your reference from session create, if set. |
amount | decimal string | Locked checkout amount. |
currency | string | ISO currency code (USD). |
transactionId | uuid | null | Linked transaction when available. |
transactionStatus | string | null | Linked transaction status when available. |
payer.paymentId | string | null | Public Zippy payment ID handle. |
payer.displayName | string | null | Payer display name (first name + last initial). |
Transaction data
| Name | Type | Description |
|---|---|---|
transactionId | uuid | Zippy transaction identifier. |
status | enum | Transaction status at event time. |
amount | decimal string | Transaction amount. |
currency | string | ISO currency code (USD). |
merchantReference | string | Merchant reference from the linked session. |
paymentSessionId | uuid | Parent payment session. |
payer | object | null | Same payer shape as payment session events. |
Reserved events
These event types appear in the catalog for forward compatibility but are not emitted in production yet. Do not depend on them until announced in the changelog.