@blaze-money/react

Drop-in React components for accepting payments with Blaze.

Quick Start

1. Create a checkout session (server-side)

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

const { id: sessionId } = await res.json()
// Return sessionId to your frontend

2. Embed the checkout (client-side)

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

export function CheckoutPage({ sessionId }: { sessionId: string }) {
  return (
    <BlazeCheckout
      sessionId={sessionId}
      publishableKey={process.env.NEXT_PUBLIC_BLAZE_PUBLISHABLE_KEY!}
      evervaultTeamId={process.env.NEXT_PUBLIC_EVERVAULT_TEAM_ID!}
      evervaultAppId={process.env.NEXT_PUBLIC_EVERVAULT_APP_ID!}
      onComplete={(event) => {
        console.log("Payment succeeded:", event.sessionId)
        window.location.href = "/success"
      }}
      onCancel={() => window.history.back()}
      appearance={{
        theme: "night",
        variables: { colorPrimary: "#6366f1", borderRadius: "12px" },
      }}
    />
  )
}

That is a fully working integration. Everything else below is optional.

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"), {
    sessionId: "ses_abc123",
    publishableKey: "pk_live_xxx",
    evervaultTeamId: "team_xxx",
    evervaultAppId: "app_xxx",
    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

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