Checkout UI Components

@mvs/mvs-pay-ui is the published React component library that wraps Hyperswitch’s HyperLoader.js Web SDK with MVS theming. It ships the browser-side surface of MVS Pay: embedded checkout, tokenize-only forms, hosted-link anchors, a saved-cards management widget, and an MVS-specific instant-payout destination picker.

The package lives at packages/mvs-pay-ui/. Its public surface is re-exported from packages/mvs-pay-ui/src/index.ts. It pairs with @mvs/mvs-pay-sdk on the server, which mints the client_secret (and the sdk_authorization token) that each widget needs before it can render.

Package at a glance

The five exported components and their HyperLoader backing primitives:

Note that only three of the five components actually touch HyperLoader. <MvsPayCheckoutLink> is a thin styled anchor, and <MvsPayInstantPayoutPicker> is an MVS-specific presentational component over PayoutMethod rows.

How tokenization keeps the host page out of PCI scope

The whole point of mounting HyperLoader rather than building card fields yourself is PCI scope reduction. Raw PAN / CVV never enter the host page’s DOM, JS heap, or network requests.

Concretely:

1. Server mints the secret. Your backend calls mvsPay.payments.create(...) (or payment-method-sessions for the saved-cards widget) with the secret API key. The browser only ever receives a scoped client_secret / sdk_authorization token.
2. The publishable key is public. Hyper(publishableKey) takes the publishable key (NEXT_PUBLIC_HYPERSWITCH_PUBLISHABLE_KEY) — it is safe to ship to the browser and intentionally has no charge-authorizing power on its own.
3. Card fields render inside HyperLoader’s iframe. The host page only renders an empty container <div>; HyperLoader injects the sensitive fields into a cross-origin iframe it controls. Sensitive data is tokenized by Hyperswitch and never crosses back into the host page.

The publishable key

All HyperLoader-backed components take a publishableKey: string prop. In the apps/mvs-pay Next.js app this is sourced from:

$
# apps/mvs-pay/.env.example
$
# Per-merchant publishable key surfaced to the browser via @mvs/mvs-pay-ui.
$
NEXT_PUBLIC_HYPERSWITCH_PUBLISHABLE_KEY=

The NEXT_PUBLIC_ prefix is what makes it available to client-side code. It is per-merchant, so a multi-tenant host must resolve the right key for the active merchant before rendering. See Environment Variables for the complete list.

The HyperLoader runtime loader

All HyperLoader-backed components share a single loader, loadHyperLoader(), defined in packages/mvs-pay-ui/src/hyper-loader.ts. It injects one <script> tag (id mvs-pay-hyperloader) so that multiple widgets on the same page reuse the same SDK instance.

Key behaviors to know when debugging:

• Idempotent. Concurrent callers share one in-flight promise (pending). If window.Hyper is already present, it resolves immediately.
• Browser-only. Called server-side (no window), it rejects with HyperLoader can only run in a browser environment. This is the failure you’ll see if a component is rendered during SSR without a client boundary.
• Default script source: https://beta.hyperswitch.io/v1/HyperLoader.js. Override per component via the scriptSrc prop (e.g. a self-hosted bundle).
• Rejection is not cached. A transient script-load failure nulls out the cached promise so the next render retries, rather than permanently breaking every widget until a full reload.
• Late-listener guard. If the script tag already exists (HMR re-eval, StrictMode remount, a duplicate bundled copy), the loader settles from current state instead of attaching a listener that would never fire — it resolves if window.Hyper is present, otherwise rejects.

<MvsPayCheckout>

Embedded one-time checkout. Mounts HyperLoader’s payment widget into a unique container (derived from useId(), so multiple checkouts can coexist on one page) and cleans up on unmount. Source: packages/mvs-pay-ui/src/components/MvsPayCheckout.tsx.

Obtain clientSecret server-side via mvsPay.payments.create(...) before rendering.

Props

Submit & wallet composition

The component does not render its own submit button — you wire one through renderSubmit, which receives submit() and an isReady flag. submit() calls hyper.confirmPayment({ widgets, confirmParams, redirect: "if_required" }):

• If the result has error, onError fires with result.error.message ?? "Payment failed".
• Otherwise onSuccess fires. The raw HyperConfirmResult is always returned to the caller.
• Calling submit() before the widget mounts throws "[mvs-pay-ui] checkout not ready" and fires onError.

The wallets block is composed in this order (last wins): walletReturnUrl from returnUrl, then googlePay.merchantId from googlePayMerchantId, then any wallets on your paymentElementOptions. So paymentElementOptions.wallets is the ultimate override. See Wallets & Click to Pay.

<MvsPayPaymentMethodForm>

Tokenize-only flow: save a payment method without immediately charging. Wraps HyperLoader’s paymentMethods widget. Use it to save a card on a customer profile, capture a payout method, or pre-authorize a card-on-file agreement. Source: packages/mvs-pay-ui/src/components/MvsPayPaymentMethodForm.tsx.

Props

<MvsPaySavedCardsWidget>

Customer-facing payment-method management. Mounts HyperLoader’s paymentMethodsManagement widget so a logged-in customer can list, select, and delete their saved methods (cards, wallets, bank-account on file). Source: packages/mvs-pay-ui/src/components/MvsPaySavedCardsWidget.tsx.

