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

# Concilie pagamentos

> Mantenha seu pedido consistente com a transação, inclusive quando eventos chegam mais de uma vez.

Use o webhook para saber **quando consultar** e a transação para saber **qual é o estado atual**.

## Guarde as relações

No seu banco, mantenha o identificador do pedido, a empresa, o `link.id` e os identificadores de transação encontrados. Um link reutilizável pode produzir vários pagamentos; não trate seu `slug` como uma transação única.

**1. Aceite somente eventos válidos**

Verifique a assinatura sobre o corpo original. Separe eventos de teste, quando marcados com `test: true`, para que não liberem pedidos reais.

**2. Consulte a transação**

Para eventos `transaction.*`, use `data.id` em `GET /api/transactions/{id}/`, com a chave da empresa correspondente.

**3. Valide o contexto**

Confira o vínculo com seu pedido, o valor esperado e a situação retornada. A resposta da API de transações usa centavos.

**4. Atualize uma única vez**

Faça a atualização do pedido e o registro de processamento na mesma transação de banco, com restrição de unicidade ou bloqueio apropriado. Uma reentrega não deve liberar o serviço novamente.

## Trate cada resultado

| Estado consultado | Comportamento da sua aplicação |
| - | - |
| `approved` | Confirme o recebimento e libere o pedido uma única vez. |
| `pending` | Continue aguardando. |
| `refused` | Informe que o pagamento não foi aprovado. |
| `refunded` | Registre o estorno e aplique a política do seu serviço. |
| `chargeback` | Registre a contestação e encaminhe para análise operacional. |
| Desconhecido | Preserve o valor recebido e investigue; não presuma aprovação. |

## Quando houver uma lacuna

Use a [listagem paginada](https://docs.sinnu.com.br/sdk/paginacao-e-erros.md) para reconciliar períodos em que seu endpoint ficou indisponível. O SDK atual oferece filtros por status, busca e cliente; não invente um filtro por data que o método não expõe.

Evite marcar um pagamento como recusado apenas porque seu servidor ainda não recebeu um webhook.


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