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

# Eventos e erros

> 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](https://docs.sinnu.com.br/elements/seguranca.md).

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


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