Skip to main content

React widget

Supported React versions

This wrapper requires React ≥ 18.2.

Overview​

<Payment> is a thin React wrapper around the <openhive-pay> custom element. It exposes the same features through camelCase props and React callback functions, with full TypeScript support.

It handles:

  • Payment form rendering
  • Payment request creation
  • Success callbacks

For framework-agnostic usage, see Vanilla widget.

Installation​

npm install @openhive-eu/payment

Styling​

Import the stylesheet once in your application entry point (e.g. main.tsx, App.tsx):

import "@openhive-eu/payment/styles.css";

Then import the component wherever you need it:

import { Payment } from "@openhive-eu/payment/react";

Theming​

The widget's appearance is controlled via CSS custom properties on the openhive-pay element:

openhive-pay {
  --pay-primary: #7c3aed;
  --pay-primary-foreground: #ffffff;
  --pay-radius: 0.5rem;
}

See Custom element → Theming for the full variable reference.

Usage examples​

Standard​

Loading…
import "@openhive-eu/payment/styles.css"; // import once in your app entry
import { Payment } from "@openhive-eu/payment/react";

const MyPaymentPage = () => (
  <Payment
    token="pk_xxx"
    defaultReference="ORDER-12345"
    defaultAmount="5000"
    productName="Abonnement Premium"
    customerName="John Doe"
    customerEmail="john.doe@example.com"
    locale="en"
    onRequestToPay={(requestToPay) => {
      // Send the payment request to your backend to process the payment
      console.log(requestToPay);
    }}
  />
);

export default MyPaymentPage;

Modal / dialog​

Loading…
import React, { useRef } from "react";
import "@openhive-eu/payment/styles.css"; // import once in your app entry
import { Payment } from "@openhive-eu/payment/react";

const MyPaymentModal = () => {
  const dialogRef = useRef(null);

  const handleRequestToPay = (requestToPay) => {
    // Send the payment request to your backend to process the payment
    console.log(requestToPay);
  };

  return (
    <>
      <button onClick={() => dialogRef.current.showModal()}>
        Open Payment Modal
      </button>
      <dialog ref={dialogRef}>
        <button onClick={() => dialogRef.current.close()}>Close</button>
        <Payment
          token="pk_xxx"
          defaultReference="ORDER-12345"
          defaultAmount="5000"
          productName="Abonnement Premium"
          customerName="John Doe"
          customerEmail="john.doe@example.com"
          locale="en"
          onRequestToPay={handleRequestToPay}
        />
      </dialog>
    </>
  );
};

export default MyPaymentModal;

Custom payment methods​

Override the payment client to supply custom payment methods or bypass the default fetching logic. See Get payment methods API.

import "@openhive-eu/payment/styles.css"; // import once in your app entry
import { Payment } from "@openhive-eu/payment/react";
import type { PayClientInterface } from "@openhive-eu/payment";

const customPayClient: PayClientInterface = {
  getPaymentMethods: async () => {
    const response = await fetch("/api/payment-methods", {
      headers: { Authorization: "Bearer <token>" },
    });
    if (!response.ok) throw new Error(`HTTP error! Status: ${response.status}`);
    return response.json();
  },
};

const MyControlledWidget = () => (
  <Payment
    token="pk_xxx"
    defaultReference="ORDER-12345"
    defaultAmount="5000"
    productName="Abonnement Premium"
    customerName="John Doe"
    customerEmail="john.doe@example.com"
    locale="en"
    payClient={customPayClient}
    onRequestToPay={(requestToPay) => {
      console.log(requestToPay);
    }}
  />
);

export default MyControlledWidget;

API​

NameTypeDescription
token requiredStringOpenHive token "pk_xxx" used to retrieve the payment methods configuration.
defaultReferenceStringPre-fills the reference field. Links the request to an order (e.g., "ORDER-1234").
defaultAmountStringPre-fills the amount field. Value is in cents as a string (e.g., "5000" = €50.00).
readOnlyAmountBooleanLocks the amount field to defaultAmount if true.
customerNameStringPre-fills the customer name.
customerEmailStringPre-fills the customer e-mail.
customerPhoneStringPre-fills the customer phone number.
localeStringUI language. Supported values: "fr" (default), "en". Controls all labels, error messages, and success screen text.
productNameStringProduct label shown on the Stripe checkout page and customer receipts. Falls back to defaultReference if omitted. Has no effect on Fintecture.
payClientObjectInject a custom payment client to override how payment methods are fetched. Useful for testing or custom backends. Must implement PayClientInterface.