Checkout Embarcado

Incorpore o checkout diretamente no seu site

Você pode copiar e colar nosso snippet de código para começar em segundos ou usar nossa biblioteca JavaScript para integrações avançadas. O checkout embarcado permite uma experiência de compra sem redirecionar o usuário para fora do seu site.

​

Script hospedado (chargefy.js)

Um único bundle chargefy.min.js expõe checkout e onboarding: window.openChargefyCheckout, window.openChargefyOnboarding, além de window.Chargefy.EmbedOnboarding para compatibilidade com o snippet de onboarding.

Para só checkout, continue usando openChargefyCheckout como antes.

​

Carregar o script

Use a versão minificada em produção, servida em /scripts/ no domínio do app (ex.: app.chargefy.io):

<script
  src="https://app.chargefy.io/scripts/chargefy.min.js"
  defer
  data-chargefy-app-origin="https://app.chargefy.io"
  data-chargefy-api-origin="https://api.chargefy.io"
></script>

• chargefy.min.js — recomendado em produção (checkout + onboarding).
• chargefy.js — mesma API, sem minificar (útil para depuração).
• checkout-load.min.js — por compatibilidade, o build copia o mesmo conteúdo de chargefy.min.js por um período; prefira chargefy.min.js em novas integrações.

Atributos opcionais no <script> (sem barra final nas origens):

