Hashry Pay for Express + React

The four routes

Your server gets four routes. The page calls the first two. Hashry calls the last one.

Before you start

• A test key from the Hashry admin: the client ID and the client secret (hsk_test_…). See Set up in the Hashry admin.
• https://localhost:5173 added to both lists on the admin's Test Sandbox tab: Allowed return origins and Allowed embed origins.
• Node 22.12 or newer.
• A React + Vite app with TypeScript. To start a new one:

  npm create vite@latest my-shop -- --template react-ts
  cd my-shop

Step by step

1. Install the packages.

   # The server
   npm install express @hashrytech/pay-node
   npm install --save-dev tsx @types/express @types/node
   
   # The page
   npm install @hashrytech/pay-react
   npm install --save-dev @hashrytech/pay-build-guard @vitejs/plugin-basic-ssl

2. Add your settings. Create .env in the project folder. Put in your test key. PUBLIC_BASE_URL is the address of the page, not of the Express server: shoppers open the page.

   # Secrets. Server only: never commit this file, and never give these names
   # a public prefix (NEXT_PUBLIC_, VITE_, PUBLIC_).
   HASHRY_CLIENT_ID=your-client-id
   HASHRY_CLIENT_SECRET=hsk_test_...
   HASHRY_ENVIRONMENT=sandbox
   # You get this one when you set up webhooks (see Test and go live).
   HASHRY_WEBHOOK_SECRET=hwhsec_test_...
   
   # Not secret: the https address shoppers open. It must be on Allowed embed
   # origins and Allowed return origins in the Hashry admin.
   PUBLIC_BASE_URL=https://localhost:5173

3. Add your orders. This file stands in for your database. It keeps orders in memory and has one test order, test-order. Change JMD to your store's currency. Later, swap in your real database and keep the same functions.

   // server/shop.ts: your own orders database. This in-memory version is only for
   // trying things out: it forgets everything on restart. Use your real database.
   
   import { randomUUID } from "node:crypto";
   
   export interface Order {
     id: string;
     email: string;
     // Set by your server, never by the browser. A decimal string, for example "2500.00".
     amount: string;
     currency: string;
     // Only your server decides "paid".
     status: "unpaid" | "paid" | "review";
     // The last payment status your server got from Hashry.
     paymentStatus: string | null;
     paymentIntentUid: string | null;
     // Goes up when a payment expired or was canceled and a new one is needed.
     paymentNumber: number;
   }
   
   const orders = new Map<string, Order>();
   const handledEvents = new Set<string>();
   
   // A test order, so you can try the pay page at /orders/test-order/pay. Use your
   // store's currency. Delete it when you use your real database.
   orders.set("test-order", {
     id: "test-order",
     email: "shopper@example.com",
     amount: "2500.00",
     currency: "JMD",
     status: "unpaid",
     paymentStatus: null,
     paymentIntentUid: null,
     paymentNumber: 1,
   });
   
   export async function createOrder(email: string, amount: string, currency: string): Promise<Order> {
     const order: Order = {
       id: randomUUID(),
       email,
       amount,
       currency,
       status: "unpaid",
       paymentStatus: null,
       paymentIntentUid: null,
       paymentNumber: 1,
     };
     orders.set(order.id, order);
     return order;
   }
   
   export async function getOrder(id: string): Promise<Order | null> {
     return orders.get(id) ?? null;
   }
   
   export async function saveOrder(order: Order): Promise<void> {
     orders.set(order.id, order);
   }
   
   export async function isEventHandled(eventId: string): Promise<boolean> {
     return handledEvents.has(eventId);
   }
   
   // In a real database, save the event ID and the order change in one transaction.
   export async function markEventHandled(eventId: string): Promise<void> {
     handledEvents.add(eventId);
   }

