@snap-pay/js

SNAP.js — client-side SDK for creating and confirming SNAP payments in the browser.

Pairs with @snap-pay/elements (UI components) and @snap-pay/react (React bindings).

bun add @snap-pay/js @snap-pay/elements

Quick start

import { Snap } from "@snap-pay/js";
import "@snap-pay/elements";

const snap = new Snap("pk_test_…");
const elements = snap.elements({ clientSecret: sessionId });
const payment = elements.create("payment");
payment.mount("#pay");

const result = await snap.confirmPayment({ elements, clientSecret: sessionId });
if (result.status === "succeeded") window.location.href = "/thanks";

Options

new Snap(publishableKey, {
  apiBase: "http://localhost:3210", // for local dev / self-hosted
  cardFrameUrl: "http://localhost:3000/elements/card-frame",
});

• apiBase — defaults to the SNAP production API. Point at a local Convex deployment during development.
• cardFrameUrl — the origin hosting the Card iframe. Defaults to SNAP's hosted page; override for local dev or self-hosted deployments.

confirmPayment

const result = await snap.confirmPayment({ elements, clientSecret });
// result.status: "succeeded" | "processing" | "pending" | "failed" | ...
// result.transactionId: the SNAP transaction id

The SDK reads the customer's selection from the mounted Elements. Wallet selection sends provider directly; Card selection sends provider: "mock" alongside card_token / card_brand / card_last4 metadata in sandbox. Live-mode Card tokenization throws explicitly — it's on the roadmap for a subsequent release.

Any form-collecting elements (BillingAddressElement, CustomerElement, OtpElement) that are mounted inside the same Elements set contribute their values automatically — no extra plumbing.

Security

• Always pass a publishable key (pk_test_ or pk_live_). Secret keys (sk_…) belong on the server and must never ship to the browser — the constructor refuses them.
• The clientSecret is a checkout session id. It grants payment rights only for that session and its owning merchant.

License

MIT