Skip to content
Docs
Get playground access

How Kustom Checkout works

The four calls behind every Kustom Checkout integration, what your site is responsible for at each one and how to tell whether you should be writing this code at all or installing a plugin instead.

Kustom Checkout is a hosted checkout you embed in your own site: you send Kustom a cart, Kustom sends back a block of HTML and you render it. This page is the model the rest of the guides assume — read it once and the integration models, the callbacks and the order lifecycle all sit in the same frame. It assumes you have a website and a backend that can make HTTP requests, and nothing else.

Check for a plugin first. Kustom sells through roughly thirty e-commerce platforms, and on most of them the integration is already written. If you run WooCommerce, Magento, Litium, Centra, PrestaShop or similar, installing the plugin is the whole job and everything below is background rather than instructions. Find your platform before you write any code.

Keep reading if no plugin covers your platform, if you’re building the platform integration itself or if you need behavior a plugin doesn’t expose.

The four calls

Section titled “The four calls”

A direct integration is four calls in a fixed order. Every page under Build a checkout is an expansion of one of them.

  1. Create the order. You POST the cart — country, currency, locale, totals, order lines and the URLs Kustom should call back. Kustom replies with an order id and an html_snippet.
  2. Render the snippet. You put that html_snippet on your checkout page and let its script run. That script loads the checkout iframe the customer interacts with.
  3. Read the order. After the customer pays, you read the order back to find out what they chose and confirm the purchase completed.
  4. Render the confirmation snippet. The order you read back carries a second html_snippet, now a receipt, which you render on your confirmation page.

Two things happen around step 3 that are easy to miss. Kustom redirects the customer’s browser to your confirmation URL, and separately calls your push URL server-to-server — so you still learn about the order when the browser never arrives. Treat the push as the authoritative one.

Integration models

Section titled “Integration models”

Everything above describes the embedded checkout, which is how most integrations render. It isn’t the only way. A Hosted Payment Page puts the same checkout on a Kustom-hosted page you redirect to, for server-only integrations that can’t embed. The Mobile SDK renders it natively inside an iOS or Android app. Beside them, Elements are individual pieces — express buttons, payment method display — to drop into pages you already own.

The important part is that this is a decision about rendering, not about the API. Every integration model, and Elements too, creates and reads the same order object with the same four calls, so nothing you learn here is wasted by choosing differently later — Integration models shows the options.

Taking payment on a terminal in a physical shop is a separate product rather than another integration model — see In-person payments.

What you are responsible for

Section titled “What you are responsible for”

Kustom owns the checkout UI, the payment methods and the customer’s payment data. You own:

  • The cart math. Kustom validates totals strictly, and a mismatch between order lines and the order total is rejected rather than corrected.
  • The callback endpoints. Confirmation, push, and optionally validation and shipping.
  • Your own order record. The push call is what tells you to create it.
  • The store around the checkout. A secure checkout inside a compromised storefront protects nobody — see below.

The store around the checkout

Section titled “The store around the checkout”

Most of this is unglamorous, and it’s exactly what automated attacks look for. They don’t distinguish between small shops and large ones.

  • Patch the store software and everything under it: operating system, web server, frameworks, plugins.
  • Run a security scanner if one exists for your platform.
  • Keep administrative accounts to the minimum number of people, give each person their own and delete the ones for people who have left or that you can’t account for.
  • Require passwords of at least 10 characters, and turn on two-factor authentication wherever it’s offered.
  • Turn on admin action logging, and watch it for unusual activity.

If the checkout looks wrong, or you see anomalies in transaction processing, contact your Kustom delivery manager or merchant support immediately rather than waiting to be sure.

What an auditor will ask for. Kustom’s own certifications — PCI DSS, PSD2 — are what you cite for the payment side. Your Kustom contact supplies the current attestations on request. What you’re asked to evidence is your side of the line: which integration model you integrated, that card data never reaches your servers and the hardening above. With the embedded checkout, the hosted payment page and the Mobile SDK, card data never enters a page you serve — the iframe, Kustom’s page or the SDK owns it. Elements are components on pages you own, so which SAQ applies depends on which elements you use.

Section titled “Related”

This page is also available as Markdown — append .md to its URL — and is indexed in llms.txt.