Add an overlay checkout

In this guide you’ll add an overlay checkout to your site: a button that opens the Bachs hosted checkout in a modal on top of your page, takes the payment, and tells you the result in real time. By the end you’ll have a drop-in payment flow where the customer never leaves your site. The overlay loads the Bachs-hosted checkout inside an iframe, so your page never touches card data. Bachs owns the card form, tokenization, and the payment; you decide what to sell and what happens after.

The Bachs overlay checkout open on a merchant page: payment methods and a local-currency picker on the hosted checkout, with the sandbox test-card panel in the corner

Try it before you build. snapkit.bachs.io is a demo storefront built on this SDK. Open one-time, subscription, free-trial, and pay-what-you-want checkouts in the overlay or as the hosted page, all against the sandbox with a test card.

Quick start

<script src="https://checkout.bachs.io/bachs.js"></script>
<script>
  Bachs.Initialize({
    onEvent: (event) => console.log(event.type, event.data),
  });

  // checkout_url comes from your server (step 1 below)
  Bachs.Checkout.open({ checkoutUrl: checkout_url });
</script>

That is the whole client. The steps below walk through it properly, server side included.

How it works

Create a checkout session (server-side)

Your backend calls the Bachs API with your secret key and gets back a checkout_url. The amount and currency are fixed here, on your server.

Open the overlay (browser)

Your frontend loads bachs.js and calls Bachs.Checkout.open() with that session. The customer pays in the modal.

Fulfil on the webhook

Bachs sends the checkout.completed and collection.succeeded webhooks to your server. Those, not the browser, are your signal to grant access or ship the order.

Before you start

A sandbox API key (sk_sandbox_...). Keep it on your server. See Authentication.
At least one product to sell. See Create a product.
A webhook endpoint to confirm payments. See Set up webhooks.

Steps

Create a checkout session on your server

Call POST /v1/checkout-sessions from your backend with your secret key, exactly as in Accept a payment. You get back a checkout_url. Return it to your frontend.

Create sessions server-side only. Your secret key must never reach the browser, and creating the session on the server is what keeps the amount tamper-proof.

curl https://sandbox-api.bachs.io/v1/checkout-sessions \
  -H "Authorization: Bearer $BACHS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_cart": [
      { "product_id": "prod_abc123", "quantity": 1 }
    ],
    "customer": { "email": "jane@example.com", "name": "Jane Doe" },
    "success_url": "https://shop.example.com/thanks",
    "cancel_url": "https://shop.example.com/cart"
  }'

{
  "checkout_id": "chk_2N3o4P5q6R7s8T9u",
  "checkout_url": "https://checkout.bachs.io/c/V8xQ2mZpLj9RfTa",
  "status": "open",
  "expires_at": "2026-04-27T13:00:00Z",
  "created_at": "2026-04-27T12:00:00Z"
}

Add bachs.js to your page

Add the SDK with a script tag, or install the npm package if you use a bundler (Vite, Next.js, webpack). Both load the same overlay.

<script src="https://checkout.bachs.io/bachs.js"></script>

npm install @bachs/js

With the script tag, the SDK is available as the global Bachs. With the npm package, import the loader:

npm import

import { loadBachs } from "@bachs/js";

const Bachs = await loadBachs();

Initialize the SDK

Initialize once when your app loads, not on every click. Pass a global onEvent handler for checkout lifecycle events.

Bachs.Initialize({
  onEvent: (event) => {
    // Handle checkout lifecycle events (see the table below).
  },
});

There is no test/live switch on the SDK. A checkout session already carries its environment: a session created with a sandbox key is a sandbox checkout, and its checkout_url says which checkout serves it. Pass that URL through and the client works the same in every environment. Only if you open bare tokens with open({ token }) do you point the SDK somewhere with baseUrl (the sandbox checkout origin while you build).

Open the overlay

On a button click, fetch a fresh checkout_url from your server, then open the overlay with it. open() returns a promise that resolves once the modal is mounted.

<button id="pay">Pay with Bachs</button>

