@blaze-money/react

Drop-in React components for accepting payments with Blaze.

Quick Start

There is no client-side key. Authentication comes from a server-created payment link (or checkout session) — the widget only needs the resulting short code. In-browser card encryption is initialized automatically: the widget fetches Blaze's public Evervault identifiers from the backend (GET /v1/checkout/config), so you don't pass them. (You can optionally override them via evervaultTeamId / evervaultAppId — see the advanced note below.)

1. Create a payment link (server-side)

Call this from your backend with your secret API key. The secret key never reaches the browser.

// e.g. Next.js API route, Express handler, etc.
const res = await fetch("https://api.blaze.money/v1/payment-links", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BLAZE_SECRET_KEY}`, // requires scope PAYMENT_LINKS_WRITE
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 2500, // cents
    currency: "USD",
    description: "Pro Plan — Annual",
    metadata: { user_id: "usr_abc123" },
  }),
})

const { short_code } = await res.json()
// e.g. short_code = "pl_ImsNk4rl" (the share URL is https://blze.at/<short_code>)
// Return ONLY the short_code to your frontend — never the full share URL.

2. Embed the checkout (client-side)

import { BlazeCheckout } from "@blaze-money/react"

export function CheckoutPage({ paymentLinkCode }: { paymentLinkCode: string }) {
  return (
    <BlazeCheckout
      paymentLinkCode={paymentLinkCode} // short code ONLY, e.g. "pl_ImsNk4rl"
      onComplete={(event) => {
        console.log("Payment succeeded:", event.sessionId)
        window.location.href = "/success"
      }}
      onError={(err) => console.error("Payment failed:", err)}
      appearance={{
        theme: "night",
        variables: { colorPrimary: "#6366f1", borderRadius: "12px" },
      }}
    />
  )
}

That is a fully working integration — the widget fetches its Evervault encryption IDs from Blaze automatically. Everything else below is optional.

Advanced — overriding the Evervault IDs. By default the widget loads Blaze's public Evervault teamId/appId from GET /v1/checkout/config. To pin specific values (e.g. while testing against a custom backend), pass them explicitly:

<BlazeCheckout
  paymentLinkCode={paymentLinkCode}
  evervaultTeamId={process.env.NEXT_PUBLIC_EVERVAULT_TEAM_ID!}
  evervaultAppId={process.env.NEXT_PUBLIC_EVERVAULT_APP_ID!}
  onComplete={(event) => window.location.href = "/success"}
/>

The paymentLinkCode is the bare short code (pl_ImsNk4rl), not the share URL. Passing the full https://blze.at/pl_ImsNk4rl produces a request to GET /v1/checkout/pay/https://blze.at/pl_ImsNk4rl, which returns a 404. Pass only the pl_... code.

How auth works (no publishable key)

The widget never sends a client-side key of any kind. apiUrl defaults to https://api.blaze.money (production); point it at staging to test.

Features

• Stripe-like Appearance API — theme, variables, rules, label modes, input modes, animation toggle
• 3 built-in themes — default, night, flat
• 30 appearance variables — colors, typography, spacing, border radii, shadows
• 16 rule selectors with state variants (:focus, :hover, :disabled, :invalid, ::placeholder)
• Floating labels mode — single toggle, no extra markup needed
• Condensed input mode — compact layout for space-constrained UIs
• Express checkout — Apple Pay / Google Pay with automatic device detection
• Promo code input — apply, remove, success, and error states with async validation
• Internationalization — 4 locales (en, es, fr, pt), 58 translated strings
• Loading skeleton — graceful placeholder while the session loads
• Animated success screen — confirms payment with configurable auto-redirect
• 3DS authentication — modal overlay handled automatically
• Card brand detection — real-time BIN matching for Visa, Mastercard, Amex, Discover
• Analytics events — 7 event types via onEvent callback
• onReady callback — know exactly when the form is interactive
• Terms / consent text — configurable legal copy below the pay button
• Full accessibility — ARIA attributes, keyboard navigation, focus trapping
• CSS class hooks — every element has a blaze-* class for external styling
• CDN / IIFE build — embed on Shopify, WordPress, or vanilla HTML without a bundler
• PCI DSS SAQ A-EP compliant — card data encrypted by Evervault before touching any server
• Output formats — CJS, ESM, IIFE, full TypeScript declarations

Appearance API

The appearance prop gives you full control over styling without writing CSS.

<BlazeCheckout
  // ... required props
  appearance={{
    theme: "flat", // start from a built-in base
    variables: {
      colorPrimary: "#0066ff",
      colorBackground: "#fafafa",
      colorText: "#1a1a1a",
      fontFamily: "'Inter', sans-serif",
      borderRadius: "8px",
      spacingUnit: "14px",
    },
    rules: {
      ".Input": {
        border: "1px solid #e2e8f0",
        ":focus": { borderColor: "#0066ff", boxShadow: "0 0 0 2px rgba(0,102,255,0.15)" },
      },
      ".Button": {
        borderRadius: "8px",
        fontWeight: "600",
        textTransform: "uppercase",
      },
      ".Label": { fontSize: "13px", fontWeight: "500" },
      ".Error": { color: "#dc2626" },
    },
    labels: "floating", // "above" (default) | "floating"
    inputs: "condensed", // "default" | "condensed"
    disableAnimations: false,
  }}
/>

See docs/themes.md for the full variable reference, all 16 rule selectors, state variants, and visual examples.

Built-in Themes

Apply a theme and override individual variables:

appearance={{ theme: "night", variables: { colorPrimary: "#10b981" } }}

Express Checkout

Show Apple Pay and Google Pay buttons when available on the device:

<BlazeCheckout
  // ... required props
  wallets={{ applePay: true, googlePay: true }}
  onWalletClick={(wallet) => {
    console.log(`User chose: ${wallet}`) // "applePay" | "googlePay"
  }}
/>

Wallet buttons render only when the device/browser supports the payment method. No buttons appear on unsupported environments — no broken UI.

Promo Codes

Enable promo code entry with server-side validation:

<BlazeCheckout
  // ... required props
  onApplyPromo={async (code) => {
    const res = await fetch(`/api/promo/validate?code=${code}`)
    const data = await res.json()
    return {
      valid: data.valid,
      discount: data.valid ? data.discount : undefined, // e.g. "20% off"
      error: data.valid ? undefined : "Invalid code",
    }
  }}
  onRemovePromo={() => {
    // User cleared the promo code
  }}
  appliedPromoCode="SUMMER20"
  appliedPromoDiscount="20% off"
/>

Internationalization

Pass a locale prop to render all UI strings in the target language:

<BlazeCheckout
  // ... required props
  locale="es" // "en" | "es" | "fr" | "pt"
/>

All 58 user-facing strings (labels, placeholders, errors, buttons, success messages) are translated. The default is "en".

Events

The onEvent callback fires for granular lifecycle and interaction events:

<BlazeCheckout
  // ... required props
  onEvent={(event) => {
    analytics.track("blaze_checkout", event)
  }}
  onReady={() => {
    console.log("Checkout form is interactive")
  }}
/>

CDN / Non-React Usage

For Shopify, WordPress, or any site without a React build step, use the IIFE bundle:

<div id="blaze-checkout-root"></div>

<script src="https://cdn.blaze.money/react/latest/index.iife.js"></script>
<script>
  BlazeCheckout.render(document.getElementById("blaze-checkout-root"), {
    paymentLinkCode: "pl_ImsNk4rl", // short code ONLY, not the share URL
    // evervaultTeamId / evervaultAppId are fetched from Blaze automatically;
    // only pass them to override the backend-provided values.
    onComplete: function (event) {
      window.location.href = "/thank-you?session=" + event.sessionId
    },
    appearance: {
      theme: "flat",
      variables: { colorPrimary: "#e11d48" },
    },
  })
</script>

The IIFE build bundles React internally — no additional script tags needed.

Advanced: Custom UI with Hooks

For full control over markup, use the exported hooks and primitives:

import {
  BlazeCheckoutProvider,
  useCheckoutSession,
  useCardPayment,
  CardSection,
  BillingAddressForm,
  SubmitButton,
} from "@blaze-money/react"
import { EvervaultProvider } from "@evervault/react"

function CustomCheckout({ sessionId }: { sessionId: string }) {
  const { session, loading } = useCheckoutSession(sessionId, "https://api.blaze.money")
  const { submit, status, errorMessage } = useCardPayment({
    sessionId,
    apiUrl: "https://api.blaze.money",
    onComplete: (event) => console.log("Paid!", event.sessionId),
  })

  if (loading) return <p>Loading...</p>

  return (
    <EvervaultProvider teamId="team_xxx" appId="app_xxx">
      <form onSubmit={(e) => { e.preventDefault(); submit() }}>
        <CardSection />
        <BillingAddressForm />
        <SubmitButton status={status}>
          Pay {session?.formattedAmount}
        </SubmitButton>
        {errorMessage && <p className="error">{errorMessage}</p>}
      </form>
    </EvervaultProvider>
  )
}

Props Reference

¹ Provide exactly one of paymentLinkCode (recommended, for real payments) or sessionId (checkout-session mode).

Troubleshooting

Documentation

• docs/themes.md — Full Appearance API reference (all 30 variables, 16 rule selectors, state variants)
• docs/features.md — Detailed feature documentation (express checkout, promo codes, i18n, 3DS, success screen)
• docs/integration-checklist.md — Step-by-step go-live checklist
• docs/pci-compliance.md — PCI DSS SAQ A-EP compliance details
• examples/gallery.html — Interactive visual playground with all themes and features

Security

Card numbers and CVCs are encrypted by Evervault inside the browser before any network request leaves the page. Neither your server nor Blaze's API ever sees raw card data — only Evervault-encrypted ciphertext. This architecture qualifies you for PCI DSS SAQ A-EP, the lightest compliance level for merchants that embed payment forms.

See docs/pci-compliance.md for the full compliance model and your responsibilities.

License

MIT