As a session moves through its lifecycle, Kustom sends POST requests to the webhook endpoint configured for the account in the Kustom Portal. Your endpoint is configured once per account, and must respond 200 to acknowledge each event.
Refer to the Webhook documentation for more information on how to set them up.
All In-Person Payments events are prefixed with ipp. so you can distinguish them from other Kustom webhooks routed to the same endpoint.
| Event | Trigger | Terminal? |
|---|---|---|
ipp.session.created | Session created and push notification sent to device (async). | No |
ipp.session.activated | Clerk selected payment method on device. | No |
ipp.session.finalized | Session collected and finalized. | ✅ Yes |
ipp.session.cancelled | Session cancelled by clerk or merchant backend. | ✅ Yes |
{
"id": "kevt_754uIatTW0hmi10Gggqe2H",
"merchant_id": "DM11917000",
"timestamp": "2026-06-05T18:37:41.232733416Z",
"type": "ipp.session.activated",
"data": {
"session_id": "c749c48d-df11-4ae3-8e5f-2c8491b16214",
"order_id": null,
"failure_reason": null
}
}Includes all base fields plus:
{
"id": "kevt_62EvxyMEaAaHSGeoDTza47",
"merchant_id": "DM11917000",
"timestamp": "2026-06-05T18:33:39.608920367Z",
"type": "ipp.session.finalized",
"data": {
"session_id": "dc01aa86-fb99-4d05-97dc-e79a22650f9a",
"order_id": "ccf4e76a-f56d-4d3a-abf9-f4fe941f0a1f",
"failure_reason": null
}
}The order_id is the UUID of the order created in Kustom Order Management. Store this — you'll use it to capture, refund, or cancel the payment.
Payment failures are handled on the device. No action is needed from your backend.
Once an ipp.payment.finalized callback is received, the payment is available in Kustom Order Management under the order_id from the callback. Use the Order Management API to:
- Capture the payment after goods are handed over if not already captured
- Refund full or partial amounts
- Cancel if the transaction needs to be voided
See the Order Management API for details.