@sazito/checkout

Headless checkout engine + React/Next UI for the Sazito platform, powered by @sazito/client-sdk. RTL-first (fa) with en support.

Installation

pnpm add @sazito/client-sdk @sazito/checkout react@18 react-dom@18

Architecture

@sazito/checkout/core   framework-agnostic engine (store, operateCart port, effects, selectors)
@sazito/checkout/react  CheckoutProvider + useCheckout() hook
@sazito/checkout/next   <SazitoCheckoutPage /> — the drop-in checkout component
@sazito/checkout/next/payment-return   server-safe Next.js callback parser
@sazito/checkout/next/server   server-side GET/POST payment callback handlers
@sazito/checkout/server   framework-neutral Web Request/Response handlers
@sazito/checkout/styles.css  self-contained, themeable, RTL/LTR styles

The React package uses the SDK client you provide. Create the Sazito SDK in your app, pass it through <SazitoProvider client={sazito}> or the client prop on <CheckoutProvider>, and checkout restores any seeded credentials on that same SDK instance. This avoids duplicate SDK clients and keeps cart/invoice/payment credentials in one place.

Usage (Next.js)

'use client';
import '@sazito/checkout/styles.css';
import { createSazitoClient } from '@sazito/client-sdk';
import { SazitoProvider, SazitoCheckoutPage } from '@sazito/checkout/next';

const sazito = createSazitoClient({ domain: 'shop.example.com' });

export default function Checkout() {
  return (
    <SazitoProvider client={sazito}>
      <SazitoCheckoutPage
        credentials={{ cart: { identifier: 'cart-identifier' } }}
        config={{
          locale: 'fa',
          continueShoppingUrl: '/',
          theme: {
            accent: '#4f46e5',
            accentForeground: '#ffffff',
            background: '#ffffff',
            foreground: '#0f172a',
            card: '#ffffff',
            border: '#e6e7eb',
            summaryBackground: '#f6f6fb',
            radius: 16
          }
        }}
      />
    </SazitoProvider>
  );
}

Payment gateway returns in Next.js

Keep the checkout UI at /checkout, then add one catch-all Route Handler for the nested gateway callback URLs. The host only exports the handlers; parsing, verification, and the secure redirect are implemented by this package.

Mount both handlers because gateways may return with either GET or POST:

// app/checkout/[...callback]/route.ts
import { SazitoCheckout } from '@sazito/checkout/next/server';

export const { GET, POST } = SazitoCheckout({
  domain: process.env.SAZITO_STORE_DOMAIN!,
  checkoutPath: '/checkout',
}).handlers;

On return, the handler validates the callback, reads its query/form/JSON body, calls payments.verifyPaymentCallback(), and preserves a confirmed show_order result. A small HTML response carries that result through tab-scoped storage to /checkout, where checkout displays success without a second payment request. If storage is unavailable, the response itself displays order confirmation. Other responses continue through a 303 redirect and a status read; pending payments are polled until settled. No host component or route changes are needed. The empty payment-in-place POST is redirected for a single browser-side verification because that method completes the order on its first payment-step call.

Use a Route Handler, not a Server Action: payment gateways send normal HTTP requests and do not use Next.js's private Server Action protocol.

Theme variables

config.theme (or the theme prop on SazitoCheckout) accepts:

| Property | CSS variable | Purpose | | --- | --- | --- | | accent | --szc-accent | Buttons and active states | | accentForeground | --szc-accent-foreground | Text/icons on the accent | | accentSoft | --szc-accent-soft | Selected and soft-accent surfaces | | background | --szc-bg | Checkout background | | foreground | --szc-fg | Primary text | | muted | --szc-muted | Muted surfaces | | mutedForeground | --szc-muted-fg | Secondary text | | border | --szc-border | Borders and dividers | | card | --szc-card | Card and input surfaces | | summaryBackground | --szc-summary-bg | Summary sidebar | | danger | --szc-danger | Errors and destructive states | | success | --szc-success | Completed and success states | | successForeground | --szc-success-foreground | Text/icons on solid success surfaces | | logoBackground | --szc-logo-bg | Plate behind shipping-provider logos | | shippingNeutral | --szc-shipping-neutral | Neutral surface for white shipping colors | | shippingNeutralForeground | --szc-shipping-neutral-foreground | Foreground on the neutral shipping surface |

radius and fontFamily remain available for shape and typography. Shipping-rate icon colors continue to come from the shipping API.

The component inherits the host font (--szc-font: inherit). The demo app loads Vazirmatn on <body>; that's all it takes for a Persian/RTL checkout.

Theme values may reference host application tokens directly. Changes to those tokens, including dark-mode changes, are reflected without rerendering:

config={{
  theme: {
    accent: 'var(--color-primary)',
    accentForeground: 'var(--color-on-primary)',
    background: 'var(--color-background)',
    foreground: 'var(--color-foreground)',
    card: 'var(--color-card)',
    border: 'var(--color-border)',
    fontFamily: 'var(--font-sans)',
  },
}}

Alternatively, pass className="store-checkout" and map the native variables in CSS imported after the checkout stylesheet:

.szc-root.store-checkout {
  --szc-accent: var(--color-primary);
  --szc-bg: var(--color-background);
  --szc-fg: var(--color-foreground);
  --szc-card: var(--color-card);
  --szc-border: var(--color-border);
  --szc-radius: var(--radius-lg);
}

Avoid configuring the same token through both methods: config.theme writes inline variables and therefore wins over ordinary stylesheet declarations.

The built-in empty-cart screen can be customized without replacing its layout:

<SazitoCheckoutPage
  config={{ continueShoppingUrl: '/products' }}
  emptyCart={{
    title: 'Nothing here yet',
    description: 'Explore the collection and add something you love.',
    actionLabel: 'Browse products',
  }}
/>

For complete control, use renderEmptyCart; it receives the resolved title, description, action label, icon, and continue-shopping URL.

Customize just the order-details link with getOrderDetailsUrl on SazitoCheckoutPage or SazitoCheckout:

<SazitoCheckoutPage
  config={{ continueShoppingUrl: '/fa/products' }}
  getOrderDetailsUrl={(order) =>
    `/fa/orders/${encodeURIComponent(String(order.id))}?identifier=${encodeURIComponent(order.orderIdentifier)}`
  }
/>

The callback receives the full CheckoutOrder. Return a relative path or an absolute URL for your theme's host and routes, keeping both id and orderIdentifier so the destination can call client.orders.get(id, orderIdentifier). The URL is used as supplied. Return null to hide the link. Without the callback, the default remains /orderinfo/{id}/{identifier} on the origin of an absolute continueShoppingUrl, or the current host otherwise. The link opens in a new tab. Define this callback inside a Client Component when using Next.js.

The post-payment screen has the same replacement path through renderResult:

<SazitoCheckoutPage
  config={{ continueShoppingUrl: '/products' }}
  renderResult={({ status, order, result, continueShoppingUrl, onRetry }) => (
    <StorefrontOrderResult
      status={status}
      order={order}
      message={result?.message}
      continueHref={continueShoppingUrl}
      onRetry={onRetry}
    />
  )}
/>

The custom renderer receives the normalized result status, finalized order, continue-shopping URL, and a retry action. Payment verification and pending polling remain managed by the checkout engine.

| RenderResultProps field | Type | Meaning | |---|---|---| | result | CheckoutResult \| null | Full result, backend message, and optional order | | status | success \| failed \| pending \| stock_violated | Normalized result status | | order | CheckoutOrder \| undefined | Finalized order convenience reference | | continueShoppingUrl | string \| undefined | Configured storefront destination | | onRetry | () => void | Return to the payment step |

renderResult is called only on the result step. It replaces the built-in ResultStep, while checkout verification, polling, the root theme/direction, the stepper, and the .szc-result-wrap layout remain active. The same prop is available on SazitoCheckout when composing CheckoutProvider manually.

Flow (v1 scope)

4 states — cart → shipping → payment → result:

• Cart — editable line items (quantity ±, remove).
• Shipping — guest contact + address form; per-package shipping-method switching for physical items; digital items skip shipping.
• Payment — payment-method selection + discount code; the Pay now (انجام پرداخت) CTA places the order directly (redirect / POST / pending-poll). The backend default appears first, online methods follow in backend order, and non-default pay-on-delivery/card-to-card methods appear last.
• Result — success / failed / pending, with the order code, public ID, shipping methods, purchased items, quantities, line totals, and invoice totals whenever the payment response includes an order. The built-in order-details action opens in a new browser tab.

Deferred (post-v1): card-to-card upload, invoice dynamic forms, wallet credit UI (engine keeps toggleCredit), multi-rate item reallocation, the legacy addDetails user comment.

Notes / deviations

• Styling. We originally planned Tailwind-authored components. Because the package exposes styles.css and must work in any React/Next app without forcing a Tailwind setup on consumers, the UI ships self-contained CSS (CSS-variable theme tokens, logical properties for RTL). The demo's Tailwind setup is untouched. Switching to Tailwind authoring later is possible without changing the engine.
• Local dev. exports point at TypeScript source; the example consumes it via Next transpilePackages. rollup.config.js exists for producing a publishable dist/ (point exports at dist before publishing).
• The engine is pure and emits typed effects; the React provider installs a default browser executor (redirect / gateway POST / polling). SSR-safe.

Scripts

pnpm test        # vitest (store, selectors, format, engine contract)
pnpm typecheck   # tsc --noEmit
pnpm build       # rollup → dist (for publishing)