<script src="https://checkout.bachs.io/bachs.js"></script>
<script>
  Bachs.Initialize({
    onEvent: (event) => {
      if (event.type === "checkout.completed") {
        // Show a success screen. Fulfil on the webhook, not here.
        console.log("Paid:", event.data.reference);
      }
    },
  });

  document.querySelector("#pay").addEventListener("click", async () => {
    const { checkout_url } = await fetch("/api/create-checkout", {
      method: "POST",
    }).then((r) => r.json());

    Bachs.Checkout.open({ checkoutUrl: checkout_url });
  });
</script>

"use client";
import { useEffect } from "react";
import { loadBachs } from "@bachs/js";

export function PayButton() {
  useEffect(() => {
    loadBachs().then((Bachs) =>
      Bachs.Initialize({ onEvent: handleEvent }),
    );
  }, []);

  async function pay() {
    const Bachs = await loadBachs();
    const { checkout_url } = await fetch("/api/create-checkout", {
      method: "POST",
    }).then((r) => r.json());
    Bachs.Checkout.open({ checkoutUrl: checkout_url });
  }

  return <button onClick={pay}>Pay with Bachs</button>;
}

You can pass the whole checkout_url as checkoutUrl, or only its token segment as token. A checkoutUrl must be on your Bachs checkout origin; the SDK rejects any other host.

Handle checkout events

Pass an onEvent callback to Initialize (global) or to open (this checkout only). Each event is { type, data }. These events drive your UI, not fulfilment.

Event	When it fires	Use it for
`checkout.opened`	The overlay opened.	Analytics.
`checkout.loaded`	The iframe finished loading.	Analytics.
`checkout.ready`	The checkout is mounted and ready for input.	Hide your own loading state.
`checkout.completed`	The payment succeeded.	Show a success screen. Fulfil on the webhook, not here.
`checkout.failed`	The payment failed.	Show a retry prompt.
`checkout.expired`	The session expired before payment.	Prompt the customer to start over.
`checkout.closed`	The overlay was closed. `data.reason` says why.	Reset your button state.
`checkout.error`	An SDK-level error, such as a bad token.	Log `data.message`.

Bachs.Initialize({
  onEvent: (event) => {
    switch (event.type) {
      case "checkout.ready":
        hideLoadingState();
        break;
      case "checkout.completed":
        showSuccess(event.data.reference);
        break;
      case "checkout.failed":
        showRetry();
        break;
      case "checkout.error":
        console.error("Checkout error:", event.data.message);
        break;
    }
  },
});

Fulfil the order with a webhook

The overlay tells you when a payment succeeds, but the browser is not the source of truth. When the checkout is paid, Bachs sends the checkout.completed and collection.succeeded webhooks to your endpoint. Grant access or ship the order on whichever arrives first, once.

Never fulfil an order from the overlay’s browser event, also named checkout.completed. A customer can close the overlay after paying but before your code runs, so the browser event can be missed. Treat the webhooks your server receives as the source of truth, and verify their signatures before trusting them. See Set up webhooks.

collection.succeeded

{
  "id": "evt_3ab4e0d5d2",
  "type": "collection.succeeded",
  "created_at": "2026-04-27T12:04:00Z",
  "organization_id": "acct_7KpQ2mNv4XbR9dLc",
  "data": {
    "charge_id": "ch_1a2b3c4d5e6f",
    "checkout_id": "chk_2N3o4P5q6R7s8T9u",
    "status": "SUCCEEDED",
    "amount": "29.00",
    "currency": "USD"
  }
}

Test it

Use a sandbox key (sk_sandbox_...) and mode: "test" to run the whole flow against test-mode products without moving real funds. Open the overlay, pay with a test card, and confirm your webhook receives collection.succeeded. See Sandbox.

Go live

When you’re ready, swap one thing: create sessions with a live secret key (sk_live_...) against https://api.bachs.io. The live session’s checkout_url points at the live checkout, so the client code does not change at all. See Go live.

Methods

`Bachs.Initialize(options)`

Configure the SDK once, when your app loads. Returns Bachs for chaining.

Option	Type	Required	Description
`onEvent`	`function`	No	Global handler for every checkout lifecycle event.
`baseUrl`	`string`	No	Checkout origin used to build URLs for bare tokens and to validate `checkoutUrl`. Defaults to the live checkout; set the sandbox origin while you build with tokens. Not needed when you pass full `checkoutUrl`s.