4. Add the payment steps. This file starts, renews and confirms payments, and applies webhooks. Copy it as it is.

   // server/payments.ts: the payment steps. The same file works in Next.js, Express and
   // SvelteKit. Each framework passes in its own Hashry client.
   
   import {
     ApiConnectionError,
     ApiError,
     type Hashry,
     type PaymentIntent,
     type WebhookEvent,
   } from "@hashrytech/pay-node";
   import { getOrder, isEventHandled, markEventHandled, saveOrder, type Order } from "./shop";
   
   // The four values the page needs. Nothing here is secret.
   export interface CheckoutSession {
     embed_url: string;
     transaction_uid: string;
     status_url: string;
     status_token: string;
   }
   
   // What the browser may see about an order.
   export function orderView(order: Order) {
     return { id: order.id, status: order.status, payment_status: order.paymentStatus };
   }
   
   // A card form can still be shown (or renewed) in these states.
   const OPEN = new Set(["awaiting_customer", "redirect_issued"]);
   
   function cents(amount: string): number | null {
     const match = /^(\d+)(?:\.(\d{1,2}))?$/.exec(amount.trim());
     if (!match) return null;
     return Number(match[1]) * 100 + Number((match[2] ?? "0").padEnd(2, "0"));
   }
   
   // Save what Hashry says. "paid" only when the payment succeeded for this
   // order's exact amount, currency and reference. A paid order stays paid.
   async function record(order: Order, intent: PaymentIntent): Promise<Order> {
     order.paymentStatus = intent.status;
     if (order.status !== "paid") {
       if (intent.status === "succeeded") {
         const amount = cents(intent.amount);
         const matches =
           amount !== null &&
           amount === cents(order.amount) &&
           intent.currency === order.currency &&
           intent.external_reference === order.id;
         if (!matches) console.warn(`Payment ${intent.uid} does not match order ${order.id}.`);
         order.status = matches ? "paid" : "review";
       } else if (intent.status === "payment_review") {
         order.status = "review";
       }
     }
     await saveOrder(order);
     return order;
   }
   
   // Start the payment, renew a card form that expired, or retry after a decline.
   // Returns null when there is no card form to show (paid, or being checked).
   // `origin` is your shop's https origin, for example https://shop.example.com.
   export async function startPayment(
     hashry: Hashry,
     order: Order,
     origin: string,
   ): Promise<CheckoutSession | null> {
     if (order.status !== "unpaid") return null;
     const embedded = { presentation: "embedded" as const, embed_origin: origin };
     // The answer holds embed_url and status_token. Never log it whole.
     let intent: PaymentIntent | null = null;
   
     if (order.paymentIntentUid) {
       const current = await hashry.paymentIntents.retrieve(order.paymentIntentUid);
       const latest = Math.max(1, ...current.attempts.map((a) => a.attempt_number));
       if (current.status === "requires_payment_method") {
         // Every card the frame allowed was declined (it takes another card by itself
         // until then). Start a new attempt on the same payment, with a new key.
         intent = await hashry.paymentIntents.createAttempt(current.uid, embedded, {
           idempotencyKey: `order-${order.id}-attempt-${latest + 1}`,
         });
       } else if (OPEN.has(current.status) && latest > 1) {
         // A retry's card form expired unused. Its own key again renews it.
         intent = await hashry.paymentIntents.createAttempt(current.uid, embedded, {
           idempotencyKey: `order-${order.id}-attempt-${latest}`,
         });
       } else if (current.status === "expired" || current.status === "canceled") {
         // Over, and nothing was charged. Start a new payment with a new key.
         order.paymentIntentUid = null;
         order.paymentNumber += 1;
       } else if (!OPEN.has(current.status)) {
         // succeeded, processing or payment_review: no new card form.
         await record(order, current);
         return null;
       }
     }
   
     // One key per order and payment number. Sending it again is safe: Hashry
     // returns the same payment, with a fresh card form if the old one expired
     // unused. A replay must send the same details, so they come from the order.
     intent ??= await hashry.paymentIntents.create(
       {
         amount: order.amount,
         currency: order.currency,
         description: `Order ${order.id}`,
         external_reference: order.id,
         payer: { email: order.email },
         return_url: `${origin}/api/orders/${order.id}/return`,
         cancel_url: `${origin}/cart`,
         ...embedded,
       },
       { idempotencyKey: `order-${order.id}-pay-${order.paymentNumber}` },
     );
     order.paymentIntentUid = intent.uid;
     order.paymentStatus = intent.status;
     await saveOrder(order);
   
     if (!intent.embed_url || !intent.transaction_uid || !intent.status_url || !intent.status_token) {
       // This card form was already used. Ask the gateway how it ended.
       await record(order, await hashry.paymentIntents.refresh(intent.uid));
       return null;
     }
     return {
       embed_url: intent.embed_url,
       transaction_uid: intent.transaction_uid,
       status_url: intent.status_url,
       status_token: intent.status_token,
     };
   }
   
   // Ask Hashry now. refresh checks with the gateway first, so it is right even
   // when a webhook is late. Call it before you fulfil an order.
   export async function confirmPayment(hashry: Hashry, order: Order): Promise<Order> {
     if (order.status === "paid" || !order.paymentIntentUid) return order;
     return record(order, await hashry.paymentIntents.refresh(order.paymentIntentUid));
   }
   
   // Apply a verified webhook once. The event is a cue: the payment read from
   // Hashry is the truth.
   export async function handleWebhookEvent(hashry: Hashry, event: WebhookEvent): Promise<void> {
     if (await isEventHandled(event.id)) return;
     if (event.paymentIntentUid) {
       const intent = await hashry.paymentIntents.retrieve(event.paymentIntentUid);
       const order = intent.external_reference ? await getOrder(intent.external_reference) : null;
       if (order) await record(order, intent);
     }
     await markEventHandled(event.id);
   }
   
   // True for a failed Hashry call: a refusal from the API, or no answer at all.
   export function isHashryCallError(error: unknown): error is ApiError | ApiConnectionError {
     return error instanceof ApiError || error instanceof ApiConnectionError;
   }
   
   // A JSON error for the browser. Hashry's error codes are safe to show.
   export function errorResponse(error: unknown): {
     status: number;
     body: { error: string; retry: boolean };
   } {
     if (!isHashryCallError(error)) throw error;
     // The SDK's error messages never hold a secret, a token or an embed_url.
     console.warn(error.message);
     // retry: true means calling the same route again is safe and needed. It
     // sends the same idempotency key, so no second payment can start.
     if (error instanceof ApiConnectionError) {
       return { status: 503, body: { error: "hashry_unreachable", retry: true } };
     }
     return { status: 502, body: { error: error.code, retry: error.outcomeUnknown } };
   }

