{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-contents/checkout/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Receive Callbacks","description":"Explore our documentation and API and start integrating Kustom Checkout","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"receive-callbacks","__idx":0},"children":["Receive Callbacks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As a session moves through its lifecycle, Kustom sends ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," requests to the webhook endpoint configured for the account in the Kustom Portal. Your endpoint is configured once per account, and must respond ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," to acknowledge each event."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Refer to the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/contents/api/api-basics/webhooks"},"children":["Webhook"]}," documentation for more information on how to set them up."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"callback-events","__idx":1},"children":["Callback events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All In-Person Payments events are prefixed with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ipp."]}," so you can distinguish them from other Kustom webhooks routed to the same endpoint."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Trigger"},"children":["Trigger"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Terminal?"},"children":["Terminal?"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ipp.session.created"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Session created and push notification sent to device (async)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ipp.session.activated"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Clerk selected payment method on device."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ipp.session.finalized"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Session collected and finalized."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅ Yes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ipp.session.cancelled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Session cancelled by clerk or merchant backend."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅ Yes"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"session-activated","__idx":2},"children":["Session Activated"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"kevt_754uIatTW0hmi10Gggqe2H\",\n  \"merchant_id\": \"DM11917000\",\n  \"timestamp\": \"2026-06-05T18:37:41.232733416Z\",\n  \"type\": \"ipp.session.activated\",\n  \"data\": {\n    \"session_id\": \"c749c48d-df11-4ae3-8e5f-2c8491b16214\",\n    \"order_id\": null,\n    \"failure_reason\": null\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"session-finalized","__idx":3},"children":["Session Finalized"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Includes all base fields plus:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"kevt_62EvxyMEaAaHSGeoDTza47\",\n  \"merchant_id\": \"DM11917000\",\n  \"timestamp\": \"2026-06-05T18:33:39.608920367Z\",\n  \"type\": \"ipp.session.finalized\",\n  \"data\": {\n    \"session_id\": \"dc01aa86-fb99-4d05-97dc-e79a22650f9a\",\n    \"order_id\": \"ccf4e76a-f56d-4d3a-abf9-f4fe941f0a1f\",\n    \"failure_reason\": null\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order_id"]}," is the UUID of the order created in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Kustom Order Management"]},". Store this — you'll use it to capture, refund, or cancel the payment."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payment failures"]}," are handled on the device. No action is needed from your backend."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"order-management-after-completion","__idx":4},"children":["Order Management after completion"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ipp.payment.finalized"]}," callback is received, the payment is available in Kustom Order Management under the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order_id"]}," from the callback. Use the Order Management API to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Capture"]}," the payment after goods are handed over if not already captured"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Refund"]}," full or partial amounts"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Cancel"]}," if the transaction needs to be voided"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/contents/api/order-management"},"children":["Order Management API"]}," for details."]}]},"headings":[{"value":"Receive Callbacks","id":"receive-callbacks","depth":1},{"value":"Callback events","id":"callback-events","depth":2},{"value":"Session Activated","id":"session-activated","depth":3},{"value":"Session Finalized","id":"session-finalized","depth":3},{"value":"Order Management after completion","id":"order-management-after-completion","depth":2}],"frontmatter":{"title":"Receive Callbacks","description":"Kustom POSTs lifecycle events to the webhook endpoint configured in the Kustom Portal on every session state change. Events carry a unique eventId for deduplication and are retried for up to 24 hours.","seo":{"title":"Receive Callbacks"}},"lastModified":"2026-06-10T07:37:02.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/contents/checkout/in-person-payments/callbacks","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}