Commerce Integration

The Kustom app is designed to work with — but does not require — the Commerce app. The checkout, confirm, and webhook ingresses all operate on Commerce-style carts (tickets of type cart), and the cart synchronization flow listens on Commerce's OnCartMutation hook. If you're using the Commerce app, everything below works out of the box; if you're integrating Kustom into a custom checkout flow, the same patterns can be re-implemented against your own ticket type.

End-to-end storefront guide

For a step-by-step walkthrough of integrating Kustom into a storefront — including the iframe lifecycle, suspend/resume handling, and the confirmation redirect — see the Storefront SDK documentation: Kustom Checkout.

Checkout Flow

The storefront initiates checkout by POST-ing to the Kustom checkout ingress with the cart ID. The ingress is idempotent — calling it again returns the existing Kustom order's snippet instead of creating a new one.

The storefront injects the returned htmlSnippet into the page, which mounts the Kustom iframe.

Cart Synchronization

Because Kustom renders the order summary inside its own iframe, the Kustom-side order must be updated whenever the Hantera cart changes (item added, quantity changed, coupon applied, etc.). The Kustom app handles this automatically via a hash-based sync mechanism driven by Commerce's OnCartMutation hook.

How It Works

1. The Commerce app fires OnCartMutation after every successful cart render with the full rendered cart payload.
2. The cart-kustom-sync rule listens on this hook. It builds the Kustom API update payload, hashes it, and compares the hash to the kustomSyncHash field stored on the cart.
3. If the hash differs, the rule:
   • Sets kustomPendingHash on the cart via a ticketCommand effect
   • Schedules the syncKustomOrder job with the pre-built payload via a scheduleJob effect
4. The syncKustomOrder job pushes the payload to Kustom's API, then updates kustomSyncHash to match kustomPendingHash.

Why Hash-Based and Not a Dirty Flag

Using OnCartMutation (a hook fired from the Commerce ingress runtime) instead of OnTicketCommands (which fires on any ticket mutation, including the sync rule's own writes) avoids an infinite loop:

cart command → OnTicketCommands → set dirty flag → OnTicketCommands → ...

The hash also lets the storefront tell, at a glance, whether the Kustom order is currently being synced: kustomPendingHash !== kustomSyncHash means a sync is in flight, so the iframe should be suspended.

Cart Fields Used by Kustom

Field	Purpose
kustomOrderId	The Kustom-side order ID. Set by the checkout ingress.
kustomPendingHash	Hash of the most-recently-built payload. Set by cart-kustom-sync.
kustomSyncHash	Hash of the most-recently-synced payload. Set by syncKustomOrder job.

Confirmation Flow

Kustom confirms successful checkouts via two paths. The Kustom app handles both — whichever fires first wins, the other becomes a no-op.

Primary Path: Confirm Ingress (Browser-Initiated)

When the customer completes payment, Kustom redirects the browser to the configured confirmation_url. The storefront detects this and calls the confirm ingress:

Fallback Path: Push Webhook

If the browser-initiated path fails (network drop, customer closes the tab, etc.), Kustom sends a push notification 2–5 minutes later:

Both paths acknowledge the order with Kustom (POST /ordermanagement/v1/orders/{id}/acknowledge) so Kustom stops sending push retries.

Pre-Completion Validation

Before completing checkout, Kustom can call back to the merchant for final validation (e.g., to verify that stock is still available). The Kustom app exposes the validate ingress for this, which fires the OnKustomValidation custom hook. Merchant-supplied rules can return a validationError effect to block completion with a structured error code that's displayed to the customer in the iframe.

See OnKustomValidation hook for full details.

Capture Flow

For Kustom payments, the authorization is created when the cart completes, but the funds are only captured later (typically when the order is fulfilled). The Kustom app subscribes to the platform's OnPaymentCapture hook:

Storefront Integration

See the Storefront SDK guide for the recommended client-side integration:

• Kustom Checkout (Storefront SDK)

The guide covers iframe lifecycle, suspending and resuming the iframe based on the sync-hash comparison, handling the confirmation redirect, and a reusable Vue component (KustomCheckout.vue) that wires it all together.

See Also

• Kustom App Overview — Ingresses, jobs, rules, and settings
• OnKustomValidation hook — Custom validation logic
• Commerce — OnCartMutation hook — The hook that drives cart sync
• Commerce PSP Integration — Generic PSP pattern