@mupag/widget

Browser SDK para abrir o checkout MuPag em modal via iframe, sem redirect obrigatório.

Distribuição

@mupag/[email protected] está publicado no npm e pode ser usado pelo npm, unpkg ou jsDelivr. O domínio CDN próprio da MuPag ainda está pendente e não é anunciado como disponível.

npm install @mupag/widget

Alternativa via unpkg:

<script src="https://unpkg.com/@mupag/[email protected]/dist/widget.global.js" defer></script>

Alternativa via jsDelivr:

<script src="https://cdn.jsdelivr.net/npm/@mupag/[email protected]/dist/widget.global.js" defer></script>

O bundle expõe apenas window.MuPagWidget com { MuPag, init, version }.

Uso via atributos de dados

<button
  data-mupag-widget
  data-environment="test"
  data-publishable-key="pk_test_..."
  data-item-name="Plano Pro"
  data-unit-amount-cents="10990"
  data-quantity="1"
  data-success-url="https://sua-loja.example/pagamento/sucesso"
  data-cancel-url="https://sua-loja.example/carrinho"
>
  Comprar agora
</button>

NPM

npm install @mupag/widget

import { MuPag } from "@mupag/widget";

const mupag = new MuPag({
  environment: "test",
  publishableKey: "pk_test_...",
});

await mupag.openCheckout({
  items: [{ name: "Plano Pro", quantity: 1, unit_amount_cents: 10_990 }],
  success_url: "https://sua-loja.example/pagamento/sucesso",
  cancel_url: "https://sua-loja.example/carrinho",
  customer_data: { email: "[email protected]" },
  onSuccess: (charge) => console.log("Paid", charge),
  onClose: () => console.log("Closed"),
});

Segurança e compatibilidade

• A chave publishable precisa do escopo checkout_sessions.create.
• environment é obrigatório e a chave deve corresponder a test (pk_test_) ou prd (pk_prd_).
• Nunca use uma chave secreta no navegador.
• O widget cria uma Idempotency-Key criptograficamente segura para cada nova sessão; informe idempotencyKey para reutilizar a mesma operação em uma tentativa controlada.
• Sem eval, top-level await ou dependências runtime externas.
• Baseline ES2018.
• Modal isolado com Shadow DOM e iframe com sandbox.
• postMessage aceita eventos apenas da origem e da janela do iframe ativo.
• A URL de checkout retornada precisa usar a origem configurada e o caminho /c/{session_id}.
• Para domínio próprio de checkout, configure checkoutBaseUrl explicitamente com a origem HTTPS.
• Em telas menores que 640px o modal vira fullscreen.
• Se o iframe não carregar, o SDK faz fallback para redirect.