Atributo	Descrição
data-chargefy-app-origin	Base do app onde rota o checkout (ex.: https://app.chargefy.io).
data-chargefy-api-origin	Base da API usada para resolver links de onboarding por token.

Alternativa: window.__CHARGEFY_APP_ORIGIN__ e window.__CHARGEFY_API_ORIGIN__ antes de carregar o script. Em produção, os padrões embutidos são https://app.chargefy.io e https://api.chargefy.io.

Se o seu painel usar outro domínio, ajuste os atributos ou as globais acima; o caminho do arquivo continua /scripts/chargefy.min.js no host do app.

O script define openChargefyCheckout (e as demais APIs) no window ao executar. Chame-as depois do script ter carregado (por exemplo em um segundo <script defer> abaixo, ou após DOMContentLoaded).

​

Retorno (Promise)

openChargefyCheckout e openChargefyOnboarding devolvem Promise<{ close: () => void }>. O close remove o overlay e limpa listeners. Em onboarding, a Promise costuma resolver quando o iframe envia o evento loaded (ou após timeout de segurança).

​

Uso e opções

<script
  src="https://app.chargefy.io/scripts/chargefy.min.js"
  defer
  data-chargefy-app-origin="https://app.chargefy.io"
  data-chargefy-api-origin="https://api.chargefy.io"
></script>
<script defer>
  async function abrir() {
    const url = 'https://app.chargefy.io/checkout/cs_xxx' // URL completa, path /checkout/... ou client secret
    const { close } = await window.openChargefyCheckout(url, {
      isModal: true,
      allowClose: true,
    })
  }
</script>
<button type="button" onclick="abrir()">Comprar</button>

Parâmetro	Tipo	Descrição
target	string	URL absoluta do checkout na mesma origem configurada como app; path começando com /checkout/...; ou client secret / slug (ex.: cs_xxx) resolvido para {appOrigin}/checkout/{slug}. URLs absolutas com origem diferente da app são rejeitadas (evita open redirect).
props.isModal	boolean	true = iframe em modal centralizado, com fundo escurecido. false ou omitido = tela cheia no viewport. Padrão: false.
props.allowClose	boolean	Controla botão fechar e tecla Escape. Com isModal: true, o fechamento fica habilitado. Em tela cheia, o padrão é não exibir fechar; passe allowClose: true se quiser botão fechar e Escape.
props.theme	'light' | 'dark'	Reservado para evolução do checkout embarcado; hoje não altera o iframe de checkout.

Exemplos:

// Modal com fechamento (comportamento típico)
await window.openChargefyCheckout(checkoutUrl, { isModal: true })

// Tela cheia, sem controles de fechar (fluxo “só checkout”)
await window.openChargefyCheckout(checkoutUrl)

// Só o client secret (mesma origem da app)
await window.openChargefyCheckout('cs_live_xxx', { isModal: true })

// Tela cheia, mas permitindo fechar com X e Escape
await window.openChargefyCheckout(checkoutUrl, { allowClose: true })

Para sessões criadas via API, configure embed_origin com a origem da página onde o iframe é exibido (ex.: https://seusite.com.br), assim o checkout em iframe é permitido.

​

Snippet de Código (pacote @chargefy/checkout)

O snippet abaixo usa o pacote npm publicado no CDN. É uma alternativa ao script hospedado chargefy.min.js quando você quer a mesma API tipada no bundler ou builds npm.

Com chargefy.min.js e data-auto-init, também é possível usar o atributo data-chargefy-checkout no gatilho (o script unificado abre o checkout em modal ao clicar, resolvendo href como URL, path ou slug).

O snippet pode ser usado em qualquer site ou CMS que permita inserir HTML.

Primeiro, crie um Checkout Link conforme descrito na seção anterior. O snippet pode ser copiado diretamente clicando em Copiar Código Embed.

O snippet fica assim:

<a
  href="__CHECKOUT_LINK__"
  data-chargefy-checkout
  data-chargefy-checkout-theme="light"
>
  Comprar
</a>
<script
  src="https://cdn.jsdelivr.net/npm/@chargefy/checkout@0.1/dist/embed.global.js"
  defer
  data-auto-init
></script>

Isso exibirá um link “Comprar” que abrirá o checkout inline quando clicado.

Você pode estilizar o elemento gatilho como quiser, desde que mantenha o atributo data-chargefy-checkout.

​

Importar Biblioteca

Se você tem um projeto JavaScript mais avançado, como um app React, adicionar a tag <script> pode não ser ideal. Nesse caso, instale nossa biblioteca dedicada.

npm

npm install @chargefy/checkout

Importe a classe ChargelyEmbedCheckout e chame manualmente ChargelyEmbedCheckout.init(). Isso adicionará os handlers necessários nos elementos com o atributo data-chargefy-checkout.

Exemplo em React:

import { ChargefyEmbedCheckout } from '@chargefy/checkout/embed'
import { useEffect } from 'react'

const BotaoCompra = () => {
  useEffect(() => {
    ChargefyEmbedCheckout.init()
  }, [])

  return (
    <a
      href="__CHECKOUT_LINK__"
      data-chargefy-checkout
      data-chargefy-checkout-theme="light"
    >
      Comprar
    </a>
  )
}

export default BotaoCompra

Em vez de um Checkout Link, você pode usar a URL de uma Checkout Session criada dinamicamente via API.

Para isso funcionar, defina corretamente o parâmetro embed_origin ao criar a Checkout Session. Por exemplo, se a página de checkout está em https://seusite.com.br/checkout, defina embed_origin como https://seusite.com.br.

​

Integração Avançada

Para quem precisa de mais controle sobre o fluxo de checkout embarcado, a classe ChargefyEmbedCheckout oferece funcionalidades avançadas.

​

Criar embed programaticamente

Em vez de usar triggers declarativos com atributos data-chargefy-checkout, crie e controle instâncias de checkout programaticamente:

import { ChargefyEmbedCheckout } from "@chargefy/checkout/embed";

const abrirCheckout = async () => {
  const checkoutLink = "__CHECKOUT_LINK__";
  const theme = "light"; // ou 'dark'

  try {
    const checkout = await ChargefyEmbedCheckout.create(checkoutLink, theme);
    return checkout;
  } catch (error) {
    console.error("Falha ao abrir checkout", error);
  }
};

document.getElementById("botao-compra").addEventListener("click", () => {
  abrirCheckout();
});

​

Ouvir eventos do checkout

Escute eventos do checkout para reagir às interações do usuário:

import { ChargefyEmbedCheckout } from "@chargefy/checkout/embed";

const abrirCheckoutComEventos = async () => {
  const checkout = await ChargefyEmbedCheckout.create("__CHECKOUT_LINK__");

  checkout.addEventListener("loaded", (event) => {
    console.log("Checkout carregado");
  });

  checkout.addEventListener("close", (event) => {
    console.log("Checkout fechado");
  });

  checkout.addEventListener("confirmed", (event) => {
    console.log("Checkout confirmado, processando pagamento");
  });

  checkout.addEventListener("success", (event) => {
    console.log("Compra realizada com sucesso!", event.detail);

    if (!event.detail.redirect) {
      mostrarMensagemSucesso();
    }
  });

  return checkout;
};

​

Integração React com eventos

Exemplo completo em React com gerenciamento de eventos:

import { ChargefyEmbedCheckout } from '@chargefy/checkout/embed'
import { useState, useEffect } from 'react'

const BotaoCheckout = () => {
  const [checkoutInstance, setCheckoutInstance] = useState(null)

  useEffect(() => {
    return () => {
      if (checkoutInstance) {
        checkoutInstance.close()
      }
    }
  }, [checkoutInstance])

  const handleCheckout = async () => {
    try {
      const checkout = await ChargefyEmbedCheckout.create(
        '__CHECKOUT_LINK__',
        'light'
      )

      setCheckoutInstance(checkout)

      checkout.addEventListener('success', (event) => {
        analytics.track('Compra Realizada', {
          productId: 'seu-product-id',
        })

        if (!event.detail.redirect) {
          // Trate o sucesso no seu app
        }
      })

      checkout.addEventListener('close', () => {
        setCheckoutInstance(null)
      })
    } catch (error) {
      console.error('Falha ao abrir checkout', error)
    }
  }

  return (
    <button onClick={handleCheckout}>
      Finalizar Compra
    </button>
  )
}

export default BotaoCheckout

​

Fechar checkout programaticamente

Em alguns casos, pode ser necessário fechar o checkout programaticamente:

import { ChargefyEmbedCheckout } from "@chargefy/checkout/embed";

let checkoutAtivo = null;

async function abrirCheckout() {
  const checkout = await ChargefyEmbedCheckout.create("__CHECKOUT_LINK__");
  checkoutAtivo = checkout;

  checkout.addEventListener("close", () => {
    checkoutAtivo = null;
  });

  return checkout;
}

function fecharCheckout() {
  if (checkoutAtivo) {
    checkoutAtivo.close();
  }
}

​

Ver também

• Hosted Onboarding — cadastro de sub-organizações com URL hospedada ou iframe embarcado, mesmo estilo de snippet/script.