Kustom

The Kustom app integrates Kustom as a Payment Service Provider in Hantera. Kustom is an iframe-based checkout where the provider owns the entire checkout UI — address collection, shipping options, and payment method selection all happen inside an iframe rendered by Kustom.

This is fundamentally different from card-style PSPs where the merchant controls the checkout UI and the PSP only processes the payment. With Kustom, the order summary is rendered inside Kustom's iframe, so the server must keep the Kustom order synchronized with the Hantera cart whenever cart contents change.

What It Provides

HTTP Ingresses

Ingress	Route	Purpose
checkout	POST /commerce/carts/{cartId}/payment/kustom	Idempotently creates (or returns) a Kustom order for the cart. Returns htmlSnippet for the storefront to render
confirm	POST /commerce/carts/{cartId}/payment/kustom/confirm	Called by the storefront after Kustom redirects to the confirmation URL. Creates the Payment and completes the cart
webhook	POST /kustom/webhook/push	Fallback push notification from Kustom (2–5 min after checkout). Completes the cart if the confirm path didn't
validate	POST /kustom/validate	Pre-completion callback from Kustom. Fires the OnKustomValidation hook

Jobs

Job	Purpose
syncKustomOrder	Pushes an updated order payload to Kustom's API when the cart changes
captureOrder	Captures an authorized Kustom order via the Order Management API

Rules

Rule	Listens on	Purpose
cart-kustom-sync	OnCartMutation	Builds the Kustom payload, hashes it, and schedules syncKustomOrder when the hash changes — see Commerce Integration
capture	OnPaymentCapture	Schedules captureOrder for Kustom payments

Custom Hook

The Kustom app emits one custom hook:

• OnKustomValidation — fires when Kustom calls back to validate an order before completing checkout. Merchant rules can return a validationError effect to block completion with a custom error code shown to the customer.

App Settings

Configured in the portal under the Kustom app:

Setting	Type	Description
username	text	Kustom API key ID
password	secret	Kustom API password
environment	select	playground (sandbox) or production

Architecture

When to Use Kustom

Choose Kustom when:

• You want a fully-managed checkout UI (iframe) and don't want to build your own
• You operate in markets where Kustom is a popular local payment provider
• You want pay-later and installment options handled by the provider

For card-only checkouts where you want to control the UI, use a card-style PSP instead.

Getting Started

1. Install the Kustom app on your Hantera instance.
2. Configure API credentials and environment in the portal.
3. Integrate the storefront. Follow the end-to-end guide in the Storefront SDK docs: Kustom Checkout.
4. (Optional) Add merchant validation rules using the OnKustomValidation hook.

See Also

• Commerce Integration — How the Kustom app integrates with the Commerce cart flow
• OnKustomValidation hook — Add custom validation logic
• Commerce PSP Integration — Generic PSP integration pattern
• Storefront SDK — Kustom Checkout — End-to-end storefront integration guide