Skip to main content

Vanilla widget

Overview​

<openhive-pay> is a framework-agnostic custom element. It works with any framework (Vue, Angular, Svelte, …) or plain HTML.

It handles:

  • Payment form rendering
  • Payment request creation
  • Success callbacks

For the React wrapper with typed props, see React widget.

Installation​

npm install @openhive-eu/payment

Styling​

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

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

Theming​

The widget exposes CSS custom properties on the openhive-pay element. Override them to match your brand:

openhive-pay {
  --pay-primary: #7c3aed;
  --pay-primary-foreground: #ffffff;
  --pay-radius: 0.5rem;
}
VariableDefault (light)Description
--pay-primaryoklch(54.1% .281 293.009)Primary action color
--pay-primary-foregroundoklch(96.9% .016 293.756)Text on primary background
--pay-backgroundoklch(100% 0 0)Widget background
--pay-foregroundoklch(14.1% .005 285.823)Default text color
--pay-mutedoklch(96.7% .001 286.375)Muted surface (skeleton, disabled)
--pay-muted-foregroundoklch(55.2% .016 285.938)Muted text
--pay-accentoklch(96.7% .001 286.375)Hover / accent surface
--pay-accent-foregroundoklch(21% .006 285.885)Text on accent surface
--pay-borderoklch(92% .004 286.32)Border color
--pay-inputoklch(92% .004 286.32)Input border color
--pay-ringoklch(70.2% .183 293.541)Focus ring color
--pay-destructiveoklch(57.7% .245 27.325)Error / destructive color
--pay-radius0.65remBorder radius

For dark mode, wrap the overrides in .pay-dark:

.pay-dark openhive-pay {
  --pay-background: oklch(14.1% 0.005 285.823);
  --pay-foreground: oklch(98.5% 0 0);
}

Usage examples​

Standard​

Loading…
<!-- Bundler: import the stylesheet once in your app entry point -->
<!-- <link rel="stylesheet" href="node_modules/@openhive-eu/payment/dist/styles.css"> -->
<!-- or via JS: import "@openhive-eu/payment/styles.css"; -->

<script type="module">
  import "@openhive-eu/payment"; // registers <openhive-pay>
</script>

<openhive-pay
  token="pk_xxx"
  default-amount="5000"
  default-reference="ORDER-12345"
  product-name="Abonnement Premium"
  customer-name="John Doe"
  customer-email="john.doe@example.com"
  locale="en"
></openhive-pay>

Modal / dialog​

Loading…
<button id="open-btn">Open Payment Modal</button>

<dialog id="payment-dialog">
  <button id="close-btn">Close</button>
  <openhive-pay
    token="pk_xxx"
    default-amount="5000"
    default-reference="ORDER-12345"
    product-name="Abonnement Premium"
    customer-name="John Doe"
    customer-email="john.doe@example.com"
    locale="en"
  ></openhive-pay>
</dialog>

<script type="module">
  import "@openhive-eu/payment"; // registers <openhive-pay>

  const dialog = document.getElementById("payment-dialog");
  document
    .getElementById("open-btn")
    .addEventListener("click", () => dialog.showModal());
  document
    .getElementById("close-btn")
    .addEventListener("click", () => dialog.close());
</script>

Custom payment methods​

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

note

payClient is a JavaScript property, not an HTML attribute. It must be set via JS after the element is available.

<openhive-pay
  id="pay-widget"
  token="pk_xxx"
  default-amount="5000"
  default-reference="ORDER-12345"
  product-name="Abonnement Premium"
  customer-name="John Doe"
  customer-email="john.doe@example.com"
  locale="en"
></openhive-pay>

<script type="module">
  import "@openhive-eu/payment"; // registers <openhive-pay>

  /**
   * @typedef {{ id: string, name: string, code: string, provider: string, description: string, logoUrl: string }} PaymentMethod
   * @type {{ getPaymentMethods: () => Promise<PaymentMethod[]> }}
   */
  const customPayClient = {
    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 widget = document.getElementById("pay-widget");
  widget.payClient = customPayClient;
</script>

API​

NameTypeDescription
token requiredStringOpenHive token "pk_xxx" used to retrieve the payment methods configuration.
default-referenceStringPre-fills the reference field. Links the request to an order (e.g., "ORDER-1234").
default-amountStringPre-fills the amount field. Value is in cents as a string (e.g., "5000" = €50.00).
read-only-amountBoolean (presence)Locks the amount field to default-amount. Set the attribute with an empty string to enable (e.g., read-only-amount="").
customer-nameStringPre-fills the customer name.
customer-emailStringPre-fills the customer e-mail.
customer-phoneStringPre-fills the customer phone number.
localeStringUI language. Supported values: "fr" (default), "en". Controls all labels, error messages, and success screen text.
api-urlStringBase URL of the payment API. Defaults to the OpenHive production endpoint.
currencyStringISO 4217 currency code (default: "EUR").
product-nameStringProduct label shown on the Stripe checkout page and customer receipts. Falls back to default-reference if omitted. Has no effect on Fintecture.
pay-client-refStringName of a window global implementing { getPaymentMethods(): Promise<PaymentMethod[]> }. Takes priority over the default API client. Useful for CDN usage where setting a JS property has timing constraints.