Hashry Pay React component

# React 18 or 19
npm install @hashrytech/pay-react

# The build guard (Vite or webpack)
npm install --save-dev @hashrytech/pay-build-guard

// Pay.tsx: the card form page. In Next.js, add "use client"; as the first line.
//
// 1. Ask your server for a card form (embed_url, transaction_uid, status_url, status_token).
// 2. Show it with <HashryCheckout>. The page never sees card data or a key.
// 3. On "completed", show progress with pollStatus (display only), then ask
//    your server, which asks Hashry. Only your server's answer counts.
// 4. A declined card: the frame asks for another card itself (onDeclined).
//    Only when every card it allows is declined does "completed" end in
//    "declined", and "Try again" starts a new attempt.

import { useCallback, useEffect, useRef, useState } from "react";
import { HashryCheckout, isHashryPayError, pollStatus, type HashryPayError } from "@hashrytech/pay-react";

type CheckoutSession = {
  embed_url: string;
  transaction_uid: string;
  status_url: string;
  status_token: string;
};
type OrderView = { id: string; status: "unpaid" | "paid" | "review"; payment_status: string | null };
type Phase = "loading" | "card" | "checking" | "paid" | "declined" | "pending" | "review" | "error";

async function post<T>(path: string): Promise<T> {
  const response = await fetch(path, { method: "POST" });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return (await response.json()) as T;
}

export function Pay({ orderId }: { orderId: string }) {
  const [phase, setPhase] = useState<Phase>("loading");
  const [session, setSession] = useState<CheckoutSession | null>(null);
  const [statusText, setStatusText] = useState("");
  // A card is going through: no going back to the cart until it ends.
  const [locked, setLocked] = useState(false);
  const started = useRef(false);
  const polling = useRef<AbortController | null>(null);
  const base = `/api/orders/${encodeURIComponent(orderId)}`;

  // The answer that counts: your server asks Hashry (refresh).
  const confirm = useCallback(async () => {
    const order = await post<OrderView>(`${base}/confirm`);
    if (order.status === "paid") setPhase("paid");
    else if (order.status === "review") setPhase("review");
    else if (order.payment_status === "requires_payment_method") setPhase("declined");
    else setPhase("pending");
  }, [base]);

  // A first card form, a renewed one after it expired, or a new attempt after
  // a decline. Your server decides which. Calling it twice is safe.
  const loadCardForm = useCallback(async () => {
    setPhase("loading");
    try {
      const { checkout } = await post<{ checkout: CheckoutSession | null }>(`${base}/payment`);
      if (checkout) {
        setSession(checkout);
        setPhase("card");
      } else {
        // No card form to show: paid already, or the payment is being checked.
        await confirm();
      }
    } catch {
      setPhase("error");
    }
  }, [base, confirm]);

  useEffect(() => {
    // Strict mode runs effects twice in development. One request is enough.
    if (!started.current) {
      started.current = true;
      void loadCardForm();
    }
    return () => polling.current?.abort();
  }, [loadCardForm]);

  async function onCompleted() {
    // Not proof of payment. The frame only says it reached an outcome.
    if (!session) return;
    setLocked(false);
    setPhase("checking");
    const controller = new AbortController();
    polling.current = controller;
    try {
      // Display only. The status token reads this payment's status and nothing else.
      await pollStatus({
        statusUrl: session.status_url,
        statusToken: session.status_token,
        signal: controller.signal,
        timeoutMs: 60_000,
        onUpdate: (status) => setStatusText(status.status),
      });
    } catch (error) {
      if (isHashryPayError(error) && error.code === "aborted") return;
      // Polling is only a nicety. Ask your server either way.
    }
    try {
      await confirm();
    } catch {
      setPhase("error");
    }
  }

  function onError(error: HashryPayError) {
    // error.code is safe to log. The message never holds the embed_url or a token.
    console.error("Card form error:", error.code);
    setPhase("error");
  }

  return (
    <section>
      {!locked && <a href="/cart">Back to cart</a>}
      {phase === "loading" && <p>Loading the card form…</p>}
      {phase === "checking" && <p>Checking your payment{statusText ? ` (${statusText})` : ""}…</p>}
      {session && (phase === "card" || phase === "checking") && (
        <HashryCheckout
          embedUrl={session.embed_url}
          transactionUid={session.transaction_uid}
          // A card was sent. The bank may be charging it.
          onProcessing={() => setLocked(true)}
          // Declined: the frame shows the card form again by itself. Nothing to ask your server.
          onDeclined={() => setLocked(false)}
          // Too many tries in a short time. The frame says so and offers "Try again".
          onPaused={() => setLocked(false)}
          onCompleted={onCompleted}
          // The card form ran out before a card was sent. Ask your server for a new one.
          onExpired={() => void loadCardForm()}
          onError={onError}
        />
      )}
      {phase === "paid" && <p>Payment received. Thank you!</p>}
      {phase === "pending" && <p>Your payment is still being processed. Check your order soon.</p>}
      {phase === "review" && <p>We are checking your payment. We will email you.</p>}
      {phase === "declined" && (
        <>
          <p>Every card was declined. Nothing was charged.</p>
          <button onClick={() => void loadCardForm()}>Try again</button>
        </>
      )}
      {phase === "error" && (
        <>
          <p>Something went wrong. Try again.</p>
          <button onClick={() => void loadCardForm()}>Try again</button>
        </>
      )}
    </section>
  );
}

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import basicSsl from "@vitejs/plugin-basic-ssl";
import { hashryPayGuard } from "@hashrytech/pay-build-guard/vite";

export default defineConfig({
  plugins: [
    react(),
    // The card form shows only in https pages, even on localhost.
    // This gives the dev server a self-signed certificate.
    basicSsl(),
    // Fails the build if a Hashry secret or server code ends up in the page.
    hashryPayGuard(),
  ],
  server: {
    // The port is part of the origin you allow in the Hashry admin. Keep it fixed.
    port: 5173,
    strictPort: true,
    // Your own server (Express, FastAPI, ...), not Hashry's API.
    proxy: { "/api": "http://localhost:8000" },
  },
});

// CardForm.tsx: the same card form, in an element you own.
import { useHashryCheckout } from "@hashrytech/pay-react";

export function CardForm(props: { embedUrl: string; transactionUid: string; onCompleted: () => void }) {
  // Takes the same options as mount() in @hashrytech/pay.
  const { ref, openFullPage } = useHashryCheckout(props);
  return (
    <div className="card-form">
      <div ref={ref} />
      {/* Moves the payment to the full Hashry Pay page. False when there is no fallback yet. */}
      <button type="button" onClick={() => openFullPage()}>
        Open the payment page in full
      </button>
    </div>
  );
}

import { pollStatus } from "@hashrytech/pay-react"; // or "@hashrytech/pay-svelte"

const result = await pollStatus({
  statusUrl: session.status_url,
  statusToken: session.status_token, // starts with hst_
  timeoutMs: 60_000,
  onUpdate: (status) => console.log(status.status),
});
// result: { status, amount, currency, updated_at }. For display only.

// webpack.config.js (webpack 5)
import { HashryPayGuardPlugin } from "@hashrytech/pay-build-guard/webpack";

export default {
  // ...your settings
  plugins: [new HashryPayGuardPlugin()],
};