> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sinnu.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Documentação oficial da sinnu, gateway de pagamento brasileiro: Pix e cartão de crédito. O índice de todas as páginas está em https://docs.sinnu.com.br/llms.txt.
> A API (https://api.sinnu.com.br) e o checkout (https://pay.sinnu.com.br) documentados são de produção. Não há ambiente público de testes: cada chamada cria ou altera dados reais.
> A chave secreta sk_live_ fica só no servidor. O navegador recebe apenas o slug do link ou a URL do checkout.
> Unidades: amountCents do link e os valores de /api/transactions/ estão em centavos (inteiro). data.amount do webhook e amount das transações de um link estão em reais. Compare na mesma unidade.
> Status: a API de transações usa approved; o corpo do webhook usa paid; o evento é transaction.approved.
> Libere o pedido só pelo webhook assinado (X-Sinnu-Signature, validado sobre o corpo cru com constructEvent({ payload, signature, secret })) e confirme com transactions.get. Nunca pelo evento completed do Sinnu Elements nem pelos parâmetros da URL de retorno.
> Estorno é sempre do valor total. Não invente métodos, campos ou eventos: confira na referência do SDK e da API.

# Início rápido

> Do link de pagamento ao primeiro pagamento com Pix ou cartão dentro do seu site.

Ao terminar, a sua página mostra o checkout da sinnu como um elemento e reage quando o pagamento é aprovado. Leva poucos minutos se o recurso já estiver liberado para a sua empresa.

Você precisa de um site servido por `https://`, de acesso ao [painel sinnu](https://app.sinnu.com.br) como Titular ou Administrador da empresa e de um link de pagamento de venda avulsa. Os exemplos usam produção: concluir um pagamento gera uma cobrança real.

**1. Peça a liberação**

O Sinnu Elements é ativado pela sinnu para cada empresa. Se ainda não estiver, [fale com o suporte de integração](https://docs.sinnu.com.br/comunidade/ajuda.md).

**2. Cadastre o domínio do seu site**

No painel, abra **Configurações → Checkout embutido → Domínios permitidos** e cadastre a origem exata da página que vai mostrar o elemento, por exemplo `https://loja.exemplo.com.br`.

`https://www.loja.exemplo.com.br` é outra origem: cadastre as duas se o site responde nas duas. A mudança pode levar até um minuto para valer. As regras completas estão em [segurança](https://docs.sinnu.com.br/elements/seguranca.md).

**3. Pegue o slug do link**

O slug é o código público no fim da URL do checkout: em `https://pay.sinnu.com.br/abc12345`, o slug é `abc12345`. Crie o link no painel ou [pela API](https://docs.sinnu.com.br/inicio/primeiro-link.md).

**4. Monte o elemento**

Escolha entre o arquivo pronto, via `<script>`, ou o pacote npm. Os dois têm a mesma API.

**Com `<script>`**, sem bundler. O arquivo expõe `window.SinnuElements`:

```html HTML theme={null}
<div id="pagamento"></div>

<script src="https://cdn.jsdelivr.net/npm/@sinnu-dev/elements@0.1/dist/sinnu-elements.global.js"></script>
<script>
  const elements = SinnuElements.createElements({
    link: "abc12345",
    reference: "pedido-123",
  });

  const checkout = elements.create("checkout");

  checkout.on("completed", ({ transactionId }) => showThanks(transactionId));
  checkout.on("error", ({ message }) => showError(message));

  checkout.mount("#pagamento");
</script>
```

* `link` é o slug do link de pagamento; `reference` é o pedido no seu sistema, que volta na transação e no webhook.
* `completed` serve só para a interface: o pedido é liberado pelo webhook.
* `error` chega quando o elemento não montou ou não carregou em 15 s (`load_timeout`). A `message` já vem pronta para o comprador.

`@0.1` recebe as correções da versão 0.1. Para fixar uma versão exata, use `@0.1.1`. Se preferir, sirva o arquivo `dist/sinnu-elements.global.js` do seu próprio domínio.

**Com npm**, em projetos com bundler:

```bash Terminal theme={null}
npm install @sinnu-dev/elements
```

```ts elements-checkout.ts theme={null}
import { createElements } from "@sinnu-dev/elements";

type Order = { slug: string; orderId: string };

type CheckoutScreen = {
  showThanks(transactionId: string): void;
  showError(message: string): void;
};

export function mountCheckout(target: string | HTMLElement, order: Order, screen: CheckoutScreen) {
  const elements = createElements({ link: order.slug, reference: order.orderId });
  const checkout = elements.create("checkout");

  checkout.on("completed", ({ transactionId }) => screen.showThanks(transactionId));
  checkout.on("error", ({ message }) => screen.showError(message));

  checkout.mount(target);
  return () => elements.destroy();
}
```

```ts Uso theme={null}
const destroy = mountCheckout("#pagamento", { slug: "abc12345", orderId: "pedido-123" }, {
  showThanks: (transactionId) => showThanks(transactionId),
  showError: (message) => showError(message),
});
```

O pacote pode ser importado no servidor (SSR) sem quebrar: só `mount()` precisa do navegador. Em React, use os [componentes prontos](https://docs.sinnu.com.br/elements/react.md).

**5. Libere o elemento na sua Content Security Policy**

Se o seu site envia o cabeçalho `Content-Security-Policy`, libere a página da sinnu em `frame-src` e, se usar o arquivo da CDN, a origem dele em `script-src`:

```text CSP theme={null}
frame-src https://pay.sinnu.com.br;
script-src 'self' https://cdn.jsdelivr.net;
```

**6. Libere o pedido pelo webhook**

Configure o [webhook](https://docs.sinnu.com.br/guias/webhooks.md) e libere o pedido no evento assinado `transaction.approved`. O `data.reference` dele traz o `reference` com que o elemento foi montado. O evento `completed` serve só para a interface.

## Se o elemento não aparecer

| O que acontece | Causa provável | O que fazer |
| - | - | - |
| O elemento fica em branco ou mostra um erro do navegador e, depois de 15 s, chega `error` com `load_timeout`. O console cita `frame-ancestors`. | O domínio da página não está cadastrado, nenhum domínio foi cadastrado ou o recurso não foi liberado para a empresa. O navegador bloqueia o elemento antes de ele carregar. | Confira a origem exata em **Domínios permitidos** e aguarde até um minuto. |
| O console cita `frame-src` ou `script-src`. | A Content Security Policy do seu site bloqueou o elemento ou o arquivo da CDN. | Libere as origens do passo anterior. |
| Evento `error` com `link_not_found`. | O slug não existe. | Confira o slug do link. |
| Evento `error` com `unsupported_link`. | O link é só de assinatura. | Use um link de venda avulsa. |
| Evento `error` com `origin_not_allowed`. | A origem informada ao elemento não está entre os domínios permitidos, por exemplo numa URL do elemento montada à mão. | Monte o elemento pelo loader, numa página do domínio cadastrado. |
| Evento `failed` com `rate_limited` ou `network_error` logo ao montar. | O link não pôde ser carregado naquele momento. | Monte de novo depois de alguns segundos, com `unmount()` e `mount()`. |
| `invalid_config` lançado na hora. | Opção inválida, como slug vazio ou `baseUrl` sem `https://`. | Leia a mensagem do erro: ela diz qual opção corrigir. |

Em qualquer `error`, ofereça uma alternativa ao comprador, como um link para o checkout hospedado do mesmo link e pedido (`https://pay.sinnu.com.br/abc12345?ref=pedido-123`). O prazo de carregamento muda com a opção `loadTimeoutMs`. A tabela completa de códigos está em [eventos e erros](https://docs.sinnu.com.br/elements/eventos.md).

> [card] [Elemento checkout](https://docs.sinnu.com.br/elements/checkout.md)
>
> Opções, eventos e o que o comprador vê.

> [card] [Elemento payment](https://docs.sinnu.com.br/elements/pagamento.md)
>
> Seus campos, seu botão e o `confirm()`.


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