Checkout SDK

Checkout SDK overview

Embed Zippy Pay checkout inline or in a modal with @zippypay/checkout.

@zippypay/checkout embeds Zippy Pay checkout on your website — inline in a container or as a full-page modal. Styles are fully scoped inside Shadow DOM, so no separate CSS import is required.

Installation

npm

bash

npm install @zippypay/checkout@1.2.1

Yarn

bash

yarn add @zippypay/checkout@1.2.1

CDN

html

<script src="https://unpkg.com/@zippypay/checkout@1.2.1/dist/index.min.js"></script>
<script>
  const checkout = ZippyPay.create({
    environment: "staging",
    sessionId: "550e8400-e29b-41d4-a716-446655440000",
    clientToken: "zps_REDACTED",
    mode: "inline",
    container: "#zippy-checkout",
  });
</script>

Pin the version in production. Also available via jsDelivr: https://cdn.jsdelivr.net/npm/@zippypay/checkout@1.2.1/dist/index.min.js. Mobile app checkout requires SDK 1.1.0+. The enforce default on phone requires SDK 1.2.0+.

Bundler

typescript

import { ZippyPay } from "@zippypay/checkout";
// Side-effect import registers the web component:
import "@zippypay/checkout";

Before the SDK runs

Your merchant backend creates a payment session with your server credentials (X-Api-Key). This must never run in browser code.

Create session (server)

http

POST /api/v1/payment-sessions
X-Api-Key: zp_live_…
Content-Type: application/json

{
  "amount": "25.00",
  "currency": "USD",
  "successUrl": "https://yourstore.com/checkout/success",
  "failureUrl": "https://yourstore.com/checkout/failure"
}

Response

json

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "clientToken": "zps_REDACTED",
  "expiresAt": "2026-08-31T12:30:00.000Z"
}

Pass credentials to the checkout page

Name	Type	Description
`sessionId`	UUID v4	URL-safe; can appear in QR and deep links. Validated at SDK init.
`clientToken`	zps_…	JavaScript only. Never in HTML attributes, URLs, logs, or analytics.

Hand off to the SDK

typescript

// ✅ Good — from your server-rendered page or secure API
const { sessionId, clientToken } = await fetch("/api/checkout-session").then(
  (r) => r.json(),
);

ZippyPay.create({ environment: "production", sessionId, clientToken });

Quick start

Call ZippyPay.create() with the session credentials from your server. Inline mode mounts inside a container; modal mode opens automatically.

Inline checkout

typescript

import { ZippyPay } from "@zippypay/checkout";

const checkout = ZippyPay.create({
  environment: "production",
  sessionId: "550e8400-e29b-41d4-a716-446655440000",
  clientToken: "zps_REDACTED",
  mode: "inline",
  container: "#zippy-checkout",
  theme: { primary: "#2563eb" },
  onReady: (session) => {
    console.log("Ready:", session.amount, session.currency);
  },
  onComplete: (session) => {
    console.log("Paid:", session.transactionId);
  },
  onError: (error) => {
    console.error(error.code, error.detail);
  },
});

// On page unload:
checkout.destroy();

HTML container

html

<div id="zippy-checkout"></div>

Modal checkout

typescript

import { ZippyPay } from "@zippypay/checkout";

// Modal opens automatically when created
const checkout = ZippyPay.create({
  environment: "production",
  sessionId: "550e8400-e29b-41d4-a716-446655440000",
  clientToken: "zps_REDACTED",
  mode: "modal",
  closeOnBackdropClick: true,
  closeOnEscape: true,
  onClose: () => console.log("Modal closed"),
});

checkout.open();
checkout.close();
checkout.destroy();

Environments

Pass environment — the SDK resolves the API base URL. You do not pass a raw API URL. Use the same environment where your backend created the session.

Environment mapping

Name	Type	Description
`production`	https://api.zippypay.io	Live merchant checkout.
`staging`	https://staging.api.zippypay.io	Staging and QA integrations.
`development`	Same-origin (empty base)	Local dev with a proxy to your API.

Embed modes

Inline

Renders inside a container on your page. Requires mode: 'inline' and a container selector or HTMLElement.

Modal

Centered overlay on document.body. Opens automatically on create. Supports backdrop and Escape dismiss.

Inline requirements

Name	Type	Description
`mode`	'inline'	Default embed mode.
`container`	string \| HTMLElement	Required. CSS selector (e.g. '#checkout') or DOM element. Throws if not found.

Modal options

Name	Type	Description
`closeOnBackdropClick`	boolean	Close when user clicks outside the panel. Default: false.
`closeOnEscape`	boolean	Close on Escape key. Default: false.

Architecture

Your server

POST /payment-sessions with X-Api-Key. Returns sessionId + clientToken.

Browser (SDK)

Polls session, handles QR or Zippy ID flow, shows terminal screens.

Zippy Pay

Session loading, checkout UI, and payment confirmation — handled by the SDK with your client token.

Framework integrations

Checkout SDK overview

Installation

Before the SDK runs

Quick start

Environments

Embed modes

Inline

Modal

Architecture

Your server

Browser (SDK)

Zippy Pay

Next steps

Framework integrations

Configuration

Checkout flow