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

# Elemento checkout

> O formulário completo da sinnu dentro do seu site: resumo, comprador, Pix ou cartão e o botão de pagar.

O elemento `checkout` coloca o checkout inteiro na sua página, num componente seguro da sinnu. O comprador vê o resumo do produto, preenche os dados dele, escolhe Pix ou cartão e paga, sem sair do seu site. Você escreve só a montagem e as reações aos eventos.

![Elemento checkout montado numa página de loja: resumo do pedido, dados do comprador, Pix ou cartão e o botão de pagar.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/checkout-inicio.png?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=f83dab92d073c6351347e3cbe5d74eae)

Antes, confira os [requisitos](https://docs.sinnu.com.br/elements/visao-geral.md): recurso liberado, domínio cadastrado e um link de venda avulsa.

## Código

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

```html Contêiner theme={null}
<div id="pagamento"></div>
```

O elemento ocupa 100% da largura do contêiner. A altura começa em 120 px e acompanha o conteúdo pelo evento `resize`, sem código seu. Limite a largura pelo contêiner, por exemplo com `max-width: 560px`.

## Opções de `createElements`

| Opção | Tipo | Descrição |
| - | - | - |
| `link` | `string` | Obrigatória. Slug do link de pagamento: até 64 caracteres entre letras, números, `-` e `_`. |
| `reference` | `string` | Pedido no seu sistema. Até 255 caracteres, sem os espaços das pontas; vazia é ignorada. Volta como `reference` na transação, no webhook e no evento `completed`. |
| `appearance` | `object` | Cores, cantos e fonte. Veja [aparência](https://docs.sinnu.com.br/elements/aparencia.md). |
| `baseUrl` | `string` | Padrão `https://pay.sinnu.com.br`. Homologação: `https://pay-sandbox.sinnu.com.br`. Precisa de `https://`. |
| `locale` | `"pt-BR"` | Único valor aceito na v1. |
| `loadTimeoutMs` | `number` | Prazo para o elemento carregar (evento `ready`), em milissegundos, de `1000` a `120000`. Padrão: `15000` (15 s). Esgotado, o elemento emite `error` com `load_timeout`. |

Uma opção inválida lança `SinnuElementsError` com `invalid_config` na hora, com uma mensagem que diz o que corrigir. `createElements` não toca no DOM: pode rodar no servidor.

Os elementos criados por uma instância compartilham link, referência e aparência. Para outro pedido, crie outra instância.

## Métodos

| Método | O que faz |
| - | - |
| `elements.create("checkout")` | Cria o elemento. Ainda não aparece na página. |
| `checkout.mount(alvo)` | Monta o elemento dentro do alvo: um seletor CSS, como `"#pagamento"`, ou um `HTMLElement`. |
| `checkout.on(evento, handler)` | Escuta um evento. Devolve uma função que cancela a escuta. |
| `checkout.unmount()` | Tira o elemento da página. Ele pode ser montado de novo. |
| `checkout.destroy()` | Tira o elemento e os handlers. O elemento não pode mais ser usado. |
| `elements.destroy()` | Destrói todos os elementos da instância e para de escutar mensagens. |

Montar duas vezes sem `unmount()` lança `invalid_config`. Numa aplicação de página única, chame `elements.destroy()` quando a tela do pagamento sair.

## Eventos que importam aqui

| Evento | Use para |
| - | - |
| `ready` | Esconder o seu indicador de carregamento. `methods` lista os meios disponíveis no link; vazio quando o link não está disponível agora (pausado, por exemplo). |
| `completed` | Mostrar o "obrigado" ou levar o comprador para a próxima tela. Traz `transactionId`, `method`, `amountCents` (centavos) e `reference`. |
| `failed` | Registrar a falha. O próprio formulário mostra o erro ao comprador e continua usável. |
| `pix_created` | Saber que o QR Code está na tela, com `expiresAt` (ISO 8601). |
| `expired` | Saber que o Pix venceu sem pagamento. O formulário volta para uma nova tentativa. |
| `error` | Mostrar uma alternativa: o elemento não montou ou não carregou no prazo (`load_timeout`). |

Os payloads e todos os códigos estão em [eventos e erros](https://docs.sinnu.com.br/elements/eventos.md).

## O que o comprador vê

> [tab] Pix
>
> ![Pix gerado dentro do elemento checkout: QR Code, contagem até o vencimento e o botão de copiar o código.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/checkout-pix.png?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=408ba1ec83c94818a2d9732e55cc41bf)

> [tab] Cartão
>
> ![Cartão de crédito escolhido no elemento checkout: número, validade, CVV e parcelas.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/checkout-cartao.png?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=a4395fd0a19a3988d5a5495aa43f48bb)

> [tab] Aprovado
>
> ![Pagamento aprovado dentro do elemento checkout, com o valor, o meio e o número do pedido.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/checkout-aprovado.png?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=905fa1dd6ef34dc80f6145b7982e9a33)

* **Pix**: o QR Code e o copia e cola aparecem dentro do elemento, com a contagem até o vencimento. Quando o pagamento é confirmado, o elemento mostra a aprovação e você recebe `completed`.
* **Cartão**: parcelas e juros seguem o link. Se o emissor recusar a primeira tentativa e a autenticação do banco (3DS) estiver disponível, o desafio abre dentro do elemento. Veja [como o 3DS entra](https://docs.sinnu.com.br/elements/seguranca.md#autenticação-do-banco-3ds). Aprovado, o elemento mostra a confirmação e você recebe `completed`.
* **Recusa**: o comprador vê o motivo no formulário e pode tentar outro cartão.
* **Comprador vinculado**: quando o link possui cliente vinculado (`customer` ou `linkedCustomer`), nome, e-mail, telefone (se informado) e CPF/CNPJ mascarado já abrem preenchidos, com opção de alterar.
* **Link pausado**: o elemento mostra que o pagamento está indisponível.

O elemento não navega. O `redirectUrl` do link vale para o checkout hospedado; no Sinnu Elements, quem decide a próxima tela é a sua página, no evento `completed`.

> [!WARNING]
>
> `completed` roda no navegador do comprador. Use para a interface e libere o pedido pelo webhook `transaction.approved` ou consultando a transação no seu servidor. Veja [segurança](https://docs.sinnu.com.br/elements/seguranca.md).

> [card] [Só os meios de pagamento](https://docs.sinnu.com.br/elements/pagamento.md)
>
> Use o elemento `payment` com o seu formulário.

> [card] [Em React](https://docs.sinnu.com.br/elements/react.md)
>
> O mesmo elemento como componente.


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