Payment component

Render native Lockerverse checkout for a catalog selection.

import { LockerversePayment } from "@lockerverse/react/payment";
import "@lockerverse/react/payment.css";

Required properties

Payment properties

type LockerversePaymentProps = {
  widget: UseLockerverseWidgetResult;
  selection: LockerversePaymentSelectionItem[];
  branding?: {
    accentColor?: string;
    imageUrl?: string | null;
    name: string;
  };
  metadata?: Record<string, string>;
  initialCustomFieldValues?: Record<string, boolean | string | string[]>;
  style?: LockerverseStyle;
  theme?: "dark" | "light";
  resumePayment?: {
    connectedAccountId: string | null;
    paymentReference: string;
  } | null;
  onPaymentComplete?: (payment: LockerversePaymentCompletion) => void;
  onPaymentRecoveryChange?: (recovery: LockerversePaymentRecovery | null) => void;
  onPaymentUncertain?: (payment: LockerversePaymentUncertain) => void;
};

The component also accepts <section> properties and className. See Theming for the shared typed CSS tokens.

Completion

import type { LockerversePaymentCompletion } from "@lockerverse/react/payment";

const widget = useLockerverseWidget({
  communitySlug: "your-community",
  widgetSlug: "your-widget",
});

const handlePaymentComplete = (payment: LockerversePaymentCompletion) => {
  const admissionItems = payment.lineItems?.filter(
    (item) => item.fulfillmentType === "event_admission"
  );
  console.info("Payment complete; admission item count", admissionItems?.length ?? 0);
};

<LockerversePayment
  onPaymentComplete={handlePaymentComplete}
  selection={selection}
  widget={widget}
/>

Use onPaymentComplete as the confirmed success signal. A direct completion includes the normalized customer email and authoritative lineItems. A completion recovered after reload has null for both fields.

Recovery

Store onPaymentRecoveryChange and pass it back through resumePayment after reload. Keep onPaymentUncertain unresolved.

Prefill custom fields

Pass configured field IDs to initialCustomFieldValues:

<LockerversePayment
  widget={widget}
  selection={selection}
  initialCustomFieldValues={{
    field_muw2q7vx_sf7r94: "Autographed basketball",
  }}
/>

The form reads these values when a checkout form starts. Buyers can edit them; parent re-renders and price refreshes do not overwrite their edits. To apply a new set of initial values, start a new form with a new React key. This also resets the other form inputs.

Text and textarea fields take strings. A checkbox takes a boolean. Radio and select fields take an option ID. Checkboxes and multi-select fields take arrays of option IDs. Unknown fields, wrong value types, and unknown options are ignored. Only fields for the selected products are used. Required-field validation and server validation still apply.

LockerverseDonateLauncher accepts the same property. For live control over individual values and a custom submission flow, use the payment primitives with the Core SDK.