5. Add the server. It creates the Hashry client once, when it starts, and adds the four routes.

   // server/index.ts: an Express 5 server for a React + Vite shop.
   // Run it with: npx tsx --env-file=.env server/index.ts
   import express from "express";
   import {
     Hashry,
     WebhookError,
     verifyWebhook,
     type Environment,
     type WebhookEvent,
   } from "@hashrytech/pay-node";
   import {
     confirmPayment,
     errorResponse,
     handleWebhookEvent,
     isHashryCallError,
     orderView,
     startPayment,
   } from "./payments";
   import { getOrder } from "./shop";
   
   // One client for the whole server. It caches the access token.
   const hashry = new Hashry({
     clientId: process.env.HASHRY_CLIENT_ID ?? "",
     clientSecret: process.env.HASHRY_CLIENT_SECRET ?? "",
     // The SDK refuses anything but "sandbox" or "live", and a key for the other mode.
     environment: (process.env.HASHRY_ENVIRONMENT || "sandbox") as Environment,
   });
   // During a secret rotation, set both. The new one goes first.
   const webhookSecrets = [process.env.HASHRY_WEBHOOK_SECRET, process.env.HASHRY_WEBHOOK_SECRET_PREVIOUS]
     .map((value) => value?.trim() ?? "")
     .filter(Boolean);
   // Your shop's https origin, where shoppers see the page. In development this
   // is the Vite dev server, for example https://localhost:5173.
   const SITE = (process.env.PUBLIC_BASE_URL ?? "").replace(/\/+$/, "");
   if (!SITE.startsWith("https://")) throw new Error("Set PUBLIC_BASE_URL to your https origin.");
   
   const app = express();
   app.disable("x-powered-by");
   
   // The webhook route comes first. It needs the raw bytes, so it uses
   // express.raw() (req.body is a Buffer) and must not go through express.json().
   app.post("/api/webhooks/hashry", express.raw({ type: "*/*", limit: "1mb" }), async (req, res) => {
     let event: WebhookEvent;
     try {
       event = verifyWebhook(req.body, {
         // The full path of the URL you gave Hashry. The query string is ignored.
         // Not req.path: inside a router, it leaves out the mount path.
         path: req.originalUrl,
         headers: req.headers,
         secrets: webhookSecrets,
       });
     } catch (error) {
       if (error instanceof WebhookError) {
         res.status(400).json({ error: error.reason });
         return;
       }
       throw error;
     }
     try {
       // Skips an event ID it has already handled.
       await handleWebhookEvent(hashry, event);
     } catch (error) {
       // Not applied. A non-2xx answer makes Hashry deliver it again.
       const { status, body } = errorResponse(error);
       res.status(status).json(body);
       return;
     }
     res.json({ ok: true });
   });
   
   app.use(express.json());
   
   // Start the payment, renew an expired card form, or retry after a decline.
   app.post("/api/orders/:id/payment", async (req, res) => {
     const order = await getOrder(req.params.id);
     if (!order) {
       res.status(404).json({ error: "order_not_found" });
       return;
     }
     try {
       res.json({ checkout: await startPayment(hashry, order, SITE) });
     } catch (error) {
       const { status, body } = errorResponse(error);
       res.status(status).json(body);
     }
   });
   
   // Confirm: ask Hashry now (refresh), then answer with this server's view of the order.
   app.post("/api/orders/:id/confirm", async (req, res) => {
     const order = await getOrder(req.params.id);
     if (!order) {
       res.status(404).json({ error: "order_not_found" });
       return;
     }
     try {
       res.json(orderView(await confirmPayment(hashry, order)));
     } catch (error) {
       const { status, body } = errorResponse(error);
       res.status(status).json(body);
     }
   });
   
   // The return_url. Ask Hashry, then send the shopper back to the pay page. It shows the result.
   app.get("/api/orders/:id/return", async (req, res) => {
     const order = await getOrder(req.params.id);
     if (!order) {
       res.status(404).json({ error: "order_not_found" });
       return;
     }
     try {
       await confirmPayment(hashry, order);
     } catch (error) {
       // The pay page checks again, and the webhook also brings the answer.
       if (!isHashryCallError(error)) throw error;
       console.warn(error.message);
     }
     res.redirect(303, `${SITE}/orders/${encodeURIComponent(order.id)}/pay`);
   });
   
   app.listen(8000, () => console.log("Shop server on http://localhost:8000"));

