Paysgator Checkout Embed

Embed the Paysgator checkout inside your page using a paymentlinkId returned by POST /payment/create.

Getting started

1. Include the script from your Paysgator checkout domain:

<script src="https://paysgator.com/embed.js"></script>

2. Mount a container on your page:

<div id="paysgator-form"></div>

3. Initialize the form with the payment link ID:

<script>
  const form = new PaysgatorForm("#paysgator-form", "LINK_ID");

  form.on((event) => {
    if (event.type === "form.ready") {
      console.log("form ready");
    }

    if (event.type === "form.initialized") {
      console.log("form initialized");
    }

    if (event.type === "payment.success") {
      console.log("success", event);
    }

    if (event.type === "payment.failed") {
      console.log("failed", event);
    }
  });

  form.init();
</script>

Theme overrides

Pass theme, cssVars, or customCss when instantiating PaysgatorForm.

Variable	Purpose
--pg-button-bg	Primary button color
--pg-button-text-color	Primary button text
--pg-card-bg	Card background color
--pg-card-shadow	Card shadow
--pg-method-card-bg	Inactive method card background
--pg-method-card-selected-bg	Selected method card background
--pg-method-card-shadow	Method card shadow
--pg-text-color	Main text color
--pg-muted-text-color	Muted footer text

const form = new PaysgatorForm("#paysgator-form", "LINK_ID", {
  theme: {
    buttonColor: "#0f172a",
    buttonTextColor: "#f8fafc",
    cardColor: "#f8fafc",
    cardElevation: "0 20px 40px rgba(15,23,42,.2)"
  },
  customCss: ".pg-method-card { border-radius: 16px; }"
});

form.init();

Events

• payment.success: payload includes linkId, transactionId, amount, currency.
• payment.failed: payload includes linkId, message, and optional error.
• form.ready: iframe loaded and requested sizing.
• form.initialized: iframe appended and listeners installed.

Complete flow: create link on backend and use it on frontend

1. Backend (Node.js + Express) creates the link

Keep your API key on the server only.

import express from "express";

const app = express();
app.use(express.json());

app.post("/api/checkout-link", async (req, res) => {
  try {
    const { amount, currency, externalTransactionId } = req.body;

    // Validate/normalize business data on your backend.
    const response = await fetch("https://paysgator.com/api/v1/payment/create", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Api-Key": process.env.PAYSGATOR_SECRET_KEY || ""
      },
      body: JSON.stringify({
        amount,
        currency,
        externalTransactionId,
        fields: ["name", "email"],
        returnUrl: "https://your-frontend.com/payment-result"
      })
    });

    const payload = await response.json();

    if (!response.ok || !payload?.success) {
      return res.status(response.status || 400).json({
        success: false,
        message: payload?.error?.message || "Could not create payment link"
      });
    }

    return res.json({
      success: true,
      linkId: payload.data.paymentlinkId,
      checkoutUrl: payload.data.checkoutUrl
    });
  } catch (error) {
    return res.status(500).json({
      success: false,
      message: "Unexpected server error",
      error: String(error)
    });
  }
});

2. Frontend HTML fetches link and mounts embed

<script src="https://paysgator.com/embed.js"></script>
<div id="paysgator-form"></div>

<script>
  async function startCheckout() {
    const response = await fetch("/api/checkout-link", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        amount: 100,
        currency: "USD",
        externalTransactionId: "order_12345"
      })
    });

    const data = await response.json();
    if (!data.success) throw new Error(data.message || "Checkout link failed");

    const form = new PaysgatorForm("#paysgator-form", data.linkId);
    form.on((event) => console.log("event", event));
    form.init();
  }

  startCheckout().catch(console.error);
</script>

3. React example (create link + embed)

import { useEffect, useRef, useState } from "react";

function ensurePaysgatorScript() {
  return new Promise((resolve, reject) => {
    if (window.PaysgatorForm) return resolve();

    const existing = document.querySelector('script[src="https://paysgator.com/embed.js"]');
    if (existing) {
      existing.addEventListener("load", resolve, { once: true });
      existing.addEventListener("error", reject, { once: true });
      return;
    }

    const script = document.createElement("script");
    script.src = "https://paysgator.com/embed.js";
    script.async = true;
    script.onload = resolve;
    script.onerror = reject;
    document.head.appendChild(script);
  });
}

export default function PaysgatorCheckout() {
  const containerRef = useRef(null);
  const [error, setError] = useState("");

  useEffect(() => {
    let mounted = true;

    async function init() {
      try {
        await ensurePaysgatorScript();

        const response = await fetch("/api/checkout-link", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({
            amount: 100,
            currency: "USD",
            externalTransactionId: "order_98765"
          })
        });

        const data = await response.json();
        if (!mounted || !data.success) {
          throw new Error(data.message || "Unable to create checkout link");
        }

        const selector = `#${containerRef.current.id}`;
        const form = new window.PaysgatorForm(selector, data.linkId, {
          cssVars: {
            "--pg-button-bg": "#111827",
            "--pg-button-text-color": "#ffffff"
          }
        });

        form.on((event) => {
          if (event.type === "payment.success") {
            console.log("Paid:", event.transactionId);
          }
          if (event.type === "payment.failed") {
            console.error("Failed:", event.message);
          }
        });

        form.init();
      } catch (e) {
        if (mounted) setError(String(e));
      }
    }

    init();
    return () => {
      mounted = false;
    };
  }, []);

  if (error) return <p>Checkout error: {error}</p>;
  return <div id="paysgator-form-react" ref={containerRef} />;
}

Embedding hints

• Prefer cssVars or customCss in PaysgatorForm options to keep iframe styling white-label.
• Keep X-Api-Key only on backend endpoints.
• Use unique externalTransactionId values to reconcile orders.
• If needed, pass currency to /v2/components/:id in iframe URL parameters to lock display currency.