Session states and callbacks

A session reports each move to the webhook endpoint configured for your account. How to handle them is in Take a payment.

States

State	Callback	Final	What happened
CREATED	ipp.session.created	No	The session was dispatched and the device notified
ACTIVE	ipp.session.activated	No	The clerk chose a payment method and the device is waiting for the card
FINALIZED	ipp.session.finalized	Yes	The payment was collected and an order exists in Order Management
CANCELLED	ipp.session.cancelled	Yes	Cancelled by the clerk or by your backend
EXPIRED	—	Yes	The session’s TTL elapsed with no payment
—	ipp.payment.failed	No	A payment attempt was declined. The clerk may retry

Three states are final. Everything else can still move.

Payloads

Every event carries id, merchant_id, timestamp and type, with the event’s fields in data. Every data carries the session_id, and two events add one field each.

ipp.session.finalized adds the order_id of the order in Order Management:

{
  "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"
  }
}

ipp.payment.failed adds a failure_reason:

{
  "id": "215c4e46-7614-4cda-9400-e88b5bb6e2b1",
  "type": "ipp.payment.failed",
  "merchant_id": "DM11917000",
  "timestamp": "2026-06-16T12:41:23.544282548Z",
  "data": {
    "session_id": "3574c250-4673-45f2-b9f0-baf21ec6c946",
    "failure_reason": "CARD_DECLINED"
  }
}

Card tap outcomes

The outcomes a Playground simulated tap accepts. Every one but SUCCESS is a declined tap, which arrives as ipp.payment.failed and needs nothing from your backend: the clerk retries on the device and the session carries on. They’re also listed in the error catalog.

Outcome	Result
SUCCESS	Approved. The session finalizes. The default if you omit outcome
DECLINED_GENERIC	Declined, no specific reason
INSUFFICIENT_FUNDS	Declined for funds
LOST_CARD	Reported lost
STOLEN_CARD	Reported stolen
EXPIRED_CARD	Expired
INCORRECT_CVC	Wrong CVC
INCORRECT_NUMBER	Invalid card number
PROCESSING_ERROR	Terminal processing error
CARD_VELOCITY_EXCEEDED	Velocity limit hit

Related

• Webhooks — delivery, signatures and retries for every Kustom event
• In-Person Payments API — the session endpoints