> ## Documentation Index
> Fetch the complete documentation index at: https://scaleup-c34c4386.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout Embarcado

> Incorpore o checkout diretamente no seu site

![](https://mintlify.s3.us-west-1.amazonaws.com/scaleup-c34c4386/assets/features/checkout/embed/demo.png)

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`):

```html theme={null}
<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

```html theme={null}
<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:

```javascript theme={null}
// 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 })
```

> [!TIP]
>
> Para sessões criadas via API, configure [`embed_origin`](https://scaleup-c34c4386.mintlify.site/api-reference/checkouts/create#body-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](https://scaleup-c34c4386.mintlify.site/features/checkout/links.md) conforme descrito na seção anterior. O snippet pode ser copiado diretamente clicando em `Copiar Código Embed`.

O snippet fica assim:

```html theme={null}
<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.

```bash npm theme={null}
npm install @chargefy/checkout
```

```bash pnpm theme={null}
pnpm add @chargefy/checkout
```

```bash yarn theme={null}
yarn add @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:

```tsx theme={null}
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
```

> [!TIP]
>
> Em vez de um Checkout Link, você pode usar a URL de uma [Checkout Session](https://scaleup-c34c4386.mintlify.site/features/checkout/session.md) criada dinamicamente via API.
>
> Para isso funcionar, defina corretamente o parâmetro [`embed_origin`](https://scaleup-c34c4386.mintlify.site/api-reference/checkouts/create#body-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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```tsx theme={null}
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:

```typescript theme={null}
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](https://scaleup-c34c4386.mintlify.site/features/hosted-onboarding) — cadastro de sub-organizações com URL hospedada ou iframe embarcado, mesmo estilo de snippet/script.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.