# sinnu developers
> Construa com a sinnu. Guias de integração, SDK TypeScript, componentes e referência da API de pagamentos.
> ## 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.
# Atualize um cliente
Source: https://docs.sinnu.com.br/api/clientes/atualizar
PATCH /api/customers/{id}/
Altere parcialmente os dados de um cliente.
Envie somente os campos que deseja modificar. Preserve o identificador usado nos vínculos da sua aplicação.
# Consulte um cliente
Source: https://docs.sinnu.com.br/api/clientes/consultar
GET /api/customers/{id}/
Busque um cliente pelo identificador.
O recurso precisa pertencer à empresa vinculada à chave de API.
# Crie um cliente
Source: https://docs.sinnu.com.br/api/clientes/criar
POST /api/customers/
Cadastre os dados de um cliente na empresa.
Envie somente os dados necessários ao cadastro (`phone` é opcional). Se você deseja criar o link já com os dados do comprador preenchidos em uma única chamada, envie o objeto `customer` diretamente em [`POST /api/payment-links`](/api/links/criar).
# Liste clientes
Source: https://docs.sinnu.com.br/api/clientes/listar
GET /api/customers/
Consulte os clientes da empresa autenticada.
A empresa é determinada pela chave de API. Use os identificadores retornados para buscar os detalhes.
# Referência da API
Source: https://docs.sinnu.com.br/api/introducao
Consulte o contrato público de links de pagamento, clientes e transações.
Todas as chamadas desta referência usam a URL base:
```text Produção theme={null}
https://api.sinnu.com.br
```
Autentique no servidor com `Authorization: Bearer SUA_CHAVE_SECRETA`. O contexto de empresa vem da chave.
> [card] [Links de pagamento](/api/links/criar)
>
> Crie a oferta e obtenha o slug do checkout.
> [card] [Transações](/api/transacoes/listar)
>
> Consulte o resultado de cada pagamento.
> [card] [Clientes](/api/clientes/listar)
>
> Gerencie os clientes da empresa.
> [card] [Eventos](/guias/webhooks)
>
> Receba mudanças no seu servidor.
## Convenções
* **Links** usam caminhos sem barra final, como `/api/payment-links`.
* **Transações e clientes** usam barra final, como `/api/transactions/`.
* **Listas** usam paginação com `page` e `pageSize`.
* **Valores** dependem do recurso. Confira [a tabela de unidades](/fundamentos/valores-e-status).
## Contrato legível por ferramentas
[Baixe o OpenAPI público](/api/openapi.yaml) para importar em ferramentas de desenvolvimento. Esta referência contém a superfície para integradores; rotas administrativas não fazem parte dela.
Os exemplos são copiáveis. O envio interativo de requisições está desativado neste portal, pois a URL documentada é de produção.
# Arquive um link
Source: https://docs.sinnu.com.br/api/links/arquivar
DELETE /api/payment-links/{id}
Retire um link de circulação.
Arquivar o link não estorna transações anteriores. O método `sinnu.links.archive(id)` não retorna um objeto.
# Atualize um link
Source: https://docs.sinnu.com.br/api/links/atualizar
PATCH /api/payment-links/{id}
Altere os campos de um link da empresa.
Envie apenas os campos que deseja alterar, incluindo `customer`, `linkedCustomer` ou `maxPayments`. Os status do link são `active`, `paused` e `archived`.
# Consulte um link
Source: https://docs.sinnu.com.br/api/links/consultar
GET /api/payment-links/{id}
Busque um link pelo identificador retornado na criação.
Use o `id` do link no caminho. O `slug` serve para a URL pública do checkout.
# Crie um link de pagamento
Source: https://docs.sinnu.com.br/api/links/criar
POST /api/payment-links
Defina o preço e os métodos de pagamento da sua oferta.
`amountCents` é expresso em centavos. A criação retorna um link; o pagamento ocorre quando o comprador conclui o checkout. Para pré-preencher os dados do comprador em uma única chamada ou limitar a quantidade de pagamentos aprovados, envie `customer` e `maxPayments` conforme o guia de [links de pagamento](/guias/links-de-pagamento#dados-do-comprador-no-checkout). Veja também o [primeiro link](/inicio/primeiro-link).
# Liste links de pagamento
Source: https://docs.sinnu.com.br/api/links/listar
GET /api/payment-links
Consulte os links da empresa com paginação.
Use `page` e `pageSize`. No SDK, a operação corresponde a `sinnu.links.list()`.
# Liste as transações de um link
Source: https://docs.sinnu.com.br/api/links/transacoes
GET /api/payment-links/{id}/transactions
Encontre os pagamentos associados a um link.
O campo `amount` desta resposta está em **reais**, diferente da API de transações. Um link pode ter várias transações.
# Consulte uma transação
Source: https://docs.sinnu.com.br/api/transacoes/consultar
GET /api/transactions/{id}/
Confira o estado atual de um pagamento pelo identificador.
Use esta consulta para [conciliar um evento](/guias/conciliacao). O `amount` retornado está em centavos.
# Estorne uma transação
Source: https://docs.sinnu.com.br/api/transacoes/estornar
POST /api/transactions/{id}/refund/
Solicite uma devolução total de um pagamento.
Esta operação altera uma transação real e exige o escopo `transactions:refund` na chave. Confira a decisão de devolução antes de executar. O contrato não oferece valor parcial. Após timeout, consulte a transação antes de repetir.
# Liste transações
Source: https://docs.sinnu.com.br/api/transacoes/listar
GET /api/transactions/
Consulte os pagamentos da empresa com filtros e paginação.
Os valores monetários dessa resposta são expressos em centavos. Uma aprovação aparece com `status: approved`.
# Ajuda com sua integração
Source: https://docs.sinnu.com.br/comunidade/ajuda
Reúna o contexto necessário para investigar uma dúvida ou falha.
Envie sua dúvida para [suporte@sinnu.com.br](mailto:suporte@sinnu.com.br).
## Para dúvidas de implementação
Conte o resultado desejado, a linguagem ou framework e a página que você está seguindo. Se o problema for de instalação, inclua a versão do runtime e a origem do pacote.
## Para uma requisição que falhou
Use este modelo, removendo chaves e dados pessoais:
```text Modelo de atendimento theme={null}
Assunto: Integração — resumo do problema
Recurso: link / transação / webhook
Operação: método HTTP e caminho
Horário e fuso:
Status HTTP:
Identificador do recurso:
Resultado esperado:
Resultado observado:
Exemplo mínimo sem segredos:
```
Não envie `Authorization`, chave de API, segredo de webhook, dados de cartão ou um dump completo do cliente.
## Antes de abrir o chamado
| Problema | Confira primeiro |
| - | - |
| `npm install @sinnu-dev/sdk` retorna `404` | [Disponibilidade do SDK](/sdk/instalacao). |
| Chamada não autentica | [Autenticação](/fundamentos/autenticacao). |
| Valor parece cem vezes maior ou menor | [Unidades dos valores](/fundamentos/valores-e-status). |
| Assinatura inválida | Corpo original e segredo em [webhooks](/guias/webhooks). |
| Pagamento repetido na sua aplicação | [Processamento idempotente](/guias/conciliacao). |
Para notificações operacionais pelo Discord, consulte a configuração de integrações no painel e peça ao suporte orientação sobre os eventos disponíveis para sua empresa.
# Melhore esta documentação
Source: https://docs.sinnu.com.br/comunidade/contribuir
Ajude a tornar cada instrução mais precisa, útil e fácil de seguir.
Você pode contribuir apontando um passo que não funciona, uma explicação ambígua ou um exemplo que ajudaria sua integração.
## Envie uma correção
Compartilhe com [suporte@sinnu.com.br](mailto:suporte@sinnu.com.br):
1. O endereço da página.
2. O trecho que precisa mudar.
3. O comportamento que você verificou.
4. Uma sugestão de texto ou um exemplo mínimo, quando possível.
## Compartilhe um exemplo
Prefira exemplos com uma tarefa definida e poucas dependências. Informe linguagem, versão, pré-requisitos e resultado esperado. Remova credenciais, dados pessoais e identificadores de clientes reais.
## Como avaliamos uma contribuição
O conteúdo precisa refletir o contrato atual, explicar unidades e estados e indicar limites relevantes. Exemplos de pagamento precisam separar interface, servidor e confirmação.
Uma sugestão para uma funcionalidade nova não significa que ela já esteja disponível. A documentação deve deixar essa diferença visível para quem está implementando.
# Exemplos por tarefa
Source: https://docs.sinnu.com.br/comunidade/exemplos
Vá direto ao código que resolve a próxima etapa da sua integração.
| Sua tarefa | Exemplo | Resultado |
| - | - | - |
| Fazer a primeira chamada | [Primeiro link com cURL](/inicio/primeiro-link) | Um link e um slug para abrir o checkout. |
| Criar um link em TypeScript | [SDK de links](/sdk/links) | Um objeto `PaymentLink` tipado. |
| Usar Next.js | [Integração no servidor](/sdk/nextjs) | Serviço de criação separado da interface. |
| Receber eventos | [Handler de webhook](/sdk/webhooks) | Validação antes da persistência. |
| Acompanhar pagamentos | [Conciliação](/guias/conciliacao) | Atualização idempotente do pedido. |
| Percorrer transações | [Paginação](/sdk/paginacao-e-erros) | Processamento progressivo da listagem. |
| Abrir o checkout em React | [Botão de pagamento](/elements/botao-de-pagamento) | Navegação sem chave no navegador. |
| Embutir o checkout no seu site | [Início rápido do Sinnu Elements](/elements/inicio-rapido) | Pix e cartão num elemento seguro da sinnu, sem chave no navegador. |
| Ver uma integração completa | [Exemplo: propostas pagas pelo WhatsApp](/elements/exemplo-propostas) | App Next.js que cria um link por proposta, cobra no elemento `payment` e libera pelo webhook. |
| Usar seus campos e seu botão | [Elemento payment](/elements/pagamento) | `confirm()` com o comprador do seu formulário. |
| Exibir o estado | [Status de pagamento](/elements/status-de-pagamento) | Mensagem acessível e valor formatado. |
## Convenções dos exemplos
Valores, nomes, e-mails e identificadores são fictícios. Substitua placeholders pelo recurso retornado à sua empresa. Os exemplos com SDK pressupõem que você já [obteve o pacote](/sdk/instalacao).
Uma demonstração de interface não simula um pagamento. As chamadas para `api.sinnu.com.br` usam produção.
# Construa junto com a sinnu
Source: https://docs.sinnu.com.br/comunidade/visao-geral
Encontre exemplos, compartilhe o contexto da sua integração e ajude a melhorar a documentação.
Uma boa integração começa com uma resposta clara e continua com exemplos que funcionam. Esta área reúne os caminhos para quem desenvolve com a sinnu.
> [card] [Encontre um exemplo](/comunidade/exemplos)
>
> Escolha pela tarefa que você precisa resolver.
> [card] [Peça ajuda](/comunidade/ajuda)
>
> Envie o contexto certo para investigar sua integração.
> [card] [Sugira uma melhoria](/comunidade/contribuir)
>
> Mostre o que ficou confuso ou compartilhe um exemplo.
> [card] [Explore o Sinnu Elements](/elements/visao-geral)
>
> Elementos embutidos e receitas de interface para o seu produto.
## Canal de contato
Fale com **[suporte@sinnu.com.br](mailto:suporte@sinnu.com.br)**. Informe que o assunto é uma integração e inclua a página ou o recurso relacionado.
Os canais públicos de colaboração serão listados aqui quando estiverem disponíveis. Os exemplos e guias deste portal já podem orientar sua implementação pela API.
# Acessibilidade nas interfaces
Source: https://docs.sinnu.com.br/elements/acessibilidade
Faça o fluxo de pagamento funcionar com teclado, leitura assistiva e diferentes tamanhos de tela.
## A ação precisa ser compreensível
Use rótulos como “Ir para o pagamento” e “Consultar pagamento”. Para navegação, prefira uma âncora; para uma ação no estado da página, um botão.
## O estado precisa estar escrito
“Aguardando pagamento”, “Pagamento aprovado” e “Pagamento não aprovado” devem aparecer como texto. Não dependa de um ponto colorido ou de uma animação.
Quando a situação mudar sem recarregar a página, use uma região de status. Evite anunciar o mesmo texto repetidamente a cada consulta.
## Teclado e foco
Todos os controles precisam de foco visível. Ao abrir um modal, leve o foco para seu conteúdo, permita fechar por teclado e devolva o foco ao elemento que o abriu.
## Formulários e erros
Associe `label` e campo. Mostre o erro próximo ao campo, explique o que corrigir e preserve os valores preenchidos. Erros de comunicação não devem apagar o pedido nem levar a uma nova cobrança automática.
## Tamanho e contraste
Mantenha alvos de toque de pelo menos 44 × 44 px nas receitas deste portal. Confira contraste em ambos os temas e teste zoom de 200%, tela de 320 px e preferência por movimento reduzido.
## Verifique o fluxo completo
Percorra do botão ao retorno do checkout só com teclado. Confira estados de espera, aprovação, recusa e falha de rede. A revisão visual de uma tela não comprova a acessibilidade da integração inteira.
# Aparência
Source: https://docs.sinnu.com.br/elements/aparencia
As variáveis de cor, cantos e fonte que o Sinnu Elements aceita, e os limites de cada uma.
Ajuste o elemento à identidade do seu site com seis variáveis. Elas valem para todos os elementos criados pela mesma instância de `createElements`.
```ts TypeScript theme={null}
import { createElements } from "@sinnu-dev/elements";
const elements = createElements({
link: "abc12345",
appearance: {
variables: {
colorPrimary: "#C6F211",
colorBackground: "#FFFFFF",
colorText: "#111111",
colorDanger: "#D92D20",
borderRadius: "8px",
fontFamily: "system",
},
},
});
```

Padrão

Com a cor, os cantos e a fonte da marca
## Variáveis
| Variável | Valores aceitos | Onde aparece |
| - | - | - |
| `colorPrimary` | `#RGB` ou `#RRGGBB` | Botão de pagar, destaques e anel de foco. O texto sobre essa cor fica preto ou branco, o que tiver mais contraste. |
| `colorBackground` | `#RGB` ou `#RRGGBB` | Fundo do elemento e dos painéis. |
| `colorText` | `#RGB` ou `#RRGGBB` | Texto principal. |
| `colorDanger` | `#RGB` ou `#RRGGBB` | Mensagens de erro. |
| `borderRadius` | Inteiro de `0px` a `24px` | Cantos de campos, botões e painéis. |
| `fontFamily` | `system`, `inter` ou `geist` | Fonte do elemento. `system` usa a fonte do sistema do comprador. |
Sem uma variável, o elemento usa o visual padrão do checkout da sinnu.
## Limites
* **Só esses formatos.** Nomes de cor (`red`), `rgb()`, transparência, unidades diferentes de `px` e valores decimais não são aceitos.
* **Valor inválido é ignorado**, sem derrubar o elemento: o resto da aparência continua valendo. Uma variável desconhecida também é ignorada.
* **Nada vira CSS.** Não é possível injetar seletores, classes ou folhas de estilo no elemento: ele aplica só essas seis variáveis, depois de validá-las de novo.
* **A fonte vem da sinnu.** Não dá para carregar uma fonte própria dentro do elemento.
Para conferir o que será aplicado, use `sanitizeAppearance`: ela devolve só as variáveis válidas.
```ts TypeScript theme={null}
import { sanitizeAppearance } from "@sinnu-dev/elements";
sanitizeAppearance({ variables: { colorPrimary: "lime", borderRadius: "12px" } });
// { borderRadius: "12px" }
```
## Mudar a aparência
A aparência vai na URL do elemento. Para mudar, crie outra instância e monte o elemento de novo; o que o comprador preencheu se perde. Em React, mudar o conteúdo de `appearance` recria o elemento.
Garanta contraste suficiente entre `colorText` e `colorBackground`. Veja também os [fundamentos visuais](/elements/fundamentos-visuais) e a [acessibilidade](/elements/acessibilidade).
# Botão de pagamento
Source: https://docs.sinnu.com.br/elements/botao-de-pagamento
Uma âncora acessível para abrir o checkout a partir de um slug público.
Use este componente depois de criar um link no servidor. Ele não cria cobranças: apenas navega para o checkout.
## Prévia
PRÉVIA VISUAL
Ir para o pagamento
O exemplo visual não inicia uma cobrança.
## Código
```tsx payment-button.tsx theme={null}
type PaymentButtonProps = {
slug: string | null;
label?: string;
};
export function PaymentButton({
slug,
label = "Ir para o pagamento",
}: PaymentButtonProps) {
if (!slug?.trim()) {
return ;
}
const href = new URL(encodeURIComponent(slug), "https://pay.sinnu.com.br/").href;
return {label};
}
```
## Propriedades
| Prop | Tipo | Descrição |
| - | - | - |
| `slug` | `string \| null` | Slug retornado pela sinnu. `null` exibe o estado indisponível. |
| `label` | `string` | Texto da ação. Padrão: “Ir para o pagamento”. |
```tsx Uso theme={null}
```
O componente restringe a URL à origem do checkout e codifica o slug. Para navegação, ele usa uma âncora nativa, que preserva os comportamentos de teclado e de abertura em outra aba.
## Estilo sugerido
```css CSS theme={null}
.sinnu-pay-button {
display: inline-flex;
align-items: center;
justify-content: center;
min-height: 44px;
padding: 12px 22px;
border: 0;
border-radius: 999px;
background: #C6F211;
color: #0A0B09;
font: inherit;
font-weight: 600;
text-decoration: none;
}
.sinnu-pay-button:focus-visible {
outline: 3px solid currentColor;
outline-offset: 4px;
}
.sinnu-pay-button:disabled {
opacity: 0.5;
cursor: not-allowed;
}
```
Mantenha uma ação principal por etapa. Se abrir uma nova aba por escolha do seu produto, informe esse comportamento no texto acessível.
# Elemento checkout
Source: https://docs.sinnu.com.br/elements/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.

Antes, confira os [requisitos](/elements/visao-geral): 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}
```
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](/elements/aparencia). |
| `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](/elements/eventos).
## O que o comprador vê
> [tab] Pix
>
> 
> [tab] Cartão
>
> 
> [tab] Aprovado
>
> 
* **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](/elements/seguranca#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](/elements/seguranca).
> [card] [Só os meios de pagamento](/elements/pagamento)
>
> Use o elemento `payment` com o seu formulário.
> [card] [Em React](/elements/react)
>
> O mesmo elemento como componente.
# Eventos e erros
Source: https://docs.sinnu.com.br/elements/eventos
Referência dos eventos do Sinnu Elements, dos códigos de failed e error e da classe SinnuElementsError.
Todo elemento avisa a sua página por eventos. Escute com `element.on(evento, handler)`, que devolve uma função para cancelar a escuta. Em React, cada evento vira uma prop (`ready` → `onReady`, `pix_created` → `onPixCreated`).
```ts TypeScript theme={null}
const off = checkout.on("completed", ({ transactionId, amountCents }) => {
// amountCents em centavos: 19900 é R$ 199,00.
});
off(); // para de escutar
```
Um erro lançado dentro de um handler é reportado como erro não tratado, no console, e não impede os outros handlers. O loader só aceita mensagens que vêm do elemento, da origem `pay.sinnu.com.br` e do canal daquele elemento; o resto é descartado em silêncio.
## Eventos
| Evento | Payload | Quando |
| - | - | - |
| `ready` | `{ element, methods }` | O formulário está pronto. Uma vez por montagem. |
| `resize` | `{ height }` | A altura do conteúdo mudou. O loader já ajusta a altura do elemento. |
| `change` | `{ method, complete }` | O comprador trocou de método, ou o cartão ficou completo ou incompleto. |
| `processing` | `{ requestId? }` | A cobrança começou. |
| `pix_created` | `{ transactionId, amountCents, expiresAt, qrCode, requestId? }` | O QR Code foi gerado e está na tela, dentro do elemento. |
| `completed` | `{ transactionId, status, method, amountCents, reference?, requestId? }` | Pagamento aprovado: cartão na hora, Pix quando o pagamento é confirmado. |
| `failed` | `{ code, message, retryable, requestId? }` | A cobrança falhou. O formulário continua usável. |
| `expired` | `{ transactionId }` | O Pix venceu sem pagamento. |
| `error` | `{ code, message }` | O elemento não montou. É fatal para ele. |
### Campos
| Campo | Valor |
| - | - |
| `element` | `"checkout"` ou `"payment"`. |
| `methods` | Meios disponíveis no link: `"pix"` e `"card"`. Vazio quando o link não está disponível agora, como um link pausado. |
| `height` | Altura do conteúdo, em px: inteiro de 0 a 10000. |
| `method` | `"pix"` ou `"card"`. |
| `complete` | No Pix, sempre `true`. No cartão, `true` com número, validade e CVV válidos. |
| `transactionId` | ID da transação, o mesmo de `GET /api/transactions/{id}`. |
| `amountCents` | Valor em **centavos**. `19900` é R\$ 199,00. |
| `expiresAt` | Vencimento do QR Code, em ISO 8601. |
| `qrCode` | O Pix copia e cola. |
| `status` | Sempre `"approved"` no `completed`. |
| `reference` | O `reference` com que o elemento foi montado, quando houver. |
| `requestId` | Presente quando o evento responde a um `confirm()` do elemento `payment`. |
O `completed` serve para a interface. Libere o pedido pelo webhook `transaction.approved` ou consultando a transação no servidor: veja [segurança](/elements/seguranca).
## Códigos de `failed`
| Código | Significado |
| - | - |
| `card_declined` | O cartão foi recusado ou a autenticação do banco não foi concluída. |
| `invalid_customer` | Os dados do comprador enviados no `confirm()` não passaram na validação. |
| `invalid_card` | Os dados do cartão estão incompletos ou inválidos. |
| `rate_limited` | Muitas tentativas em pouco tempo. Aguarde antes de tentar de novo. |
| `link_unavailable` | O link não está disponível para pagamento agora, por exemplo pausado. |
| `network_error` | Falha de conexão do comprador ou do elemento. |
| `unknown` | Outra falha. Com `retryable: false`, o desfecho é incerto ou o pagamento já foi concluído: consulte a transação antes de cobrar de novo. É o que chega quando a cobrança é bloqueada porque o pagamento já foi aprovado ou ainda está em confirmação. |
Decida pelo `retryable` que chega com cada falha. `message` vem em pt-BR, pronta para mostrar ao comprador, sem detalhe interno.
`rate_limited` e `network_error` também podem chegar logo ao montar, sem `requestId`, quando o link não pôde ser carregado. Nesse caso, monte de novo depois de alguns segundos.
## Códigos de `error`
| Código | Significado | O que fazer |
| - | - | - |
| `origin_not_allowed` | A origem da página não está entre os domínios permitidos da empresa. | Cadastre a origem exata em **Configurações → Checkout embutido → Domínios permitidos**. |
| `link_not_found` | O slug não corresponde a um link. | Confira o slug. |
| `unsupported_link` | O link é só de assinatura. A v1 vende só avulso; um link que também aceita compra avulsa abre nela. | Use um link de venda avulsa. |
| `invalid_request` | Os parâmetros da URL do elemento são inválidos. | Monte o elemento pelo loader, sem alterar a URL do elemento. |
| `load_timeout` | O elemento não mandou `ready` dentro de `loadTimeoutMs` (padrão 15 s). Emitido pelo loader. | Em geral, o domínio da página não está cadastrado e o navegador bloqueou o elemento. Confira **Domínios permitidos** e o console. |
Depois de um `error`, o elemento não serve mais para cobrar: `confirm()` rejeita com o mesmo erro. Ofereça uma alternativa, como o link do checkout hospedado.
## `SinnuElementsError`
Todo erro do pacote é uma `SinnuElementsError`, com:
| Propriedade | Descrição |
| - | - |
| `code` | Um código de `failed`, de `error` ou do loader. |
| `message` | Em `failed` e `error`, texto em pt-BR para o comprador. Nos códigos do loader, texto para quem integra. |
| `retryable` | `true` quando o comprador pode tentar de novo. |
```ts TypeScript theme={null}
import { SinnuElementsError } from "@sinnu-dev/elements";
try {
await payment.confirm({ customer });
} catch (error) {
if (error instanceof SinnuElementsError && error.retryable) {
mostrarAviso(error.message);
}
}
```
### Códigos do loader
| Código | Quando |
| - | - |
| `invalid_config` | Opção ou argumento inválido em `createElements`, `create`, `mount`, `on` ou `confirm`. Lançado na hora: é erro de integração. |
| `confirm_in_progress` | Já há um `confirm()` em andamento neste elemento. |
| `timeout` | O `confirm()` não recebeu resposta no prazo. A cobrança pode ter acontecido: consulte a transação. |
| `unmounted` | O elemento foi desmontado com um `confirm()` pendente. Consulte a transação. |
| `destroyed` | O elemento foi destruído com um `confirm()` pendente, ou foi usado depois de destruído. |
| `not_mounted` | O `` ainda não montou o elemento. |
| `unsupported_environment` | Sem navegador (por exemplo, `mount()` no servidor), página fora de `http(s)` ou sem `crypto.getRandomValues`. |
# Exemplo completo: propostas pagas pelo WhatsApp
Source: https://docs.sinnu.com.br/elements/exemplo-propostas
Um app Next.js de propostas que cria um link por proposta, cobra no elemento payment e libera o pedido só pelo webhook.
O **Propostiva** é o app de exemplo do Sinnu Elements: o sistema de propostas de uma agência fictícia. A agência monta a proposta, envia o link pelo WhatsApp, e o cliente paga com Pix ou cartão na própria página da proposta, pelo [elemento `payment`](/elements/pagamento). Serve de modelo para qualquer negócio que vende produto, serviço ou software e quer receber dentro do próprio site.
O endereço do ambiente de demonstração (sandbox) é `https://propostiva.sinnu.cloud`: um domínio fora da sinnu, como o site de um cliente. Nenhum pagamento feito lá é real.
## Como funciona
**1. A agência cria a proposta**
O servidor do app cria um link de pagamento para a proposta, com o total, o máximo de parcelas e quem paga os juros. Junto nasce um pedido no banco do app; o `id` dele é a `reference`.
**2. A agência envia pelo WhatsApp**
A mensagem leva o endereço da página da proposta. O endereço tem um token aleatório e nenhum dado pessoal.
**3. O cliente paga na página da proposta**
A página coleta nome, e-mail, celular e CPF ou CNPJ e chama `confirm({ customer })`. O QR Code do Pix, os campos do cartão e o desafio do banco ficam dentro do elemento.
**4. O webhook libera o pedido**
O evento assinado `transaction.approved` marca o pedido como pago. A página, que consultava o servidor do app desde o `completed`, mostra a confirmação. O link é arquivado para ninguém pagar de novo por ele.
## Onde está cada parte
O que é integração com a sinnu fica separado do produto fictício. Copie a integração e troque o resto pelo seu sistema.
| Parte | No exemplo | O que faz |
| - | - | - |
| Cliente da API | `src/sinnu/client.ts` | O SDK com a chave secreta. Só roda no servidor. |
| Link por proposta | `src/sinnu/payment-link.ts` | O corpo de `links.create`, em centavos. |
| Pedido | `src/sinnu/orders.ts` | Os estados do pedido: aguardando, pago, estornado, contestado. |
| Webhook | `src/sinnu/webhook.ts` e `src/app/api/webhooks/sinnu/route.ts` | Assinatura, conferências e idempotência. |
| Status para a página | `src/app/api/propostas/[token]/status/route.ts` | Diz à página se o pedido já está pago. |
| Tela de pagamento | `src/components/public/pay-panel.tsx`, `src/sinnu/payment-flow.ts` e `src/sinnu/use-payment-flow.ts` | O elemento `payment`, o `confirm()` e o que a tela mostra em cada evento. |
| Content Security Policy | `next.config.ts` | Libera o elemento do checkout em `frame-src`. |
## Um link por proposta
O valor de cada proposta é diferente, e o elemento cobra pelo link. Por isso o app cria um link para cada proposta:
```ts TypeScript theme={null}
const link = await sinnu.links.create({
title: proposal.title,
amountCents: proposalTotalCents(proposal.items), // centavos
methods: ["pix", "credit_card"],
maxInstallments: proposal.maxInstallments,
interestMode: proposal.interestPaidBy === "client" ? "pass_to_customer" : "absorb",
externalReference: proposal.id,
});
```
A chave precisa dos escopos `links:write`, para criar e arquivar o link, e `transactions:read`, para conferir a venda no webhook. Veja [escopos](/fundamentos/autenticacao).
## Libere só pelo webhook
O `completed` e o resultado do `confirm()` rodam no navegador do cliente. No exemplo, eles só mudam a tela para "confirmando". Quem marca o pedido como pago é o webhook, depois de quatro conferências:
```ts TypeScript theme={null}
// 1. A assinatura, sobre o corpo cru da requisição.
const event = sinnu.webhooks.constructEvent({ payload: rawBody, signature, secret });
// 2. A referência é um pedido seu, e a venda é do link desse pedido.
const order = await orders.get(event.data.reference);
if (!order || event.data.link?.id !== order.linkId) return ok();
// 3. O valor, na mesma unidade: a transação na API vem em centavos.
const tx = await sinnu.transactions.get(event.data.id);
if (tx.status === "pending") throw new Error("ainda pending"); // responda 5xx: a sinnu reenvia
if (tx.status !== "approved" || tx.reference !== order.id) return ok();
if (tx.productAmount !== order.amountCents) return ok();
// 4. Idempotente: o pedido só sai de "aguardando" uma vez.
await orders.markPaidIfPending(order.id, tx.id);
```
* **`data.amount` vem em reais** e inclui os juros quando o cliente paga o parcelamento. Por isso o exemplo compara `productAmount`, o preço antes dos juros, em centavos. Veja [valores e status](/fundamentos/valores-e-status).
* **A mesma entrega pode chegar mais de uma vez**, e fora de ordem. No banco, a marcação é um `UPDATE ... WHERE id = ? AND status = 'pending'`, conferindo as linhas afetadas.
* **Transação ainda `pending` na API**: responda 5xx. Com 200, a sinnu daria o evento por entregue.
* **Arquive o link depois de pago** (`sinnu.links.archive`). O exemplo faz isso depois de responder ao webhook, para a resposta sair rápido.
## A tela de pagamento
* **Confirmando até o servidor dizer que está pago.** Depois do `completed`, a página consulta o servidor do app até ele responder que o pedido está pago.
* **Volta do app do banco.** Quem paga Pix pelo celular sai para o app do banco e volta. Quando a aba fica visível de novo, a página consulta na hora.
* **Recarregar não cobra de novo.** Entre o `completed` e o webhook, o pedido ainda está "aguardando". O exemplo guarda o `transactionId` na aba e, se o cliente recarregar, a tela volta para "confirmando" em vez de mostrar o formulário outra vez.
* **Falhas.** A tela decide pelo `retryable` de cada `failed`. Um `unknown` com `retryable: false` pede para conferir antes de cobrar de novo. Veja [eventos e erros](/elements/eventos).
## O que configurar
1. **Sinnu Elements liberado para a empresa.** [Fale com o suporte de integração](/comunidade/ajuda).
2. **A origem exata do site em Domínios permitidos**, em **Configurações → Checkout embutido**. `https://www.loja.exemplo.com.br` é outra origem que `https://loja.exemplo.com.br`. Veja [domínios permitidos](/elements/seguranca#domínios-permitidos).
3. **Um webhook** assinando `transaction.*`, apontando para a rota do app. Veja [webhooks](/guias/webhooks).
4. **A Content Security Policy do site** com o checkout em `frame-src`. O exemplo usa a variante simples, com `'unsafe-inline'` em `script-src`. Em produção, prefira a variante com nonce.
5. **`reference` e endereços sem dado pessoal.** Use o `id` do pedido e um token aleatório, nunca e-mail, CPF ou telefone.
> [card] [Elemento payment](/elements/pagamento)
>
> O `confirm()` com o comprador do seu formulário.
> [card] [Segurança](/elements/seguranca)
>
> Domínios permitidos, 3DS e liberação do pedido.
# Fundamentos visuais
Source: https://docs.sinnu.com.br/elements/fundamentos-visuais
Cor, tipografia e hierarquia para interfaces claras no ecossistema sinnu.
O design system usado nas aplicações da sinnu combina superfícies escuras, destaque lima e texto de alto contraste. Neste portal, o tema claro tem um verde mais escuro para manter a leitura dos links.
## Cor com função
| Token da interface | Valor | Papel |
| - | - | - |
| `brand.lime` | `#C6F211` | Ação principal e destaque. |
| `surface.canvas` | `#0A0B09` | Fundo principal escuro. |
| `surface.surface` | `#141511` | Superfície de conteúdo. |
| `text.primary` | `#F4F4EF` | Texto principal sobre fundo escuro. |
| `brand.amber` | `#E8B54A` | Situações de espera. |
| `brand.coral` | `#E86A4A` | Atenção e falhas. |
Texto sobre lima deve ser escuro. Use texto e ícone para identificar um estado; a cor reforça a mensagem.
## Tipografia
**Instrument Sans** sustenta a leitura da interface. **Space Grotesk** aparece em títulos e números de destaque. Use uma fonte monoespaçada para identificadores e código.
Não transforme o logotipo em texto com uma fonte parecida: use os arquivos oficiais da marca.
## Hierarquia
Reserve o botão lima para a ação principal. Agrupe informações do mesmo pagamento, mostre o valor com sua unidade e escreva a ação por inteiro: “Ir para o pagamento” comunica melhor do que “Continuar” fora de contexto.
## Pacotes internos
`@repo/design` contém tokens TypeScript e CSS; `@repo/ui` reúne componentes de interface do workspace. Se você desenvolve dentro do monorepo, use essas fontes. Eles não são publicados: numa aplicação externa, use as receitas desta documentação.
O pacote público de interface da sinnu é o `@sinnu-dev/elements`, do Sinnu Elements, que embute o checkout no seu site. As cores, os cantos e a fonte dele se ajustam pela [aparência do Sinnu Elements](/elements/aparencia), não pelos tokens acima.
# Início rápido
Source: https://docs.sinnu.com.br/elements/inicio-rapido
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](/comunidade/ajuda).
**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](/elements/seguranca).
**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](/inicio/primeiro-link).
**4. Monte o elemento**
Escolha entre o arquivo pronto, via `
```
* `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](/elements/react).
**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](/guias/webhooks) 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](/elements/eventos).
> [card] [Elemento checkout](/elements/checkout)
>
> Opções, eventos e o que o comprador vê.
> [card] [Elemento payment](/elements/pagamento)
>
> Seus campos, seu botão e o `confirm()`.
# Elemento payment
Source: https://docs.sinnu.com.br/elements/pagamento
Só Pix e cartão dentro do elemento: sua página coleta o comprador, mostra o botão e chama confirm().
O elemento `payment` mostra só os meios de pagamento: a escolha entre Pix e cartão e os campos do cartão. O resto da tela é seu: o formulário do comprador, o resumo do pedido e o botão de pagar. Quando o comprador confirma, a sua página chama `payment.confirm({ customer })` e o elemento cobra no método escolhido.

Antes, confira os [requisitos](/elements/visao-geral). As opções de `createElements` e os métodos `mount`, `on`, `unmount` e `destroy` são os mesmos do [elemento checkout](/elements/checkout).
## Código
O exemplo monta o elemento e traduz o resultado do `confirm()` em quatro situações para a sua interface: Pix gerado, pagamento aprovado, nova tentativa ou conferência no servidor.
```ts elements-payment.ts theme={null}
import {
createElements,
SinnuElementsError,
type CustomerInput,
type PaymentElement,
type SinnuElementsErrorCode,
} from "@sinnu-dev/elements";
type Order = { slug: string; orderId: string };
type PaymentScreen = {
setComplete(complete: boolean): void;
showPaid(transactionId: string): void;
showPixExpired(): void;
};
export function mountPayment(target: string | HTMLElement, order: Order, screen: PaymentScreen) {
const elements = createElements({ link: order.slug, reference: order.orderId });
const payment = elements.create("payment");
payment.on("change", ({ complete }) => screen.setComplete(complete));
payment.on("completed", ({ transactionId }) => screen.showPaid(transactionId));
payment.on("expired", () => screen.showPixExpired());
payment.mount(target);
return { payment, destroy: () => elements.destroy() };
}
export type PaymentOutcome =
| { status: "pix"; transactionId: string; qrCode: string; expiresAt: string }
| { status: "approved"; transactionId: string; amountCents: number }
| { status: "retry" | "check" | "stop"; code: SinnuElementsErrorCode; message: string };
const MAY_HAVE_BEEN_CHARGED = new Set(["timeout", "unmounted", "destroyed", "unknown"]);
export async function pay(
payment: Pick,
customer: CustomerInput,
): Promise {
try {
const result = await payment.confirm({ customer });
if (result.type === "pix_created") {
const { transactionId, qrCode, expiresAt } = result;
return { status: "pix", transactionId, qrCode, expiresAt };
}
return { status: "approved", transactionId: result.transactionId, amountCents: result.amountCents };
} catch (error) {
if (!(error instanceof SinnuElementsError)) throw error;
const { code, message } = error;
if (error.retryable) return { status: "retry", code, message };
if (MAY_HAVE_BEEN_CHARGED.has(code)) return { status: "check", code, message };
return { status: "stop", code, message };
}
}
```
```html Formulário theme={null}
```
```ts Uso theme={null}
const form = document.querySelector("#pedido")!;
const button = document.querySelector("#pagar")!;
const notice = document.querySelector("#aviso")!;
const { payment } = mountPayment("#meios-de-pagamento", { slug: "abc12345", orderId: "pedido-123" }, {
setComplete: (complete) => { button.disabled = !complete; },
showPaid: () => { notice.textContent = "Pagamento aprovado."; },
showPixExpired: () => { notice.textContent = "O Pix venceu. Gere um novo para continuar."; },
});
function readCustomer(data: FormData) {
return {
name: String(data.get("name")),
email: String(data.get("email")),
document: String(data.get("document")),
phone: String(data.get("phone")),
};
}
form.addEventListener("submit", async (event) => {
event.preventDefault();
button.disabled = true;
const outcome = await pay(payment, readCustomer(new FormData(form)));
if (outcome.status === "pix") notice.textContent = "Pague com o QR Code acima.";
if ("message" in outcome) notice.textContent = outcome.message;
if (outcome.status === "retry") button.disabled = false;
});
```
Habilite o botão pelo evento `change`: no Pix ele chega sempre com `complete: true`; no cartão, `complete` fica `true` quando número, validade e CVV estão preenchidos de forma válida.
## `confirm({ customer, timeoutMs })`
| Campo | Tipo | Descrição |
| - | - | - |
| `customer.name` | `string` | Nome do comprador. |
| `customer.email` | `string` | E-mail do comprador. |
| `customer.document` | `string` | CPF ou CNPJ. |
| `customer.phone` | `string` | Telefone do comprador. |
| `timeoutMs` | `number` | Opcional. Prazo para a resposta do elemento, em milissegundos. Padrão: `120000` (120 s). |
O elemento valida o comprador com as mesmas regras do checkout hospedado. Dado inválido volta como `invalid_customer`; cartão incompleto, como `invalid_card`. Um campo que não seja texto rejeita na hora.
Regras do `confirm()`:
* **Antes do `ready`**, ele espera o elemento ficar pronto e é enviado em seguida.
* **Um por vez.** Outro `confirm()` com um em andamento rejeita na hora com `confirm_in_progress`.
* **Resolve** com `{ type: "pix_created", ... }` ou `{ type: "completed", ... }`.
* **Rejeita** com `SinnuElementsError` (`code`, `message`, `retryable`) quando a cobrança falha.
* **No `timeout`**, a cobrança pode ter acontecido mesmo assim. Consulte a transação no seu servidor antes de tentar de novo. O mesmo vale para `unmounted` e `destroyed`, quando o elemento sai da página com um `confirm()` pendente.
## Pix
`confirm()` resolve assim que o QR Code é gerado, com `type: "pix_created"`, `transactionId`, `amountCents` (centavos), `expiresAt` (ISO 8601) e `qrCode` (o copia e cola). O QR Code, o botão de copiar e a contagem até o vencimento já aparecem dentro do elemento: você não precisa desenhá-los.

Depois disso, o desfecho chega por evento:
* `completed`, quando o pagamento é confirmado;
* `expired`, quando o Pix vence sem pagamento. O elemento volta para a escolha do método e um novo `confirm()` gera outro Pix.
Enquanto o QR Code está na tela, um novo `confirm()` responde `failed` com `unknown` e `retryable: true`. Esconda o seu botão de pagar até `completed` ou `expired`.
## Cartão
`confirm()` resolve com `type: "completed"` quando o cartão é aprovado. Se o emissor recusar a primeira tentativa e a autenticação do banco (3DS) estiver disponível, o desafio abre dentro do elemento e a promessa espera por ele. Veja [como o 3DS entra](/elements/seguranca#autenticação-do-banco-3ds). Parcelas e juros seguem o link.

Cartão preenchido

Desafio do banco (3DS) dentro do elemento

Aprovado
| Situação | O que chega | O que fazer |
| - | - | - |
| Cartão recusado | `card_declined`, `retryable: true` | Mostre `message` e deixe o comprador tentar de novo ou trocar de cartão. |
| Dados do cartão incompletos | `invalid_card`, `retryable: true` | Peça para conferir os campos do cartão. |
| Sem confirmação a tempo | `unknown`, `retryable: false` | Consulte a transação no servidor antes de cobrar de novo. |
| Pagamento já concluído neste elemento | `unknown`, `retryable: false` | Não cobre de novo: siga para a tela de sucesso. |
## Trate o `failed`
Decida pelo `retryable` recebido, e não só pelo código:
* `retryable: true`: mostre `message` e deixe o comprador tentar de novo. A mensagem já vem em pt-BR, pronta para o comprador.
* `retryable: false` com `unknown`, `timeout`, `unmounted` ou `destroyed`: o desfecho é incerto. Consulte a transação antes de oferecer outra cobrança.
* `retryable: false` com outro código, como `link_unavailable`: não ofereça nova tentativa.
A lista completa está em [eventos e erros](/elements/eventos).
## O que o elemento `payment` não mostra
Resumo do produto, campos do comprador, endereço e botão de pagar ficam de fora. Se o link pede o endereço do comprador, use o [elemento checkout](/elements/checkout): o `confirm()` envia só nome, e-mail, documento e telefone.
> [!WARNING]
>
> `completed` e a promessa do `confirm()` rodam no navegador do comprador. Libere o pedido pelo webhook `transaction.approved` ou consultando a transação no seu servidor. Veja [segurança](/elements/seguranca).
# Sinnu Elements em React
Source: https://docs.sinnu.com.br/elements/react
Os componentes SinnuCheckout e SinnuPayment, com confirm() pela ref.
Em React, use os componentes de `@sinnu-dev/elements/react`. `` é o [elemento checkout](/elements/checkout) e `` é o [elemento payment](/elements/pagamento), com `confirm()` exposto pela `ref`. Eles funcionam com React 18 ou superior.
```bash Terminal theme={null}
npm install @sinnu-dev/elements
```
## Código
O `PaymentStep` usa a função `pay` do [exemplo do elemento payment](/elements/pagamento), que aceita tanto o elemento quanto a `ref` do ``.
```tsx elements-react.tsx theme={null}
"use client";
import { useRef, useState } from "react";
import {
SinnuCheckout,
SinnuPayment,
type CustomerInput,
type SinnuPaymentHandle,
} from "@sinnu-dev/elements/react";
import { pay, type PaymentOutcome } from "./elements-payment";
type Order = { slug: string; orderId: string };
export function EmbeddedCheckout({ order, onPaid }: { order: Order; onPaid(transactionId: string): void }) {
return (
onPaid(transactionId)}
style={{ maxWidth: 560 }}
/>
);
}
export function PaymentStep({ order, customer }: { order: Order; customer: CustomerInput }) {
const payment = useRef(null);
const [complete, setComplete] = useState(false);
const [busy, setBusy] = useState(false);
const [paid, setPaid] = useState(false);
const [outcome, setOutcome] = useState(null);
async function handlePay() {
if (!payment.current) return;
setBusy(true);
try {
setOutcome(await pay(payment.current, customer));
} finally {
setBusy(false);
}
}
const waitingForPix = outcome?.status === "pix";
const canPay = !paid && !waitingForPix;
return (
);
}
```
```tsx Uso theme={null}
```
`slug` e `orderId` vêm do seu servidor. No Next.js (App Router), carregue o pedido num Server Component e passe só esses dois valores para o componente de cliente. A chave de API não entra na árvore do cliente.
## Props
As mesmas nos dois componentes.
| Prop | Tipo | Descrição |
| - | - | - |
| `link` | `string` | Obrigatória. Slug do link de pagamento. |
| `reference` | `string` | Pedido no seu sistema, até 255 caracteres. |
| `appearance` | `Appearance` | Veja [aparência](/elements/aparencia). |
| `baseUrl` | `string` | Padrão `https://pay.sinnu.com.br`. |
| `locale` | `"pt-BR"` | Único valor aceito na v1. |
| `loadTimeoutMs` | `number` | Prazo para carregar, em milissegundos. Padrão: `15000`. Esgotado, chama `onError` com `load_timeout`. |
| `className`, `style` | | Aplicados ao `
` que recebe o elemento. |
| `onReady`, `onResize`, `onChange`, `onProcessing`, `onPixCreated`, `onCompleted`, `onFailed`, `onExpired`, `onError` | função | Um handler por [evento](/elements/eventos), com o mesmo payload. |
## Quando o elemento é recriado
O elemento só é recriado quando muda `link`, `reference`, `baseUrl`, `locale`, `loadTimeoutMs` ou o conteúdo de `appearance`. Um objeto `appearance` novo com o mesmo conteúdo não remonta nada, e trocar os handlers a cada render também não.
Recriar o elemento descarta o que o comprador preencheu nele. Evite mudar essas props durante o pagamento.
## A `ref` do ``
A `ref` expõe só `confirm({ customer, timeoutMs })`, com as mesmas regras do [elemento payment](/elements/pagamento). Antes de o componente montar o elemento, `confirm()` rejeita com `not_mounted`.
## Renderização no servidor
Os componentes já trazem `"use client"`. No servidor, renderizam só o `
`; o elemento é criado no navegador, depois da montagem. O seu componente precisa de `"use client"` quando usa hooks, como o `PaymentStep` acima.
# Segurança do Sinnu Elements
Source: https://docs.sinnu.com.br/elements/seguranca
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](/guias/webhooks). 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](/sdk/transacoes).
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](/fundamentos/valores-e-status).
O webhook pode chegar mais de uma vez: atualize o pedido de forma idempotente, como em [conciliação](/guias/conciliacao).
## 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`](/elements/eventos#códigos-de-failed).
* **Desafio não concluído** chega como `card_declined`. Tempo esgotado ou desafio indisponível chega como `unknown`.

