{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-contents/checkout/sidebars.yaml","oas-contents/api/in-person-payments.json":"oas-contents/api/in-person-payments.json"},"props":{"metadata":{"markdoc":{"tagList":["openapi-code-sample","openapi-response-sample","admonition"]},"type":"markdown"},"seo":{"title":"Create a Session","description":"Explore our documentation and API and start integrating Kustom Checkout","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":["openapi"],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"create-a-session","__idx":0},"children":["Create a Session"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a customer is ready to pay in-store, your backend creates a session with the cart details and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["device_id"]}," of the target terminal. Kustom dispatches it to the device immediately via push notification — no polling needed on your end."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-payment-session-flow","__idx":1},"children":["The payment session flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The diagram below shows the full lifecycle. Only the first step, creating the session, is something your backend does. Everything after the push notification happens inside the Kustom POS app; you can observe progress through the callbacks."]},{"$$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":"Actor"},"children":["Actor"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Role"},"children":["Role"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Merchant System"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The merchant's backend or e-commerce platform that creates payment sessions when a customer is ready to pay in-store. Webhooks to receive lifecycle events and an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["orderId"]}," to correlate the session with its own order record are configured in the Kustom Portal."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Shopper"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Anyone shopping at the merchant store."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Store Clerk"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Merchant employee using the Kustom POS app to collect in-person payments."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Kustom POS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Kustom POS app for iOS or Android running on any certified device."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Session API"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Kustom session API, used to create sale sessions that handle the payment collection and order creation workflow."]}]}]}]}]},{"$$mdtype":"Tag","name":"Mermaid","attributes":{"data-language":"mermaid","diagramSource":"sequenceDiagram\n actor Shopper\n actor Store Clerk\n participant Kustom POS\n participant Session API\n participant Merchant System\n\n critical Public — authenticated with x-merchant-id\n Merchant System->>+Session API: POST /ipp/v1/sessions\n Note over Merchant System,Session API: Session payload\n Session API->>-Merchant System: 200 if session created successfully\n Session API-->>Merchant System: callback: ipp.session.created (async)\n end\n\n critical Kustom POS gets notified about new session\n Session API->>Kustom POS: Push notification { sessionId }\n end\n\n critical Kustom POS payment flow\n Kustom POS->>+Session API: Get session details\n Store Clerk->>Kustom POS: Selects payment method (ex: tap-to-pay)\n Kustom POS->>+Session API: Attaches payment to session\n Session API-->>Merchant System: callback: ipp.session.activated\n Session API->>-Kustom POS: \n\n Kustom POS->>Store Clerk: Present tap-to-pay screen\n Store Clerk->>Shopper: Present tap-to-pay\n\n alt Payment succeeds\n Shopper->>Kustom POS: Tap card\n Kustom POS->>+Session API: Finalize payment\n Session API-->>Merchant System: callback: ipp.session.finalized\n Session API->>-Kustom POS: \n Kustom POS->>Store Clerk: Render receipt / QR code\n else Payment fails — clerk retries\n Shopper->>Kustom POS: Tap card (declined)\n Kustom POS->>+Session API: Finalize payment\n Session API->>-Kustom POS: Return payment failed status\n Kustom POS->>Store Clerk: Show payment failed\n else Clerk cancels\n Store Clerk->>Kustom POS: Cancel session\n Kustom POS->>+Session API: Cancel session\n Session API-->>Merchant System: callback: ipp.session.cancelled\n Session API->>-Kustom POS: \n end\n end\n","diagramHtml":"
Merchant SystemSession APIKustom POSMerchant SystemSession APIKustom POSSession payloadcritical[Public — authenticated withx-merchant-id]critical[Kustom POS gets notifiedabout new session]alt[Payment succeeds][Payment fails — clerk retries][Clerk cancels]critical[Kustom POS payment flow]ShopperStore ClerkPOST /ipp/v1/sessions200 if session created successfullycallback: ipp.session.created (async)Push notification { sessionId }Get session detailsSelects payment method (ex: tap-to-pay)Attaches payment to sessioncallback: ipp.session.activated​Present tap-to-pay screenPresent tap-to-payTap cardFinalize paymentcallback: ipp.session.finalized​Render receipt / QR codeTap card (declined)Finalize paymentReturn payment failed statusShow payment failedCancel sessionCancel sessioncallback: ipp.session.cancelled​ShopperStore Clerk
"},"children":["sequenceDiagram\n actor Shopper\n actor Store Clerk\n participant Kustom POS\n participant Session API\n participant Merchant System\n\n critical Public — authenticated with x-merchant-id\n Merchant System->>+Session API: POST /ipp/v1/sessions\n Note over Merchant System,Session API: Session payload\n Session API->>-Merchant System: 200 if session created successfully\n Session API-->>Merchant System: callback: ipp.session.created (async)\n end\n\n critical Kustom POS gets notified about new session\n Session API->>Kustom POS: Push notification { sessionId }\n end\n\n critical Kustom POS payment flow\n Kustom POS->>+Session API: Get session details\n Store Clerk->>Kustom POS: Selects payment method (ex: tap-to-pay)\n Kustom POS->>+Session API: Attaches payment to session\n Session API-->>Merchant System: callback: ipp.session.activated\n Session API->>-Kustom POS: \n\n Kustom POS->>Store Clerk: Present tap-to-pay screen\n Store Clerk->>Shopper: Present tap-to-pay\n\n alt Payment succeeds\n Shopper->>Kustom POS: Tap card\n Kustom POS->>+Session API: Finalize payment\n Session API-->>Merchant System: callback: ipp.session.finalized\n Session API->>-Kustom POS: \n Kustom POS->>Store Clerk: Render receipt / QR code\n else Payment fails — clerk retries\n Shopper->>Kustom POS: Tap card (declined)\n Kustom POS->>+Session API: Finalize payment\n Session API->>-Kustom POS: Return payment failed status\n Kustom POS->>Store Clerk: Show payment failed\n else Clerk cancels\n Store Clerk->>Kustom POS: Cancel session\n Kustom POS->>+Session API: Cancel session\n Session API-->>Merchant System: callback: ipp.session.cancelled\n Session API->>-Kustom POS: \n end\n end\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"create-a-session-1","__idx":2},"children":["Create a session"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-contents/api/in-person-payments.json","operationId":"createSession","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"OpenApiResponseSample","attributes":{"descriptionFile":"oas-contents/api/in-person-payments.json","operationId":"createSession"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All amounts are in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["minor units"]},". ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["19900"]}," means ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["199.00"]}," in the given currency."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Lifecycle callbacks are delivered to the webhook endpoint configured in the Kustom Portal — see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/contents/checkout/in-person-payments/callbacks"},"children":["Receive Callbacks"]},"."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your merchant account has multiple locations, pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["location_id"]}," as a query parameter: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /ipp/v1/sessions?location_id="]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Store the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session_id"]},". The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ipp.session.created"]}," callback is delivered ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["asynchronously"]}," — the create response is returned first, and the callback fires shortly after. In the edge case where the callback arrives before your system has finished processing the create response, use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order_id"]}," to correlate."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"session-lifecycle","__idx":3},"children":["Session lifecycle"]},{"$$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":"State"},"children":["State"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$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":["created"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Session dispatched, push notification sent to 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":["activated"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Clerk selected payment method, tap-to-pay in progress."]},{"$$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":["completed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payment collected. Order created in Kustom Order Management."]},{"$$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":["cancelled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cancelled by the clerk or by your backend."]},{"$$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":["expired"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Session TTL elapsed without completion."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅ Yes"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"fetch-session-status","__idx":4},"children":["Fetch session status"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Poll this endpoint if you need the current state without waiting for a callback:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"fetch-session-details","__idx":5},"children":["Fetch session details"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-contents/api/in-person-payments.json","operationId":"getSession","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"OpenApiResponseSample","attributes":{"descriptionFile":"oas-contents/api/in-person-payments.json","operationId":"getSession"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"cancel-a-session","__idx":6},"children":["Cancel a session"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can cancel a session from your backend as long as it has not reached a final state:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"cancel-session","__idx":7},"children":["Cancel session"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-contents/api/in-person-payments.json","operationId":"cancelSession","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"OpenApiResponseSample","attributes":{"descriptionFile":"oas-contents/api/in-person-payments.json","operationId":"cancelSession"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cancellation is final — no further payment collection is possible on a cancelled session."]}]}]},"headings":[{"value":"Create a Session","id":"create-a-session","depth":1},{"value":"The payment session flow","id":"the-payment-session-flow","depth":2},{"value":"Create a session","id":"create-a-session-1","depth":4},{"value":"Session lifecycle","id":"session-lifecycle","depth":2},{"value":"Fetch session status","id":"fetch-session-status","depth":2},{"value":"Fetch session details","id":"fetch-session-details","depth":4},{"value":"Cancel a session","id":"cancel-a-session","depth":2},{"value":"Cancel session","id":"cancel-session","depth":4}],"frontmatter":{"title":"Create a Session","description":"When a customer is ready to pay in-store, create a payment session targeting a registered device. Kustom dispatches it via push notification to the clerk's terminal instantly.","seo":{"title":"Create a Session"}},"lastModified":"2026-06-10T07:37:02.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/contents/checkout/in-person-payments/create-session","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}