@snap-pay/react

React bindings for SNAP Elements - provider, hooks, and component wrappers.

pnpm add @snap-pay/js @snap-pay/elements @snap-pay/react

Usage

import { Snap } from "@snap-pay/js";
import "@snap-pay/elements"; // side effect: registers every element
import {
  SnapProvider,
  PaymentElement,
  BillingAddressElement,
  CustomerElement,
  useSnap,
  useElements,
  useClientSecret,
} from "@snap-pay/react";

const snap = new Snap(process.env.NEXT_PUBLIC_SNAP_PK!);

export function CheckoutPage({ clientSecret }: { clientSecret: string }) {
  return (
    <SnapProvider snap={snap} clientSecret={clientSecret}>
      <CustomerElement />
      <BillingAddressElement defaultCountry="Somalia" />
      <PaymentElement />
      <ConfirmButton />
    </SnapProvider>
  );
}

function ConfirmButton() {
  const snap = useSnap();
  const elements = useElements();
  const clientSecret = useClientSecret();
  return (
    <button
      onClick={async () => {
        const result = await snap.confirmPayment({ elements, clientSecret });
        if (result.status === "succeeded") window.location.href = "/thanks";
      }}
    >
      Pay
    </button>
  );
}

Components

Every wrapper accepts the standard event props (onReady, onChange, onFocus, onBlur, onFailed) plus style and className for the outer container.

| Component | Notes | |---|---| | <PaymentElement /> | Umbrella - auto-picks Wallet + Card | | <WalletElement /> | Mobile-wallet radio buttons | | <CardElement /> | Card fields inside a cross-origin iframe. Sandbox only (see below) | | <ExpressCheckoutElement /> | Prominent one-tap buttons; adds onSubmit for the click event | | <PaymentMethodSelector /> | Tabbed Wallet/Card switcher | | <BillingAddressElement defaultCountry={...} /> | Address form | | <CustomerElement /> | Name / email / phone | | <QrElement /> | QR code for the hosted checkout URL; onChange fires with complete: true when paid, onFailed on cancel or expiry |

Also exported: <QrCode /> (standalone QR image), <ThreeDsChallenge /> (3-D Secure challenge iframe) and <MastercardCardElement />, which is fail-closed: it renders a notice and calls onError instead of card inputs.

Live card payments

Live card tokenization in Elements is not available yet. <CardElement /> issues sandbox tokens only, and confirmPayment throws for a card selection under a pk_live_ key. For live card payments, redirect the customer to SNAP-hosted checkout (the checkout session URL). Wallet Elements work in live mode.

Next.js

The package ships a "use client" directive, so it can be imported from App Router server components; the components themselves render on the client.

Hooks

• useSnap() - the Snap instance from the provider
• useElements() - the shared Elements handle
• useClientSecret() - the client secret

All three throw if called outside a <SnapProvider>.

License

MIT