Headless Checkout SDK

Build your own checkout UI with @shoppexio/checkout-js/headless while Shoppex handles payment sessions, webhooks, invoices, and fulfillment.

The Headless Checkout SDK is for merchants who want a fully custom checkout page on their own domain. You own the layout, fields, and buyer experience. Shoppex still creates the invoice, starts the payment session, handles 3DS or redirects, receives webhooks, and fulfills the order.

Use this when the hosted checkout page or modal embed is not flexible enough.

Headless checkout requires an active Business plan.

What You Need

• A storefront or app page on your own domain.
• An active Business plan.
• A headless checkout publishable key from the dashboard.
• At least one allowed origin for the site that will call the browser API.
• @shoppexio/checkout-js installed in your frontend app.

Dashboard Setup

Open Dashboard -> Settings -> Developer -> Headless Checkout.

1. Generate a publishable key

   Click Generate key. Copy the pk_live_... key immediately. The full key is shown only once.

2. Add your storefront origin

   Add the exact origin that hosts your checkout page, for example https://yourstore.com.

3. Add local development origins

   For local testing, add the exact local origin too, for example http://localhost:3000.

An origin is only the scheme, host, and optional port. Do not include a path.

URL you paste	Saved origin
https://vyy.gg/checkout	https://vyy.gg
https://www.vyy.gg	https://www.vyy.gg
http://localhost:3000/cart	http://localhost:3000

If your site works on both https://vyy.gg and https://www.vyy.gg, add both origins.

Never put a secret shx_... API key in browser code. Headless checkout uses pk_live_... or pk_test_... publishable keys only.

Install

npm install @shoppexio/checkout-js
# or
bun add @shoppexio/checkout-js

React Example

import {
  ShoppexCheckoutProvider,
  useCheckoutSession,
  useStripePaymentSession,
  ShoppexPoweredBy,
} from '@shoppexio/checkout-js/headless/react';

function CheckoutForm() {
  const { session, loading, error } = useCheckoutSession({
    product_id: 'PROD_123',
    email: '[e-mail]',
    quantity: 1,
  });

  const stripe = useStripePaymentSession(session?.id, {
    returnUrl: 'https://yourstore.com/thanks',
  });

  if (loading) return <p>Preparing checkout...</p>;
  if (error) return <p>{error.message}</p>;
  if (!session) return null;

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        void stripe.confirm();
      }}
    >
      <h1>{session.product?.title ?? 'Checkout'}</h1>
      <p>Total: {session.breakdown.total} {session.currency}</p>

      <div ref={stripe.mountRef} />

      <button type="submit" disabled={!stripe.ready}>
        Pay now
      </button>

      <ShoppexPoweredBy />
    </form>
  );
}

export default function Page() {
  return (
    <ShoppexCheckoutProvider publishableKey="pk_live_your_key_here">
      <CheckoutForm />
    </ShoppexCheckoutProvider>
  );
}

ShoppexPoweredBy is required unless your account has a server-side white-label entitlement. The SDK checks that the badge is visible before payment confirmation.

API Shape

The browser SDK sends the publishable key in the x-shoppex-publishable-key header. Shoppex also checks the request Origin header against your allowed origins.

The SDK can:

• create a checkout session
• read the current session status
• apply or remove coupons
• set tips
• select add-ons
• start a gateway payment session
• fetch delivery after the payment is complete

The session response includes line items, totals, available payment gateways, shop branding, terms, and delivery state. Render against the gateway kind, not the provider name, so your UI works across card, redirect, crypto, balance, and manual payment flows.

Troubleshooting

Generate key fails

Check these first:

• The shop has an active Business plan.
• You are using the shop owner account or a team member with permission to manage webhooks/developer settings.
• Your dashboard session is fresh. Refresh the page or log out and back in.

If it still fails, open browser DevTools -> Network and inspect:

POST /v1/dashboard/checkout/headless/rotate-key

Common responses:

Status	Meaning
403 BUSINESS_PLAN_REQUIRED	The shop is not on an active Business plan.
401	The dashboard session or shop permission is invalid.
500	Backend or database issue. Contact support with the request id if available.

Add origin fails

Use a full http:// or https:// origin. These are valid:

https://vyy.gg
https://www.vyy.gg
http://localhost:3000

These should not be saved as origins:

vyy.gg
https://vyy.gg/checkout
ftp://vyy.gg

The dashboard normalizes paths away before saving, but the backend still rejects non-http origins and malformed values.

Inspect this request if the UI only shows a generic error:

PUT /v1/dashboard/checkout/headless/origins

Browser API calls fail

Check the browser response code:

Status	Meaning
401	Missing, malformed, or unknown publishable key. Make sure it starts with pk_live_ or pk_test_.
403 ORIGIN_NOT_ALLOWED	The calling site’s origin is not in the allowed origins list.
403 BUSINESS_PLAN_REQUIRED	Headless checkout is not enabled for the shop’s current plan.

Related Docs

Headless Commerce Overview

Pick the right integration shape for custom storefronts, apps, and backend flows.

Checkout Embed SDK

Use the hosted modal when you do not need a fully custom checkout UI.

Storefront SDK

Read public product, cart, and storefront data from browser code.

Webhooks

Fulfill orders and update your app after Shoppex receives payment events.