Fungies JavaScript SDK

The Fungies JavaScript SDK provides easy integration for Fungies checkout in your web applications.

Installation

npm install @fungies/fungies-js

yarn add @fungies/fungies-js

pnpm add @fungies/fungies-js

Usage

JavaScript Initialization

import { Fungies } from "@fungies/fungies-js";

// Initialize Fungies
Fungies.Initialize({
  // Optional: Disable data attribute support
  // enableDataAttributes: false
});

// Open a checkout programmatically
Fungies.Checkout.open({
  checkoutUrl: "https://store.example.com/checkout-element/my-checkout-id",
  settings: {
    mode: "overlay", // 'overlay' | 'embed'
    frameTarget: "target-element-id", // Optional, for embed mode
  },
});

// Close the checkout
Fungies.Checkout.close();

Listening to checkout events

The SDK listens for messages from the checkout iframe and dispatches DOM events on document. This happens automatically when you call Fungies.Initialize() or use the data-auto-init script attribute — no extra setup is required.

Use these events to run your own logic after a purchase (redirect, show a thank-you page, refresh entitlements, etc.).

import { DOM_CHECKOUT_EVENTS, Fungies } from "@fungies/fungies-js";

Fungies.Initialize();

document.addEventListener(DOM_CHECKOUT_EVENTS.COMPLETE, () => {
  // Payment succeeded — e.g. redirect to a thank-you page
  window.location.href = "/thank-you";
});

document.addEventListener(DOM_CHECKOUT_EVENTS.CLOSE, () => {
  // Checkout overlay/embed was dismissed
  console.log("Checkout closed");
});

Fungies.Checkout.open({
  checkoutUrl: "https://store.example.com/checkout-element/my-checkout-id",
  settings: { mode: "overlay" },
});

When using the CDN script tag, register listeners after the SDK loads:

<script
  src="https://cdn.jsdelivr.net/npm/@fungies/fungies-js@CURRENT_VERSION"
  defer
  data-auto-init
></script>
<script>
  document.addEventListener("fungies:checkout:complete", () => {
    window.location.href = "/thank-you";
  });
</script>

In React, attach listeners in a useEffect and clean them up on unmount:

import { useEffect } from "react";
import { DOM_CHECKOUT_EVENTS, Fungies } from "@fungies/fungies-js";

function App() {
  useEffect(() => {
    Fungies.Initialize();

    const onComplete = () => {
      window.location.href = "/thank-you";
    };

    document.addEventListener(DOM_CHECKOUT_EVENTS.COMPLETE, onComplete);
    return () => {
      document.removeEventListener(DOM_CHECKOUT_EVENTS.COMPLETE, onComplete);
    };
  }, []);

  return <button onClick={() => Fungies.Checkout.open({ /* ... */ })}>Buy</button>;
}

Updating a payment method

Let a subscriber replace an expired card without leaving your page. Mint a session on your server with POST /v0/subscriptions/{subscriptionIdOrNumber}/paymentMethodSession (the secret key never reaches the browser), then hand the SDK the sessionToken and url from that response. The token travels to the element over postMessage only — it is never put in a URL, cookie or storage.

import { DOM_PAYMENT_METHOD_EVENTS, Fungies } from "@fungies/fungies-js";

document.addEventListener(DOM_PAYMENT_METHOD_EVENTS.UPDATED, () => {
  // The card on file changed; in overlay mode the element has already closed itself.
});
document.addEventListener(DOM_PAYMENT_METHOD_EVENTS.FAILED, () => {
  // The session can no longer be used (expired, already used, invalid). Mint a new one to retry.
});
document.addEventListener(DOM_PAYMENT_METHOD_EVENTS.CLOSE, () => {
  // The customer dismissed the overlay (X, ESC or backdrop). The session is still valid.
});

const { sessionToken, url } = await fetch("/api/payment-method-session", { method: "POST" }).then((r) => r.json());

Fungies.PaymentMethod.update({
  sessionToken,
  url,
  settings: {
    mode: "overlay", // 'overlay' | 'embed'
    frameTarget: "target-element-id", // Required with 'embed', ignored by 'overlay'
  },
});

// Close it programmatically (dispatches no event)
Fungies.PaymentMethod.close();

A declined card fires nothing: the form stays open and the customer can try another card.

Your page never navigates: the element completes the card change inside its own frame, and the frame is mounted with a sandbox that grants no allow-top-navigation, so nothing loaded inside it can replace your tab.

