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

# Elemento payment

> Só Pix e cartão dentro do elemento: sua página coleta o comprador, mostra o botão e chama confirm().

O elemento `payment` mostra só os meios de pagamento: a escolha entre Pix e cartão e os campos do cartão. O resto da tela é seu: o formulário do comprador, o resumo do pedido e o botão de pagar. Quando o comprador confirma, a sua página chama `payment.confirm({ customer })` e o elemento cobra no método escolhido.

![Página de loja com o formulário do comprador e, abaixo, o elemento payment com a escolha entre Pix e cartão.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/pagamento-inicio.png?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=df718a83498ad4805cf8d1b8d11816e8)

Antes, confira os [requisitos](https://docs.sinnu.com.br/elements/visao-geral.md). As opções de `createElements` e os métodos `mount`, `on`, `unmount` e `destroy` são os mesmos do [elemento checkout](https://docs.sinnu.com.br/elements/checkout.md).

## Código

O exemplo monta o elemento e traduz o resultado do `confirm()` em quatro situações para a sua interface: Pix gerado, pagamento aprovado, nova tentativa ou conferência no servidor.

```ts elements-payment.ts theme={null}
import {
  createElements,
  SinnuElementsError,
  type CustomerInput,
  type PaymentElement,
  type SinnuElementsErrorCode,
} from "@sinnu-dev/elements";

type Order = { slug: string; orderId: string };

type PaymentScreen = {
  setComplete(complete: boolean): void;
  showPaid(transactionId: string): void;
  showPixExpired(): void;
};

export function mountPayment(target: string | HTMLElement, order: Order, screen: PaymentScreen) {
  const elements = createElements({ link: order.slug, reference: order.orderId });
  const payment = elements.create("payment");

  payment.on("change", ({ complete }) => screen.setComplete(complete));
  payment.on("completed", ({ transactionId }) => screen.showPaid(transactionId));
  payment.on("expired", () => screen.showPixExpired());

  payment.mount(target);
  return { payment, destroy: () => elements.destroy() };
}

export type PaymentOutcome =
  | { status: "pix"; transactionId: string; qrCode: string; expiresAt: string }
  | { status: "approved"; transactionId: string; amountCents: number }
  | { status: "retry" | "check" | "stop"; code: SinnuElementsErrorCode; message: string };

const MAY_HAVE_BEEN_CHARGED = new Set<SinnuElementsErrorCode>(["timeout", "unmounted", "destroyed", "unknown"]);

export async function pay(
  payment: Pick<PaymentElement, "confirm">,
  customer: CustomerInput,
): Promise<PaymentOutcome> {
  try {
    const result = await payment.confirm({ customer });
    if (result.type === "pix_created") {
      const { transactionId, qrCode, expiresAt } = result;
      return { status: "pix", transactionId, qrCode, expiresAt };
    }
    return { status: "approved", transactionId: result.transactionId, amountCents: result.amountCents };
  } catch (error) {
    if (!(error instanceof SinnuElementsError)) throw error;
    const { code, message } = error;
    if (error.retryable) return { status: "retry", code, message };
    if (MAY_HAVE_BEEN_CHARGED.has(code)) return { status: "check", code, message };
    return { status: "stop", code, message };
  }
}
```

```html Formulário theme={null}
<form id="pedido">
  <input name="name" autocomplete="name" required />
  <input name="email" type="email" autocomplete="email" required />
  <input name="document" inputmode="numeric" required />
  <input name="phone" type="tel" autocomplete="tel" required />
  <div id="meios-de-pagamento"></div>
  <p id="aviso" role="alert"></p>
  <button id="pagar" type="submit" disabled>Pagar</button>
</form>
```

```ts Uso theme={null}
const form = document.querySelector<HTMLFormElement>("#pedido")!;
const button = document.querySelector<HTMLButtonElement>("#pagar")!;
const notice = document.querySelector<HTMLElement>("#aviso")!;

const { payment } = mountPayment("#meios-de-pagamento", { slug: "abc12345", orderId: "pedido-123" }, {
  setComplete: (complete) => { button.disabled = !complete; },
  showPaid: () => { notice.textContent = "Pagamento aprovado."; },
  showPixExpired: () => { notice.textContent = "O Pix venceu. Gere um novo para continuar."; },
});

function readCustomer(data: FormData) {
  return {
    name: String(data.get("name")),
    email: String(data.get("email")),
    document: String(data.get("document")),
    phone: String(data.get("phone")),
  };
}

form.addEventListener("submit", async (event) => {
  event.preventDefault();
  button.disabled = true;

  const outcome = await pay(payment, readCustomer(new FormData(form)));

  if (outcome.status === "pix") notice.textContent = "Pague com o QR Code acima.";
  if ("message" in outcome) notice.textContent = outcome.message;
  if (outcome.status === "retry") button.disabled = false;
});
```

Habilite o botão pelo evento `change`: no Pix ele chega sempre com `complete: true`; no cartão, `complete` fica `true` quando número, validade e CVV estão preenchidos de forma válida.

## `confirm({ customer, timeoutMs })`

| Campo | Tipo | Descrição |
| - | - | - |
| `customer.name` | `string` | Nome do comprador. |
| `customer.email` | `string` | E-mail do comprador. |
| `customer.document` | `string` | CPF ou CNPJ. |
| `customer.phone` | `string` | Telefone do comprador. |
| `timeoutMs` | `number` | Opcional. Prazo para a resposta do elemento, em milissegundos. Padrão: `120000` (120 s). |

O elemento valida o comprador com as mesmas regras do checkout hospedado. Dado inválido volta como `invalid_customer`; cartão incompleto, como `invalid_card`. Um campo que não seja texto rejeita na hora.

Regras do `confirm()`:

* **Antes do `ready`**, ele espera o elemento ficar pronto e é enviado em seguida.
* **Um por vez.** Outro `confirm()` com um em andamento rejeita na hora com `confirm_in_progress`.
* **Resolve** com `{ type: "pix_created", ... }` ou `{ type: "completed", ... }`.
* **Rejeita** com `SinnuElementsError` (`code`, `message`, `retryable`) quando a cobrança falha.
* **No `timeout`**, a cobrança pode ter acontecido mesmo assim. Consulte a transação no seu servidor antes de tentar de novo. O mesmo vale para `unmounted` e `destroyed`, quando o elemento sai da página com um `confirm()` pendente.

## Pix

`confirm()` resolve assim que o QR Code é gerado, com `type: "pix_created"`, `transactionId`, `amountCents` (centavos), `expiresAt` (ISO 8601) e `qrCode` (o copia e cola). O QR Code, o botão de copiar e a contagem até o vencimento já aparecem dentro do elemento: você não precisa desenhá-los.

![Elemento payment depois do confirm(): Pix gerado com QR Code e contagem até o vencimento.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/pagamento-pix.png?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=3db93764b5c7bfca065f37e7d16ae8ba)

Depois disso, o desfecho chega por evento:

* `completed`, quando o pagamento é confirmado;
* `expired`, quando o Pix vence sem pagamento. O elemento volta para a escolha do método e um novo `confirm()` gera outro Pix.

Enquanto o QR Code está na tela, um novo `confirm()` responde `failed` com `unknown` e `retryable: true`. Esconda o seu botão de pagar até `completed` ou `expired`.

## Cartão

`confirm()` resolve com `type: "completed"` quando o cartão é aprovado. Se o emissor recusar a primeira tentativa e a autenticação do banco (3DS) estiver disponível, o desafio abre dentro do elemento e a promessa espera por ele. Veja [como o 3DS entra](https://docs.sinnu.com.br/elements/seguranca.md#autenticação-do-banco-3ds). Parcelas e juros seguem o link.

![Elemento payment com o cartão escolhido: número, validade, CVV e parcelas.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/pagamento-cartao.png?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=9bde295f71e1053133c2ecdd17588af6)

Cartão preenchido

![Desafio de autenticação do banco aberto dentro do elemento payment, sem sair da página da loja.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/pagamento-3ds.png?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=7c278073d4a91ecfa1b5e038268e86e3)

Desafio do banco (3DS) dentro do elemento

![Elemento payment com o pagamento aprovado e a confirmação na página da loja.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/pagamento-aprovado.png?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=c1bf33365b85507a2c2c18ccc20dacf2)

Aprovado

| Situação | O que chega | O que fazer |
| - | - | - |
| Cartão recusado | `card_declined`, `retryable: true` | Mostre `message` e deixe o comprador tentar de novo ou trocar de cartão. |
| Dados do cartão incompletos | `invalid_card`, `retryable: true` | Peça para conferir os campos do cartão. |
| Sem confirmação a tempo | `unknown`, `retryable: false` | Consulte a transação no servidor antes de cobrar de novo. |
| Pagamento já concluído neste elemento | `unknown`, `retryable: false` | Não cobre de novo: siga para a tela de sucesso. |

## Trate o `failed`

Decida pelo `retryable` recebido, e não só pelo código:

* `retryable: true`: mostre `message` e deixe o comprador tentar de novo. A mensagem já vem em pt-BR, pronta para o comprador.
* `retryable: false` com `unknown`, `timeout`, `unmounted` ou `destroyed`: o desfecho é incerto. Consulte a transação antes de oferecer outra cobrança.
* `retryable: false` com outro código, como `link_unavailable`: não ofereça nova tentativa.

A lista completa está em [eventos e erros](https://docs.sinnu.com.br/elements/eventos.md).

## O que o elemento `payment` não mostra

Resumo do produto, campos do comprador, endereço e botão de pagar ficam de fora. Se o link pede o endereço do comprador, use o [elemento checkout](https://docs.sinnu.com.br/elements/checkout.md): o `confirm()` envia só nome, e-mail, documento e telefone.

> [!WARNING]
>
> `completed` e a promessa do `confirm()` rodam no navegador do comprador. Libere o pedido pelo webhook `transaction.approved` ou consultando a transação no seu servidor. Veja [segurança](https://docs.sinnu.com.br/elements/seguranca.md).


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