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

# Abra o checkout

> Leve o comprador da sua interface ao checkout hospedado da sinnu.

Depois de criar um link, monte a URL com o `slug` retornado:

```ts Servidor theme={null}
const checkoutUrl = new URL(
  encodeURIComponent(link.slug),
  "https://pay.sinnu.com.br/",
).toString();
```

## Redirecionamento

O caminho mais direto é abrir o checkout na mesma aba. Use uma âncora com texto que explique a ação:

```html HTML theme={null}
<a href="https://pay.sinnu.com.br/SLUG_RETORNADO">
  Ir para o pagamento
</a>
```

Em React, use a [receita de botão de pagamento](https://docs.sinnu.com.br/elements/botao-de-pagamento.md). A URL vem do seu servidor e o componente não recebe uma chave secreta.

## Parâmetros de campanha

O helper do SDK monta a URL e codifica parâmetros:

```ts TypeScript theme={null}
const checkoutUrl = sinnu.checkout.url(link.slug, {
  query: { utm_source: "email", utm_campaign: "consultoria" },
});
```

O helper apenas monta a URL. Acrescentar um parâmetro não garante que o checkout o interprete como uma configuração funcional. Os parâmetros `utm_*` são lidos pelo [rastreamento da origem da venda](https://docs.sinnu.com.br/guias/rastreamento.md): com um pixel ligado no link, a venda mostra de onde veio e a compra chega à plataforma de anúncios.

## Pedido de cada venda

O link é o produto e pode ser vendido muitas vezes. Para saber qual pedido do seu sistema cada venda pagou, abra o checkout com `reference`:

```ts TypeScript theme={null}
const checkoutUrl = sinnu.checkout.url(link.slug, { reference: "pedido-123" });
// https://pay.sinnu.com.br/SLUG?ref=pedido-123
```

A referência fica gravada na venda e volta como `reference` em `GET /api/transactions`, no `data.reference` do webhook e no retorno para o `redirectUrl`. Ela tem até 255 caracteres. O código do produto vai no link, em `externalReference`, e volta como `externalRef` do item.

## Dados do comprador preenchidos

Quando o link é criado ou atualizado com `customer` (em uma única requisição) ou `linkedCustomer`, o checkout abre com nome, e-mail, telefone (se enviado) e CPF/CNPJ mascarado (`***.456.789-**`) já preenchidos, sem trafegar dados pessoais na URL. Veja os campos aceitos em [Links de pagamento](https://docs.sinnu.com.br/guias/links-de-pagamento.md#dados-do-comprador-no-checkout).

O comprador pode concluir o pagamento imediatamente ou clicar em **Alterar** ao lado do documento mascarado para pagar com outro CPF/CNPJ. Se preferir manter o formulário do comprador na sua própria página e renderizar apenas Pix e cartão, use o [elemento `payment`](https://docs.sinnu.com.br/elements/pagamento) e envie `customer` no `confirm()`.

## Depois do checkout

> [!NOTE]
>
> O retorno ao `redirectUrl` é liberado por empresa. Confirme com a sinnu se já está ativo para a sua antes de depender dele.

Com `redirectUrl` no link, o checkout leva o comprador de volta quando o pagamento é confirmado (cartão aprovado ou Pix pago), acrescentando à query:

| Parâmetro | Valor |
| - | - |
| `transactionId` | ID da transação, o mesmo de `GET /api/transactions/{id}`. |
| `reference` | O pedido com que o checkout foi aberto, quando houver. |
| `status` | `approved`. |

Se o cartão for recusado, o comprador continua no checkout para tentar de novo. Sem `redirectUrl`, ele fica na tela de sucesso da sinnu.

O comprador pode alterar a URL de retorno. Use os parâmetros só para mostrar a tela certa e libere o pedido pelo [webhook validado](https://docs.sinnu.com.br/guias/webhooks.md) ou consultando a transação no seu servidor.

## App nativo

No app, abra o checkout no navegador do sistema (`SFSafariViewController` no iOS, Custom Tabs no Android; no Expo, `WebBrowser.openAuthSessionAsync`). Use como `redirectUrl` o deep link do app, por exemplo `meuapp://pedido`, ou um universal link / app link. O retorno traz os mesmos parâmetros.

Evite abrir o checkout dentro de uma WebView própria: Apple Pay e a autenticação do banco dependem do navegador do sistema.

## Dentro do seu site

O checkout hospedado não pode ser embutido na sua página: `https://pay.sinnu.com.br/{slug}` responde com `frame-ancestors 'none'`. Use link, redirecionamento ou, no app, o navegador do sistema. Para receber dentro da sua página, use o [Sinnu Elements](https://docs.sinnu.com.br/elements/visao-geral.md).

Para o comprador pagar sem sair do seu site, use o [Sinnu Elements](https://docs.sinnu.com.br/elements/visao-geral.md): o mesmo checkout, com o mesmo link, servido numa página própria que só abre nos domínios cadastrados pela sua empresa. O `reference` funciona igual ao `?ref=` deste guia.


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