Need the event names without loading the SDK — a server-side bundle, or a page that loads a different SDK build by <script>? Import them from @fungies/fungies-js/events, which installs nothing on window.

settings.mode must be 'overlay' or 'embed'; any other value is refused with a console warning and nothing opens — the same as a missing sessionToken or an invalid url. At most one of updated / failed fires per session; a frame that re-announces after either is not forwarded.

There is deliberately no data-* attribute variant for this flow: a session token in a DOM attribute is readable by every third-party script on your page and gets captured by session-replay tools, while a value held in JavaScript is not. Keep the token in your code and call PaymentMethod.update().

Your page's origin must be in the workspace's authorized domains, or the browser refuses to frame the element. A refused frame never answers the handshake, so the SDK removes it 15 s after it loads and fires failed — in overlay mode that clears a full-viewport frame that would swallow clicks, in embed mode it empties the container you gave it instead of leaving the browser's error page there.

HTML Data Attribute Support

You can also use HTML data attributes to create checkout buttons without writing JavaScript:

<!-- Basic checkout button -->
<button
  data-fungies-checkout-url="https://store.example.com/checkout-element/my-checkout-id"
  data-fungies-mode="overlay"
>
  Open Checkout
</button>

<!-- Script tag to initialize the SDK -->
<script
  src="https://cdn.jsdelivr.net/npm/@fungies/fungies-js@CURRENT_VERSION"
  defer
  data-auto-init
></script>

<!-- Embed checkout with target element -->
<div id="target-element-id"></div>

<!-- Script tag to initialize and display checkout automatically -->
<script
  src="https://cdn.jsdelivr.net/npm/@fungies/fungies-js@CURRENT_VERSION"
  defer
  data-auto-init
  data-auto-display-checkout
  data-fungies-checkout-url="https://demo.dev.fungies.net/checkout-element/a85d8c76-bc30-48a3-9861-be68952a1eca"
  data-fungies-mode="embed"
  data-fungies-frame-target="target-element-id"
></script>

Manual DOM Scanning

If you dynamically add checkout elements after page load, you can manually trigger a DOM scan:

// Scan the page for new checkout elements
Fungies.ScanDOM();

Data Attributes Reference

• data-fungies-checkout-url: (Required for new format) The checkout URL
• data-fungies-mode: (Optional) The checkout mode ('overlay' or 'embed')
• data-fungies-frame-target: (Optional) Target element ID for embed checkouts
• data-fungies-discount-code: (Optional) Discount code to be applied
• data-fungies-customer-email: (Optional) Customer email to pre-fill (deprecated, use data-fungies-billing-email)
• data-fungies-billing-email: (Optional) Billing email to pre-fill
• data-fungies-billing-first-name: (Optional) Billing first name to pre-fill
• data-fungies-billing-last-name: (Optional) Billing last name to pre-fill
• data-fungies-billing-country: (Optional) Billing country code (ISO 3166-1 alpha-2) to pre-fill
• data-fungies-billing-state: (Optional) Billing state/province to pre-fill
• data-fungies-billing-city: (Optional) Billing city to pre-fill
• data-fungies-billing-zip-code: (Optional) Billing zip/postal code to pre-fill
• data-fungies-quantity: (Optional) Default quantity for the checkout
• data-fungies-items: (Optional) JSON string of items to be purchased
• data-fungies-custom-fields: (Optional) JSON string of custom fields
• data-fungies-button: (Legacy format) Contains a checkout URL like "https://STORE_URL/checkout-element/:checkoutID" or "https://STORE_URL/overlay/:checkoutID"

TypeScript Support

This package includes TypeScript definitions. You can take advantage of type checking and IntelliSense in supported editors:

import { DOM_CHECKOUT_EVENTS, Fungies } from "@fungies/fungies-js";
import type { DomCheckoutEvent, InitialCheckoutOpenOptions } from "@fungies/fungies-js";

const onComplete = (event: Event) => {
  const checkoutEvent = event.type as DomCheckoutEvent;
  if (checkoutEvent === DOM_CHECKOUT_EVENTS.COMPLETE) {
    window.location.href = "/thank-you";
  }
};

document.addEventListener(DOM_CHECKOUT_EVENTS.COMPLETE, onComplete);

// TypeScript will validate all parameters
const openOptions: InitialCheckoutOpenOptions = {
  checkoutUrl: "https://store.example.com/checkout-element/my-checkout-id",
  settings: {
    mode: "overlay",
    // frameTarget is optional and only used with embed mode
    frameTarget: "container-id",
  },
};

Fungies.Checkout.open(openOptions);