## 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:` e `http://127.0.0.1:` 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.
# Status de pagamento
Source: https://docs.sinnu.com.br/elements/status-de-pagamento
Mostre o estado recebido do servidor sem depender apenas de cor.
## Prévia
CONSULTORIA INICIAL / EXEMPLO
R\$ 99,00
Os estados acima são uma demonstração local. Nenhuma requisição de pagamento é executada.
## Código
```tsx payment-status.tsx theme={null}
const labels: Record = {
approved: "Pagamento aprovado",
pending: "Aguardando pagamento",
refused: "Pagamento não aprovado",
refunded: "Pagamento estornado",
chargeback: "Pagamento contestado",
};
type PaymentStatusProps = {
status: string;
amountCents: number;
};
export function PaymentStatus({ status, amountCents }: PaymentStatusProps) {
if (!Number.isSafeInteger(amountCents) || amountCents < 0) {
throw new Error("Use um valor não negativo em centavos.");
}
const label = labels[status] ?? "Status a confirmar";
const amount = new Intl.NumberFormat("pt-BR", {
style: "currency",
currency: "BRL",
}).format(amountCents / 100);
return (
{label}{amount}
);
}
```
## Propriedades
| Prop | Tipo | Descrição |
| - | - | - |
| `status` | `string` | Status da API de transações. Valores desconhecidos exibem “Status a confirmar”. |
| `amountCents` | `number` | Inteiro não negativo em centavos. |
```tsx Uso theme={null}
```
## De onde vêm os dados
Seu servidor consulta a transação e retorna o estado necessário à interface. Não conecte este componente diretamente ao corpo do webhook: nele, `amount` está em reais e a aprovação usa `paid`.
O componente anuncia mudanças de texto com `role="status"` e `aria-live="polite"`. Mantenha-o montado durante as atualizações para que tecnologias assistivas recebam a mudança.
# Sinnu Elements
Source: https://docs.sinnu.com.br/elements/visao-geral
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`](/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`](/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](/elements/botao-de-pagamento) | 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](/elements/status-de-pagamento) | 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: o formulário completo

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](/elements/aparencia) ajusta as cores dos elementos; os [fundamentos visuais](/elements/fundamentos-visuais) e a [acessibilidade](/elements/acessibilidade) 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](/elements/seguranca#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](/elements/seguranca).
## O que você precisa
1. **Sinnu Elements liberado para a sua empresa.** O recurso é ativado pela sinnu. [Fale com o suporte de integração](/comunidade/ajuda) 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](/inicio/primeiro-link) e guarde o `slug`.
4. **Um webhook configurado.** O pedido é liberado pelo evento assinado `transaction.approved`, não pelo navegador. Veja [webhooks](/guias/webhooks).
## Como um pagamento acontece

**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 `