stablezact-pay

React and vanilla JavaScript SDK for Stablezact checkout.

Environment selection

The SDK uses production by default and no longer requires apiUrl for the standard Stablezact environments:

<StablezactPayment
  environment="production"
  publicKey="pk_live_..."
  config={{ amount: 100, customerEmail: '[email protected]' }}
/>

Use environment="staging" during staging integration. environment="auto" (the default) detects the environment from a supplied Stablezact API URL and uses staging on localhost; all other hosts safely default to production.

| Environment | API URL | Hosted payment screen | | --- | --- | --- | | Staging | https://talented-mercy-production.up.railway.app | https://paymentscreen-h9e8.vercel.app | | Production | https://hub.stablezact.com | https://payment.stablezact.com |

An explicit apiUrl or paymentScreenUrl remains supported as an override for private deployments.

Sandbox simulated tokens

Use a merchant test key (pk_test_...) with the same apiUrl and checkout configuration used in production. The SDK automatically detects sandbox mode, creates test payments through Stablezact Server, and displays a Pay with test tokens action. No blockchain wallet, gas, or real asset is involved.

For lower-level integrations, PaymentAPI.completeSandboxPayment(paymentId, customerId) completes a pending test payment and returns its simtx_... transaction hash. Replace only the public key with pk_live_... when moving the integration to production.

React / Vite Install

Use the package ESM entry for React apps:

import { StablezactPayment } from 'stablezact-pay';
import 'stablezact-pay/dist/style.css';

The React checkout is lazy-loaded from the root entry, so Vite apps do not pull the full wallet/payment stack into the initial application chunk.

Webhooks

Pass your backend webhook endpoint as callbackUrl when opening checkout:

<StablezactPayment
  config={{
    publicKey: 'pk_your-public-key',
    amount: 100,
    currency: 'USD',
    callbackUrl: 'https://your-store.com/api/webhooks/stablezact'
  }}
/>

On your backend, verify Stablezact webhook signatures before trusting the event:

import { stablezactWebhookMiddleware } from 'stablezact-pay';

app.post(
  '/api/webhooks/stablezact',
  stablezactWebhookMiddleware(process.env.STABLEZACT_WEBHOOK_SECRET),
  (req, res) => {
    // req.body is verified here.
    res.sendStatus(200);
  }
);

coinleyWebhookMiddleware is still exported as a backward-compatible alias, but new integrations should use stablezactWebhookMiddleware.

PWA Builds

The SDK ESM build is split into smaller chunks so vite-plugin-pwa can precache it with Workbox's default 2 MiB per-file limit. In the current build, the largest React checkout chunk is about 1.3 MB minified.

Do not import the standalone vanilla CDN bundle in React/Vite apps. The vanilla bundle is intentionally self-contained for script-tag usage and is much larger than the split ESM build.

If an app intentionally uses the standalone vanilla bundle with PWA precaching, configure Workbox explicitly:

VitePWA({
  workbox: {
    maximumFileSizeToCacheInBytes: 7 * 1024 * 1024
  }
})