Unlike checkout, this widget is initialised with an sdkAuthorization token (not a per-payment clientSecret). The token is minted server-side via the extensions-service proxy POST /v1/payment-method-sessions (apps/mvs-pay-extensions/src/routes/payment-method-sessions.ts), which forwards to Hyperswitch’s endpoint of the same name and scopes the session to a business profile via x-profile-id. See Extensions Service and the Connector Onboarding runbook (M27).

Props

The event payloads from HyperLoader are loosely typed (unknown[]); the component defensively extracts the id from any of paymentMethodId, payment_method_id, or id, or a bare string argument.

<MvsPayCheckoutLink>

A thin styled anchor that opens a Hyperswitch hosted-checkout URL. Use it for a no-JS share-link flow rather than embedding a widget. It does not load HyperLoader. Source: packages/mvs-pay-ui/src/components/MvsPayCheckoutLink.tsx.

Props

1
import { MvsPayCheckoutLink } from "@mvs/mvs-pay-ui";
2
3
<MvsPayCheckoutLink href={paymentLink.url}>
4
  Pay your invoice
5
</MvsPayCheckoutLink>

Generating the hosted URL is a server concern — see Payment Links.

<MvsPayInstantPayoutPicker>

MVS-specific, not a HyperLoader widget. Renders a radiogroup of saved payout destinations (PayoutMethod rows — bank accounts / debit cards) and emits the selected id via onSelect. It is purely presentational: fetching the methods is the caller’s job (use mvsPay.payoutMethods.list() or a server action that proxies it). Source: packages/mvs-pay-ui/src/components/MvsPayInstantPayoutPicker.tsx. See Payouts & Instant Payouts.

Props

Each MvsPayInstantPayoutPickerOption has id, optional type, brand, lastFour, name, verified, disabled (plus arbitrary extras). The default row renders brand/type ····lastFour, an optional name, and a Verified/Unverified badge. Rows use the ARIA role="radio" pattern inside a role="radiogroup" (a native <input type="radio"> can’t host the badge children).

Plaid Link integration (Phase 5 / M24, opt-in)

When the plaid prop is supplied, the “Link a bank account” / “Add another account” buttons drive react-plaid-link’s usePlaidLink hook instead of calling onAddNewAccount:

MvsPayInstantPayoutPickerPlaidConfig:

Both fetches use credentials: "include". The button label reflects state (“Preparing Plaid…”, “Linking…”). The link token is fetched on demand (not on mount); the usePlaidLink hook only opens once a token loads. End-to-end provisioning is documented in the Plaid Link runbook.

Usage example: embedded checkout

A minimal Next.js (App Router) integration. The server mints the secret; the client renders the widget.

1
// app/checkout/page.tsx (Server Component)
2
import { mvsPay } from "../../../../lib/mvs-pay"; // your @mvs/mvs-pay-sdk instance
3
import { CheckoutClient } from "./checkout-client";
4
5
export default async function CheckoutPage() {
6
  const payment = await mvsPay.payments.create({
7
    amount: 4200,
8
    currency: "USD",
9
    // ...customer, metadata, etc.
10
  });
11
12
  return (
13
    <CheckoutClient
14
      publishableKey={process.env.NEXT_PUBLIC_HYPERSWITCH_PUBLISHABLE_KEY!}
15
      clientSecret={payment.clientSecret}
16
    />
17
  );
18
}

1
"use client";
2
import { useState } from "react";
3
import { MvsPayCheckout } from "@mvs/mvs-pay-ui";
4
5
export function CheckoutClient({
6
  publishableKey,
7
  clientSecret,
8
}: {
9
  publishableKey: string;
10
  clientSecret: string;
11
}) {
12
  const [submitting, setSubmitting] = useState(false);
13
14
  return (
15
    <MvsPayCheckout
16
      publishableKey={publishableKey}
17
      clientSecret={clientSecret}
18
      layout="tabs"
19
      returnUrl="https://pay.mvspay.io/checkout/complete"
20
      googlePayMerchantId={process.env.NEXT_PUBLIC_GOOGLE_PAY_MERCHANT_ID}
21
      onSuccess={(result) => console.log("paid", result.status)}
22
      onError={(err) => console.error(err.message)}
23
      renderSubmit={({ submit, isReady }) => (
24
        <button
25
          type="button"
26
          disabled={!isReady || submitting}
27
          onClick={async () => {
28
            setSubmitting(true);
29
            try {
30
              await submit();
31
            } finally {
32
              setSubmitting(false);
33
            }
34
          }}
35
        >
36
          {submitting ? "Processing…" : "Pay $42.00"}
37
        </button>
38
      )}
39
    />
40
  );
41
}

Type exports

packages/mvs-pay-ui/src/index.ts also re-exports the HyperLoader type bindings and the loader itself, so you can type custom escape-hatch options or call HyperLoader directly:

1
import {
2
  loadHyperLoader,
3
  type HyperAppearance,
4
  type HyperConfirmResult,
5
  type HyperConfirmPaymentInput,
6
  type HyperInstance,
7
  type HyperWidgets,
8
  type HyperPaymentElementOptions,
9
  type HyperPaymentMethodsManagementOptions,
10
  type LoadHyperLoaderOptions,
11
} from "@mvs/mvs-pay-ui";

These are hand-written bindings over HyperLoader (packages/mvs-pay-ui/src/hyper-loader.ts), not generated from an upstream package — most option bags carry an open [k: string]: unknown index so you can pass through fields the bindings don’t enumerate.

Where to go next

For request/response shapes of the endpoints that back these widgets, see the API Reference tab.