Embed de Checkout Paysgator

Incorpore o checkout da Paysgator dentro da sua página usando o paymentlinkId retornado por POST /payment/create.

Primeiros passos

Inclua o script do domínio de checkout Paysgator:

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

Adicione um container na sua página:

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

Inicialize o formulário com o ID do link de pagamento:

<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>

Personalização de tema

Passe theme, cssVars ou customCss ao instanciar PaysgatorForm.

Variável	Finalidade
`--pg-button-bg`	Cor principal do botão
`--pg-button-text-color`	Cor do texto do botão
`--pg-card-bg`	Cor de fundo do card
`--pg-card-shadow`	Sombra do card
`--pg-method-card-bg`	Fundo do card de método (inativo)
`--pg-method-card-selected-bg`	Fundo do card de método (selecionado)
`--pg-method-card-shadow`	Sombra dos cards de método
`--pg-text-color`	Cor principal do texto
`--pg-muted-text-color`	Cor de texto secundário

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();

Eventos

payment.success: payload inclui linkId, transactionId, amount, currency.
payment.failed: payload inclui linkId, message e error opcional.
form.ready: o iframe carregou e solicitou ajuste de tamanho.
form.initialized: iframe anexado e listeners instalados.

Fluxo completo: criar link no backend e enviar para frontend

1. Backend (Node.js + Express) cria o link

Mantenha sua chave de API apenas no servidor.

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;

    // Valide e normalize os dados de negócio no 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 || "Nao foi possivel criar o link de pagamento"
      });
    }

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

2. Frontend HTML busca o link e monta o embed

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

<script>
  async function iniciarCheckout() {
    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 || "Falha ao criar checkout link");

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

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

3. Exemplo React (criar 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 CheckoutPaysgator() {
  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 || "Nao foi possivel criar o 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("Pago:", event.transactionId);
          }
          if (event.type === "payment.failed") {
            console.error("Falhou:", event.message);
          }
        });

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

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

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

Dicas de embed

Prefira cssVars ou customCss nas opcoes do PaysgatorForm para manter o estilo white-label no iframe.
Mantenha X-Api-Key apenas em endpoints de backend.
Use externalTransactionId unico para conciliacao de pedidos.
Se necessario, passe currency para /v2/components/:id nos parametros do iframe para fixar a moeda de exibicao.

Primeiros passos​

Personalização de tema​

Eventos​

Fluxo completo: criar link no backend e enviar para frontend​

1. Backend (Node.js + Express) cria o link​

2. Frontend HTML busca o link e monta o embed​

3. Exemplo React (criar link + embed)​

Dicas de embed​