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

# Segurança do Sinnu Elements

> Domínios permitidos, o que fica fora do seu site e como liberar o pedido sem confiar no navegador.

O Sinnu Elements foi desenhado para que a sua página nunca veja o cartão nem guarde segredo. Em troca, três coisas ficam com você: cadastrar os domínios certos, liberar o pedido só pelo servidor e manter a chave de API fora do navegador.

## O que fica fora da sua página

* **Dados do cartão.** Número, validade e CVV só existem dentro do elemento, servido por `pay.sinnu.com.br`. O navegador isola o elemento da sua página: ela não consegue ler esse conteúdo. Por isso a sua página pode se enquadrar no questionário SAQ A do PCI DSS; a avaliação de conformidade da sua empresa continua sendo sua.
* **Segredos.** O elemento usa só o slug do link, que é público. A chave `sk_live_...` e o segredo do webhook ficam no servidor.

## Domínios permitidos

O elemento só abre nas páginas cujos domínios a empresa cadastrou no painel, em **Configurações → Checkout embutido → Domínios permitidos**. Qualquer membro da empresa vê a lista; cadastrar e remover é de quem gerencia integrações (Titular ou Administrador).

Cada item é uma **origem**: esquema, domínio e porta, exatamente como o navegador mostra em `window.location.origin`.

| Você cadastra | Vale para | Não vale para |
| - | - | - |
| `https://loja.exemplo.com.br` | `https://loja.exemplo.com.br/checkout` e qualquer outro caminho do mesmo domínio. | `https://www.loja.exemplo.com.br`, `https://pagamento.loja.exemplo.com.br` ou `http://loja.exemplo.com.br`. |
| `https://loja.exemplo.com.br:8443` | Páginas servidas nessa porta. | A mesma página na porta 443. |

Regras do cadastro:

* **`https://` obrigatório.** A porta 443 é omitida.
* **Cada subdomínio é outra origem.** `www` incluído. Curinga (`*`) não é aceito: cadastre cada endereço.
* **Só a origem.** Caminho, `?`, `#`, usuário e senha são recusados. Uma barra no fim é removida.
* **Domínio, não IP.** Endereço IP e host sem ponto são recusados.
* **Até 20 origens por empresa.** A mesma origem não pode ser cadastrada duas vezes.
* **Domínios internacionalizados** são gravados em punycode, como o navegador envia.

Uma mudança na lista pode levar até um minuto para valer.

Como o navegador confere: a página do elemento responde com `Content-Security-Policy: frame-ancestors` listando as origens da empresa. Fora delas, o navegador bloqueia o elemento antes de ele carregar, e o loader avisa com `error` `load_timeout`. Sem nenhuma origem cadastrada, ou com o recurso desligado para a empresa, nenhuma página consegue embutir o elemento. O checkout hospedado (`https://pay.sinnu.com.br/{slug}`) continua sem poder ser embutido em outra página.

## Mensagens entre a página e o elemento

As duas pontas conferem cada mensagem:

* o loader só aceita mensagens da origem `pay.sinnu.com.br`, vindas daquele elemento e com o canal aleatório criado para ele;
* o elemento só aceita mensagens da página que o embutiu, da origem cadastrada e do mesmo canal, e só envia para essa origem;
* mensagem fora do contrato é descartada sem resposta.

O elemento recebe apenas três permissões, válidas só para a origem da sinnu: escrever na área de transferência, para o botão de copiar o Pix, e ler acelerômetro e giroscópio, que o antifraude usa como sinal do aparelho. Se o seu site enviar um cabeçalho `Permissions-Policy` que bloqueie esses sensores, o bloqueio do seu site prevalece: o pagamento funciona igual, o antifraude só fica sem esse sinal.

## Libere o pedido pelo servidor

O evento `completed` e o resultado do `confirm()` rodam no navegador do comprador, que pode alterar a página. Use-os para a interface, nunca para liberar o pedido.

Libere de um destes jeitos:

1. **Webhook assinado `transaction.approved`.** Valide a assinatura como em [webhooks](https://docs.sinnu.com.br/guias/webhooks.md). O `data.reference` traz a referência com que o elemento foi montado.
2. **Consulta no seu servidor.** Com o `transactionId` do evento, chame `GET /api/transactions/{id}` com a sua chave e confira o status. Veja [transações no SDK](https://docs.sinnu.com.br/sdk/transacoes.md).

Ao liberar, confira se a referência é de um pedido seu e se o valor bate com o pedido. Atenção às unidades: nos eventos do Sinnu Elements, `amountCents` está em **centavos**; no webhook, `data.amount` está em **reais**. Veja [valores e status](https://docs.sinnu.com.br/fundamentos/valores-e-status.md).

O webhook pode chegar mais de uma vez: atualize o pedido de forma idempotente, como em [conciliação](https://docs.sinnu.com.br/guias/conciliacao.md).

## Autenticação do banco (3DS)

A primeira tentativa no cartão vai sem desafio. Se o emissor recusar e a autenticação do banco estiver disponível para a sua empresa, o elemento abre o desafio do banco e tenta mais uma vez, com a autenticação. Isso vale para qualquer `threeDsMode` do link.

* **O desafio abre dentro do elemento.** O comprador não sai da sua página, e o retorno do banco volta para o próprio elemento. A sua página não precisa fazer nada além de esperar o `completed` ou o `failed`.
* **Uma tentativa a mais, no máximo.** Uma segunda recusa chega como `failed` com `card_declined`.
* **Só recusa do emissor puxa o desafio.** Se a cobrança for bloqueada porque o pagamento já foi aprovado ou ainda está em confirmação, ou se houver erro de rede ou do servidor, não há desafio: chega `failed` com a mensagem original. Veja os [códigos de `failed`](https://docs.sinnu.com.br/elements/eventos#códigos-de-failed).
* **Desafio não concluído** chega como `card_declined`. Tempo esgotado ou desafio indisponível chega como `unknown`.

![Desafio de autenticação do banco aberto dentro do elemento payment, na própria página da loja.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/pagamento-3ds.png?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=7c278073d4a91ecfa1b5e038268e86e3)

## A referência do pedido

O link é o produto e pode ser vendido muitas vezes. Monte cada elemento com `reference` igual ao pedido no seu sistema:

```ts TypeScript theme={null}
createElements({ link: "abc12345", reference: "pedido-123" });
```

A referência tem até 255 caracteres, sem os espaços das pontas. Ela fica gravada na transação e volta como `reference` em `GET /api/transactions`, no `data.reference` do webhook e no evento `completed`. Não coloque dado pessoal do comprador nela: use o identificador do pedido.

## Content Security Policy do seu site

Se o seu site envia `Content-Security-Policy`, libere a origem do elemento 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;
```

Para não depender da CDN, sirva o arquivo `dist/sinnu-elements.global.js` do seu próprio domínio.

## Homologação

Se a sinnu liberou o ambiente de homologação para a sua empresa, aponte o elemento para ele com `baseUrl`:

```ts TypeScript theme={null}
createElements({ link: "abc12345", baseUrl: "https://pay-sandbox.sinnu.com.br" });
```

O link e os domínios permitidos precisam existir nesse ambiente, no painel dele; os de produção não valem lá. Na homologação, o painel também aceita `http://localhost:<porta>` e `http://127.0.0.1:<porta>` para você desenvolver na sua máquina. Em produção, só `https://`.

Fora isso, `baseUrl` precisa usar `https://` (`http://` só com `localhost` ou `127.0.0.1`) e ser só a origem, sem caminho.


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