`Bachs.Checkout.open(args)`

Opens the overlay. Returns a promise that resolves once the modal is mounted and rejects on a bad token or a checkoutUrl from the wrong origin.

Argument	Type	Required	Description
`checkoutUrl`	`string`	One of the two	The session’s `checkout_url` from your server. Must be on the configured checkout origin.
`token`	`string`	One of the two	Only the token segment of the URL; the SDK builds the URL on `baseUrl`.
`onEvent`	`function`	No	Extra handler for this checkout only, on top of the global one.
`options.showCloseButton`	`boolean`	No	Show the close button. Defaults to `true`.
`options.autoCloseOnComplete`	`boolean`	No	Close the overlay about 1.2 seconds after a successful payment. Defaults to `true`.

`Bachs.Checkout.close()` and `Bachs.Checkout.isOpen()`

Close the overlay programmatically, and check whether it is currently open.

How the overlay stays secure

No card data on your page. The card form lives in the Bachs iframe on checkout.bachs.io. Your site and the SDK never see the card number, CVV, or PIN.
Server-set amounts. The token references a session whose amount and currency were fixed on your server. The browser cannot change what the customer pays.
Origin-locked messaging. The SDK only accepts messages from the exact Bachs checkout origin it loaded, and only from its own iframe. Anything else is ignored.

Overlay or hosted page?

Both run the same checkout session; they differ in where the customer pays.

	Overlay	Hosted page
Where the customer pays	In a modal on your page	On the Bachs-hosted page after a redirect
Page context	Kept; the customer never leaves	Left and returned to via `success_url`
Integration	Script tag or `@bachs/js`, a few lines of JS	A plain redirect to `checkout_url`, zero JS
Browser events	Full lifecycle events (`checkout.completed`, …)	None; you get the redirect and webhooks
Best for	Keeping customers in your product	The simplest possible integration

The live demo has a toggle that opens every scenario both ways, on identical sessions.

Troubleshooting

The overlay does not open

Check the browser console for a checkout.error event. The usual causes: the SDK was not loaded before calling open(), the token is invalid, or the checkoutUrl is on a different origin than the SDK expects (set baseUrl to match where the session was created).

Events are not firing

Confirm onEvent is set in Initialize() or passed to open(), and that no other message listener on your page stops propagation. Events only flow while the overlay is open.

The overlay is blank

The session is probably expired or the token malformed; create a fresh session and open it promptly. Sessions default to a 60 minute lifetime.

Next steps

Live demo: click through every scenario on this page against the sandbox.
Accept a payment: the full checkout session flow the overlay opens.
Set up webhooks: receive and verify collection.succeeded.
The checkout session object: every field the API returns and accepts.

Get Started

Payouts

Virtual accounts

Products & pricing

Subscriptions

Customer portal

Payments

Dashboard

Developer Portal

CLI

For You and Your Customers

Add an overlay checkout

Quick start

How it works

Before you start

Steps

Handle checkout events

Fulfil the order with a webhook

Test it

Go live

Methods

`Bachs.Initialize(options)`

`Bachs.Checkout.open(args)`

`Bachs.Checkout.close()` and `Bachs.Checkout.isOpen()`

How the overlay stays secure

Overlay or hosted page?

Troubleshooting

Next steps

​Quick start

​How it works

​Before you start

​Steps

​Handle checkout events

​Fulfil the order with a webhook

​Test it

​Go live

​Methods

​Bachs.Initialize(options)

​Bachs.Checkout.open(args)

​Bachs.Checkout.close() and Bachs.Checkout.isOpen()

​How the overlay stays secure

​Overlay or hosted page?

​Troubleshooting

​Next steps

Quick start

How it works

Before you start

Steps

Handle checkout events

Fulfil the order with a webhook

Test it

Go live

Methods

`Bachs.Initialize(options)`

`Bachs.Checkout.open(args)`

`Bachs.Checkout.close()` and `Bachs.Checkout.isOpen()`

How the overlay stays secure

Overlay or hosted page?

Troubleshooting

Next steps