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

# Integre com Next.js

> Mantenha o SDK no servidor e passe apenas a URL pública para sua interface.

O fluxo tem três partes: um serviço de criação no servidor, uma interface que abre o checkout e um endpoint de webhook.

## 1. Prepare o ambiente

Obtenha o SDK conforme a [distribuição disponível](https://docs.sinnu.com.br/sdk/instalacao.md). Configure `SINNU_API_KEY` e `SINNU_WEBHOOK_SECRET` no servidor, sem o prefixo `NEXT_PUBLIC_`.

## 2. Crie um serviço de checkout

Coloque este código em um módulo usado apenas no servidor. No Next.js, use também `import "server-only"` para impedir uma importação acidental em um Client Component.

```ts checkout.ts theme={null}
import { Sinnu, type PaymentLinkCustomerInput } from "@sinnu-dev/sdk";

export async function createCheckout(
  apiKey: string,
  offer: {
    title: string;
    amountCents: number;
    customer?: PaymentLinkCustomerInput;
    maxPayments?: number;
  },
  fetchImpl?: typeof fetch,
) {
  if (!Number.isSafeInteger(offer.amountCents) || offer.amountCents <= 0) {
    throw new Error("Informe um preço positivo em centavos.");
  }
  const sinnu = new Sinnu({ apiKey, fetch: fetchImpl });
  const link = await sinnu.links.create({
    title: offer.title,
    amountCents: offer.amountCents,
    priceMode: "fixed",
    methods: ["pix", "credit_card"],
    maxInstallments: 1,
    ...(offer.customer ? { customer: offer.customer } : {}),
    ...(offer.maxPayments !== undefined ? { maxPayments: offer.maxPayments } : {}),
  });
  return { linkId: link.id, slug: link.slug, url: sinnu.checkout.url(link.slug) };
}
```

Em uma Route Handler ou Server Action, autentique o usuário quando o seu fluxo exigir, carregue o pedido e obtenha o preço do catálogo no servidor. Não repasse um preço recebido do navegador diretamente a `createCheckout`.

Guarde `linkId` junto do pedido antes de devolver a URL. Em caso de timeout, consulte os links existentes antes de repetir a criação.

## 3. Abra a URL no frontend

Use a [receita de botão](https://docs.sinnu.com.br/elements/botao-de-pagamento.md) com o `slug` retornado ou redirecione para `url`. Seu frontend não precisa importar `Sinnu`.

## 4. Confirme pelo servidor

Adicione um [handler de webhook](https://docs.sinnu.com.br/sdk/webhooks.md) com runtime Node.js. Atualize o pedido de forma idempotente após consultar o estado da transação.

## Confira antes de liberar

* O preço é determinado no servidor e enviado em centavos.
* O navegador recebe uma URL pública, sem chaves.
* Repetir um evento não libera o pedido novamente.
* Falha de persistência no webhook retorna erro.
* Uma URL de retorno não é tratada como confirmação financeira.


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