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

# Sinnu Elements em React

> Os componentes SinnuCheckout e SinnuPayment, com confirm() pela ref.

Em React, use os componentes de `@sinnu-dev/elements/react`. `<SinnuCheckout>` é o [elemento checkout](https://docs.sinnu.com.br/elements/checkout.md) e `<SinnuPayment>` é o [elemento payment](https://docs.sinnu.com.br/elements/pagamento.md), 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](https://docs.sinnu.com.br/elements/pagamento.md), que aceita tanto o elemento quanto a `ref` do `<SinnuPayment>`.

```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 (
    <SinnuCheckout
      link={order.slug}
      reference={order.orderId}
      onCompleted={({ transactionId }) => onPaid(transactionId)}
      style={{ maxWidth: 560 }}
    />
  );
}

export function PaymentStep({ order, customer }: { order: Order; customer: CustomerInput }) {
  const payment = useRef<SinnuPaymentHandle>(null);
  const [complete, setComplete] = useState(false);
  const [busy, setBusy] = useState(false);
  const [paid, setPaid] = useState(false);
  const [outcome, setOutcome] = useState<PaymentOutcome | null>(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 (
    <div>
      <SinnuPayment
        ref={payment}
        link={order.slug}
        reference={order.orderId}
        onChange={(event) => setComplete(event.complete)}
        onCompleted={() => setPaid(true)}
        onExpired={() => setOutcome(null)}
      />
      {outcome && "message" in outcome && <p role="alert">{outcome.message}</p>}
      {canPay && (
        <button type="button" disabled={!complete || busy} onClick={handlePay}>
          Pagar
        </button>
      )}
    </div>
  );
}
```

```tsx Uso theme={null}
<EmbeddedCheckout order={{ slug: "abc12345", orderId: "pedido-123" }} onPaid={mostrarObrigado} />

<PaymentStep
  order={{ slug: "abc12345", orderId: "pedido-123" }}
  customer={{ name, email, document, phone }}
/>
```

`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](https://docs.sinnu.com.br/elements/aparencia.md). |
| `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 `<div>` que recebe o elemento. |
| `onReady`, `onResize`, `onChange`, `onProcessing`, `onPixCreated`, `onCompleted`, `onFailed`, `onExpired`, `onError` | função | Um handler por [evento](https://docs.sinnu.com.br/elements/eventos.md), 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 `<SinnuPayment>`

A `ref` expõe só `confirm({ customer, timeoutMs })`, com as mesmas regras do [elemento payment](https://docs.sinnu.com.br/elements/pagamento.md). 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 `<div>`; o elemento é criado no navegador, depois da montagem. O seu componente precisa de `"use client"` quando usa hooks, como o `PaymentStep` acima.


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