Web SDK

The web SDK tells your pages and your server what a signed-in customer has paid for. It reads the same entitlements your iOS and Android apps use, so a customer who subscribed on an iPhone is Pro in your web app too, and a web subscription unlocks the mobile apps.

How it works#

The browser never holds a secret key and never decides who the customer is:

1. Your backend signs the customer in, with whatever authentication you already use.
2. It asks CashSDK for a web session for that customer and your site's origin. The session lasts at most ten minutes, and only works from that origin.
3. The browser uses the session and your publishable key to read the customer's access.
4. Purchases reach CashSDK as signed events from your payment provider. Returning from a checkout page grants nothing by itself.
5. Your server checks access again before it returns anything paid for.

Install#

npm install cashsdk-web cashsdk-node
# or: pnpm add cashsdk-web cashsdk-node
# or: yarn add cashsdk-web cashsdk-node

For React, add cashsdk-react as well. See React and Next.js.

Set up the dashboard#

Issue sessions from your backend#

Add one endpoint that your signed-in pages call. It must only answer a customer your own authentication has verified.

import { CashSDKServer } from "cashsdk-node";

export const cashsdkServer = new CashSDKServer({
  secretKey: process.env.CASHSDK_SECRET_KEY!, // csk_rk_test_… in sandbox
  environment: "sandbox",
});

import { cashsdkServer } from "@/lib/cashsdk-server";

export async function POST(request: Request) {
  const user = await requireSignedInUser(request); // your authentication
  const session = await cashsdkServer.createWebSession({
    customerId: user.id,               // never a value the browser sent
    origin: "https://app.example.com", // the exact origin you allowed
  });
  return Response.json(session, { headers: { "Cache-Control": "no-store" } });
}

Protect this endpoint against cross-site requests the way your framework does, for example with same-site cookies and a same-origin check.

A session lasts ten minutes, or less if you pass ttlSeconds. The browser client keeps it and asks your endpoint again shortly before it expires, so a page needs one session at a time, not one per request. Minting is rate limited per server key and per customer: see Server SDK. Pages that sell also ask for the checkout scopes, as Getting paid on the web shows.

Read access in the browser#

import { createCashSDK } from "cashsdk-web";

export const cashsdk = createCashSDK({
  publishableKey: "csk_pk_…",
  environment: "sandbox",
  getSessionToken: async ({ signal }) => {
    const response = await fetch("/api/cashsdk/session", {
      method: "POST",
      credentials: "same-origin",
      signal,
    });
    if (!response.ok) throw new Error("Sign in to continue");
    return response.json(); // { token, expiresAt, … }
  },
});

await cashsdk.initialize();
const { entitlements } = await cashsdk.getEntitlements();
const isPro = entitlements.some((item) => item.identifier === "pro" && item.active);

Create one client for the page and reuse it. It asks your endpoint for a session the first time it needs one.

The full list is in the reference.

Check access on your server#

The browser decides what to show. Your server decides what to serve.

const { entitlements } = await cashsdkServer.getEntitlements(user.id);
if (!entitlements.some((item) => item.identifier === "pro")) {
  return new Response("Pro is required", { status: 403 });
}

cashsdkServer is the cashsdk-node client from lib/cashsdk-server.ts. Its key needs the Customers permission.

Sign-out and switching customers#

In the browser, logout() clears the client's state and ends this tab's session:

await cashsdk.logout();

Each tab holds its own session. In your sign-out handler, end all of them with the server client:

await cashsdkServer.revokeWebSessions(user.id); // → { revoked: 2 }

To sign in as someone else without reloading, call cashsdk.setSessionTokenProvider(getSessionToken) after your own sign-in. It drops everything the client knew and ends the previous session.

Sandbox and production#

environment is "sandbox" or "production" and must match everywhere: the client, the server key (test or live), the origins you allowed, and the payment provider connection. Sandbox purchases never grant production access. Your Sandbox and Production Stripe connections live side by side, so you can keep testing in Sandbox after you go live.

Go live#

Before you take real payments, follow Go live with Stripe. It walks through the Production Stripe connection, the live prices, your production origins and the live server key, then a first live purchase and refund.

Next#

The source and a complete example application are on GitHub. The packages are MIT licensed.

Desktop and extensions#

The same customer sessions and Stripe account can serve Chrome extensions and directly distributed Mac apps. Extensions use cashsdk-web/extension, which ships in the cashsdk-web package. Mac apps use the CashSDKCommerce product of the Swift package, from version 2.4.0. Web apps use cashsdk-web and cashsdk-react directly.