6. Add the card form component. It asks your server for a card form, shows it, and asks your server for the result.

   // src/Pay.tsx: the card form page.
   //
   // 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>
     );
   }

7. Add the pay page. Replace src/main.tsx with this. It shows the card form for the order in the address.

   // src/main.tsx: shows the pay page for /orders/<id>/pay.
   // Vite serves index.html for every path, so this runs on that address.
   import { StrictMode } from "react";
   import { createRoot } from "react-dom/client";
   import { Pay } from "./Pay";
   
   // /orders/<id>/pay gives <id>. If your app has a router, use it instead.
   const orderId = decodeURIComponent(location.pathname.split("/")[2] ?? "");
   
   createRoot(document.getElementById("root")!).render(
     <StrictMode>
       <h1>Pay for your order</h1>
       <Pay orderId={orderId} />
     </StrictMode>,
   );

8. Set up Vite. Replace vite.config.ts with this. It serves the page over https, adds the build guard, and passes /api to Express.

   // 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" },
     },
   });

9. Start both, each in its own terminal:

   # Terminal 1: the server, on http://localhost:8000
   npx tsx --env-file=.env server/index.ts
   
   # Terminal 2: the page, on https://localhost:5173
   npx vite

Check it works

1. Open https://localhost:5173/orders/test-order/pay.
2. Your browser warns that the connection is not private. That is your dev server's own certificate, so it is safe here. Choose to go on (in Chrome: Advanced, then Proceed).
3. The card form appears. Enter the test card 4012000000020071, any expiry date in the future, and 123 as the security code.
4. The page says "Checking your payment", then "Payment received. Thank you!". Your server asked Hashry, and Hashry said the payment succeeded. The order is now paid.

The test order can be paid once. To pay again, change test-order to a new ID in server/shop.ts, restart the server, and open the new address.

Something went wrong? See Troubleshooting.

How the code keeps payments safe

The code above already does all of this. Keep these rules if you change it.

• Your server sets the price. The amount and currency come from your own order. The page only says which order.
• Mark an order paid only when Hashry says so. That means the status is succeeded, and the amount, currency and external_reference match your order. If they don't match, hold the order for review.
• Each payment has its own idempotency key. The code uses order-<id>-pay-1. Sending the same key again is safe: you get the same payment back. The same key with different details gets 409 idempotency_conflict.
• When you get no answer, don't start a new payment. Repeat the call with the same key, or read the payment. The first call may have worked.
• Never log or store embed_url. It works like a password for one payment. Pass it to the page and forget it.
• A declined card needs nothing from your server. The card form asks for another card by itself, up to 3 cards. See Declines and retries.

Notes

• Express 5 passes errors from async handlers to its error handler. On Express 4, wrap each handler in try/catch.
• In production, serve the built page and the API from one https address. Set PUBLIC_BASE_URL to it, and add it to the live allowed origins.