Get started

Create a sandbox integration with a server-held API key and a same-origin buyer endpoint.

This guide lists a published product, creates gateway-hosted checkout, and shows where payment confirmation belongs. You need a Cipay sandbox API key, a storefront locator, and one published sandbox product with a price.

Install the SDK

bun add @cipay/client-sdk

pnpm add @cipay/client-sdk

npm install @cipay/client-sdk

yarn add @cipay/client-sdk

Connect your backend

Cipay ships two package entry points. Import each one only in its intended runtime:

The /api suffix above is a server SDK import. /api/cipay is the HTTP route you mount for browser-safe operations. The /react entry point calls that route and never receives your Cipay API key.

What is the storefront locator?

The locator is a public, non-secret identifier for the storefront whose published products and checkout settings you want to use. A sandbox locator looks like sandbox.<merchant-id>.<public-slug>.

Copy it from Cipay Platform → Settings → Developer → Storefront integration. Follow the three screenshot steps if you have not configured it yet.

• The API key authenticates your server.
• The locator selects the Cipay environment, merchant, and public storefront.
• Cipay uses that selection to load the published catalog and approved checkout origins.

Keep it in server configuration so the browser cannot switch to another merchant or environment.

import { createCipayClient } from "@cipay/client-sdk/api";

export const cipay = createCipayClient({
  apiKey: process.env.CIPAY_SANDBOX_API_KEY!,
  mode: "sandbox"
});

import { createCipayBuyerHandler } from "@cipay/client-sdk/api";
import { cipay } from "./cipay";
import { readVerifiedSession } from "./cipay-session";

export const cipayBuyerHandler = createCipayBuyerHandler({
  client: cipay,
  storefront: {
    locator: process.env.CIPAY_STOREFRONT_LOCATOR!
  },
  resolveCustomer: async (request) => {
    const session = await readVerifiedSession(request);
    return session
      ? { subject: session.userId, customerId: session.cipayCustomerId }
      : null;
  }
});

Connect React

CipayProvider receives your same-origin endpoint and a non-secret cache partition. It never receives an API key.

"use client";

import { CipayProvider } from "@cipay/client-sdk/react";

export function Providers({ userId, children }: {
  userId?: string;
  children: React.ReactNode;
}) {
  return (
    <CipayProvider endpoint="/api/cipay" sessionKey={userId}>
      {children}
    </CipayProvider>
  );
}

"use client";

import { ProductsList } from "@cipay/client-sdk/react";

export function Products() {
  return (
    <ProductsList
      heading="Available plans"
      input={{ pageSize: 12 }}
      className="products-grid"
      empty={() => <p>No published products yet.</p>}
    />
  );
}

Confirm the result