@reflow-works/checkout

Reflow Works shopper SDK for TypeScript, JavaScript, Node and browser integrations. Beta: provider sandbox only. Live custom Shopify purchases remain gated. This package does not bypass merchant account enablement or Shopify approval.

npm install @reflow-works/checkout@beta

import { ReflowCheckout, ReflowIdentity } from "@reflow-works/checkout";

const identity = new ReflowIdentity("YOUR_PUBLIC_STORE_KEY");
const providers = await identity.discover();
// Render the configured provider's CAPTCHA / Firebase verification first.
const challenge = await identity.startOtp(
  "merchant-otp",
  "+919000000000",
  captchaToken,
);
const session = await identity.verifyOtp({ ...challenge, code: enteredCode });
const checkout = new ReflowCheckout({
  storeId: session.context.storeId,
  environment: session.context.environment,
  getAccessToken: () => session.accessToken,
});
const cart = await checkout.create({
  items: [{ variantId: "merchant-variant-id", quantity: 1 }],
  idempotencyKey: crypto.randomUUID(),
});
const methods = await checkout.methods(cart.id);
// Show enabled methods, with no payment-gateway selector.
const paymentKey = crypto.randomUUID(); // Retain this key if the outcome is uncertain.
await checkout.pay(cart.id, {
  method: "upi",
  details: { upiFlow: "qr" },
  idempotencyKey: paymentKey,
});
const result = await checkout.waitForPayment(cart.id);
// Only result.session.status === 'completed' means a completed order.

The token must be a Reflow shopper access token, obtained after verification. Merchant keys, Firebase ID tokens and gateway credentials are not checkout bearer tokens. startExternal / verifyExternal exchanges a merchant-configured Firebase or Google proof for a shopper session. The merchant must configure permitted origins and enable SDK access in its plan.

Use one client per authenticated shopper request in a Hydrogen server loader/action. Never place a merchant key in a browser bundle or share a mutable client between users. Browser integrations need an operator-approved CORS origin or a merchant-owned same-origin backend. The SDK does not persist tokens; use short-lived memory or platform secure storage. Clear user state on logout.

All operations have bounded network timeouts. Mutations are never automatically retried; retain and reuse the same idempotency key after a lost response. Monitoring is bounded and abortable. PAYMENT_UNRESOLVED, order_pending, QR expiry or an app return are not permission for a second charge. Resume payment() / waitForPayment() instead.

configuration() returns the API/checkout version, merchant feature grants and theme configuration. Sandbox/live is explicit and checked against the authenticated store. New SDK checkout creation requires its feature grant; existing payment recovery remains accessible if access is later removed.

No card-number or CVV contract is exposed. Render secure provider fields using supported merchant integrations, or use the Reflow checkout interface. Never collect card details in ordinary merchant inputs or send them through this client.

Validation: typed compilation, protocol/uncertain-payment tests and clean tarball consumer installation. Actual gateway accounts, Shopify canonical purchases and physical device UAT are separate launch gates. Support: [email protected].