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

# Sinnu Elements

> Tudo o que você precisa para receber com Pix e cartão no seu site: elementos seguros da sinnu para o pagamento e componentes para a interface em volta deles.

Com o Sinnu Elements, o comprador paga com Pix ou cartão sem sair do seu site. O formulário roda num componente seguro servido por `pay.sinnu.com.br`, e a sua página conversa com ele por eventos. Preço, parcelas, juros e meios de pagamento continuam vindo do link de pagamento, como no checkout hospedado.

O checkout hospedado (`https://pay.sinnu.com.br/{slug}`) continua sendo o caminho mais simples: um link ou redirecionamento, sem nada para instalar. Use o Sinnu Elements quando o pagamento precisar acontecer dentro da sua página.

## Escolha a peça

O Sinnu Elements reúne as peças para cobrar no seu site. Os **elementos** são componentes seguros servidos pela sinnu: recebem o pagamento dentro da sua página. Os **componentes do seu site** ficam no seu código, em volta deles: abrir o checkout e mostrar o resultado.

| Peça | Onde roda | O que faz | Quando usar |
| - | - | - | - |
| [Elemento `checkout`](https://docs.sinnu.com.br/elements/checkout) | Servido pela sinnu | Resumo, dados do comprador, Pix ou cartão e o botão de pagar. | Você quer o checkout completo embutido, com o mínimo de código. |
| [Elemento `payment`](https://docs.sinnu.com.br/elements/pagamento) | Servido pela sinnu | Só os meios de pagamento: Pix e os campos do cartão. | Você já coleta nome, e-mail, documento e telefone no seu formulário e quer o seu próprio botão de pagar. |
| [Botão de pagamento](https://docs.sinnu.com.br/elements/botao-de-pagamento.md) | Seu código | Abre o checkout hospedado a partir do slug público do link. | Você quer cobrar com um clique, sem embutir nada. |
| [Status de pagamento](https://docs.sinnu.com.br/elements/status-de-pagamento.md) | Seu código | Mostra a situação e o valor que o seu servidor confirmou. | Depois do pagamento, em qualquer uma das opções acima. |

![Elemento checkout numa página: resumo do pedido, dados do comprador, escolha entre Pix e 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)

Elemento checkout: o formulário completo

![Elemento payment numa página: o formulário do comprador é da loja, e o elemento mostra só a escolha entre Pix e cartão.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/pagamento-inicio.png?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=df718a83498ad4805cf8d1b8d11816e8)

Elemento payment: só os meios de pagamento

Os elementos vêm no pacote `@sinnu-dev/elements`, com componentes React em `@sinnu-dev/elements/react`. O botão e o status são receitas React para copiar e adaptar: não há pacote para instalar, e nenhum deles recebe chave de API, segredo de webhook ou dado de cartão. A [aparência](https://docs.sinnu.com.br/elements/aparencia.md) ajusta as cores dos elementos; os [fundamentos visuais](https://docs.sinnu.com.br/elements/fundamentos-visuais.md) e a [acessibilidade](https://docs.sinnu.com.br/elements/acessibilidade.md) valem para tudo.

Nos elementos, o QR Code do Pix, o desafio de autenticação do cartão (3DS) e a confirmação do pagamento aparecem dentro do elemento. Veja [como o 3DS entra](https://docs.sinnu.com.br/elements/seguranca.md#autenticação-do-banco-3ds). O elemento ocupa a largura do contêiner e ajusta a altura sozinho.

## O que a sinnu garante

> [card] O cartão não passa pela sua página
>
> Número, validade e CVV só existem dentro do elemento, servido por `pay.sinnu.com.br`. Seu site não tem acesso a eles, o que permite que sua página se enquadre no questionário SAQ A do PCI DSS.

> [card] Nenhum segredo no navegador
>
> O elemento usa só o slug do link, que é público: o mesmo código da URL do checkout. A chave `sk_live_...` fica no seu servidor.

> [card] Só nos seus domínios
>
> O elemento só abre nos domínios cadastrados para a sua empresa. As mensagens entre a página e o elemento são conferidas nas duas pontas.

> [card] As mesmas regras do checkout
>
> A cobrança é a do checkout hospedado: mesmos valores, mesmas parcelas e as mesmas verificações antifraude.

Os detalhes estão em [segurança](https://docs.sinnu.com.br/elements/seguranca.md).

## O que você precisa

1. **Sinnu Elements liberado para a sua empresa.** O recurso é ativado pela sinnu. [Fale com o suporte de integração](https://docs.sinnu.com.br/comunidade/ajuda.md) para liberar.
2. **O domínio do seu site cadastrado no painel**, em **Configurações → Checkout embutido → Domínios permitidos**: a origem exata, como `https://loja.exemplo.com.br`.
3. **Um link de pagamento de venda avulsa.** Crie no painel ou [pela API](https://docs.sinnu.com.br/inicio/primeiro-link.md) e guarde o `slug`.
4. **Um webhook configurado.** O pedido é liberado pelo evento assinado `transaction.approved`, não pelo navegador. Veja [webhooks](https://docs.sinnu.com.br/guias/webhooks.md).

## Como um pagamento acontece

![Fluxo de um pagamento: seu servidor entrega à página o slug e o pedido; a página monta o elemento da sinnu; o comprador paga com Pix ou cartão; o evento completed só atualiza a tela; a sinnu envia o webhook transaction.approved ao seu servidor, que libera o pedido.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/fluxo-pagamento.svg?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=f6bd940f83ecb6547f03e3234cbe2e83)

**1. Seu servidor escolhe o link e o pedido**

Ele entrega à página o `slug` do link e a referência do pedido no seu sistema. Nada de chave de API vai junto.

**2. Sua página monta o elemento**

O loader `@sinnu-dev/elements` monta o elemento com o slug, a referência e a origem da sua página.

**3. O comprador paga dentro do elemento**

No Pix, o QR Code aparece no elemento até o pagamento ou o vencimento. No cartão, a aprovação aparece na hora.

**4. O seu servidor libera o pedido**

O evento `completed` atualiza a sua interface. A liberação vem do webhook `transaction.approved`, que traz a mesma referência do pedido.

## Limitações da v1

* **Só venda avulsa.** Um link só de assinatura não monta: o elemento responde `error` com `unsupported_link`. Um link que também aceita compra avulsa abre só nela.
* **Só pt-BR.** A opção `locale` aceita apenas `"pt-BR"`.
* **Sem Apple Pay e Google Pay** dentro do elemento.
* **O valor vem do link.** Uma sessão com valor definido pelo seu servidor na hora da compra virá em uma versão futura.
* **Pixels de rastreamento** configurados no link não rodam dentro do elemento.
* **Pix Automático** em breve.

## O pacote

O loader é o pacote `@sinnu-dev/elements`: zero dependências, ESM e CommonJS, tipos TypeScript e componentes React em `@sinnu-dev/elements/react`. Ele também tem um arquivo pronto para usar com `<script>`, sem bundler. A versão atual e o histórico ficam na [página do pacote no npm](https://www.npmjs.com/package/@sinnu-dev/elements).

> [card] [Início rápido](https://docs.sinnu.com.br/elements/inicio-rapido.md)
>
> Do link ao primeiro pagamento embutido.

> [card] [Exemplo completo](https://docs.sinnu.com.br/elements/exemplo-propostas.md)
>
> Um app de propostas que cobra pelo elemento payment.

> [card] [Segurança](https://docs.sinnu.com.br/elements/seguranca.md)
>
> Domínios permitidos e liberação do pedido.


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