Este guia explica exatamente como cobrar via Pix avulso (one-time) na API da Autra. É o caso mais comum de Pix: você gera um QR Code para o cliente pagar uma vez.

Não confunda com Pix Automático. Pix Checkout é cobrança única. Pix Automático é débito recorrente com autorização prévia do pagador. Para recorrência, veja a categoria Pix Automático.

Conceitos fundamentais

Termo	O que é
`transactionalToken`	Token de sessão de Pix Checkout, gerado por `/initialize`. Curta validade.
`qrCode`	Payload copia-e-cola do QR Code. Pode ser exibido como QR (gerando a imagem do lado do front) ou como texto pra colar no app do banco.
`pixId`	Identificador interno da Autra para esse Pix. Use para correlacionar webhooks.
`orderId`	ID do pedido no seu sistema. Recomendado para correlação cliente ↔ pagamento.
Status `PENDING`	QR criado, aguardando pagamento.
Status `AUTHORIZED`	Pagamento confirmado pelo banco (já caiu no fluxo).
Status `SETTLED`	Liquidado — dinheiro disponível na conta.
Status `EXPIRED`	QR não foi pago no prazo.

Antes de começar — checklist

Você tem client_id + client_secret da Autra.
Você sabe gerar Bearer JWT via POST /v1/oauth/token.
Você tem o CPF/CNPJ do pagador (necessário para inicializar a sessão).
(Opcional, recomendado) Você tem endpoint para receber webhooks da Autra.
(Opcional) Frontend tem biblioteca para renderizar QR Code (ex.: qrcode.js).

Resumo dos endpoints

#	O que faz	Endpoint	Quando usar
1	Iniciar sessão	`POST /v1/acquiring/pix/initialize`	Sempre antes de gerar Pix — retorna `transactionalToken`
2	Criar Pix	`POST /v1/acquiring/pix/checkout`	Gera o QR Code + payload copia-e-cola

Prefixo: https://api.autra.io. Headers: Authorization: Bearer <JWT>, Content-Type: application/json.

State machine

PENDING        (QR gerado, aguardando pagamento)
  │
  ├─► AUTHORIZED      (pagador pagou no app do banco)
  │     │
  │     └─► SETTLED   (liquidado — dinheiro disponível)
  │
  └─► EXPIRED         (não foi pago até expiresAt)

Estados terminais: SETTLED, EXPIRED.

🟦 Caminho feliz — passo a passo

Passo 1: Inicializar a sessão

POST /v1/acquiring/pix/initialize
Authorization: Bearer <JWT>
Content-Type: application/json

{ "documentId": "12345678901" }

documentId é o CPF ou CNPJ do pagador (somente números).

Resposta 200:

{ "transactionalToken": "eyJhbGciOi..." }

✅ Guarde o transactionalToken — ele é válido por poucos minutos. Não cacheie por muito tempo.

⚠️ Se demorar entre o passo 1 e o passo 2, o token expira e você precisa começar de novo.

Passo 2: Criar o Pix (gera QR Code)

POST /v1/acquiring/pix/checkout
Authorization: Bearer <JWT>

{
  "transactionalToken": "eyJhbGciOi...",
  "amount":             99.90,
  "currency":           "BRL",
  "description":        "Pedido #1234",
  "orderId":            "pedido-abc-123"
}

Resposta 200:

{
  "pixId":     "550e8400-e29b-41d4-a716-446655440000",
  "status":    "PENDING",
  "qrCode":    "00020126580014BR.GOV.BCB.PIX0136...",
  "amount":    99.90,
  "expiresAt": "2026-05-01T18:30:00Z"
}

✅ Use o qrCode das duas formas:

QR Code visual — passe o payload por uma lib (ex.: qrcode.js) e renderize a imagem.
Copia-e-cola — exiba o texto com botão "Copiar" para o cliente colar no app do banco.

⚠️ Guarde o pixId — é como você correlaciona webhooks com este pagamento.

⚠️ Atente ao expiresAt — após esse momento, o QR vira EXPIRED e não pode ser pago.

Campos importantes

Campo	Obrigatório	Detalhe
`transactionalToken`	sim	Do passo 1.
`amount`	sim	Em BRL, ex.: `99.90`. Maior que zero.
`currency`	sim	Use `BRL`.
`description`	não	Aparece no app do banco do pagador. Útil pra ele saber do que se trata.
`orderId`	não	Recomendado — seu ID interno do pedido. Volta nos webhooks pra correlação.

Passo 3: Pagador paga (não é uma chamada de API)

O cliente abre o app do banco dele, escaneia o QR (ou cola o copia-e-cola), confirma o valor e paga.

Você não chama nada aqui — só espera.

Passo 4: Receber confirmação

Há três formas de saber que o Pix foi pago:

A) Webhook `FINANCIAL_TRANSACTION` (recomendado em produção)

A Dock dispara um webhook para a Autra, que processa e atualiza o status para AUTHORIZED. Se você assina os webhooks da Autra, recebe o evento em segundos.

{
  "event_type": "FINANCIAL_TRANSACTION",
  "payload": {
    "productType": "PIX",
    "status":      "AUTHORIZED",
    "pixId":       "550e8400-...-446655440000",
    "amount":      99.90,
    "orderId":     "pedido-abc-123",
    ...
  }
}

✅ Esta é a forma mais rápida e barata.

B) Webhook `PAYOUT` (liquidação)

Algum tempo depois (segundos a poucos minutos), o Pix é liquidado — o dinheiro fica disponível na sua conta. A Autra dispara PAYOUT com status: SETTLED.

{
  "event_type": "PAYOUT",
  "payload": {
    "productType": "PIX",
    "status":      "SETTLED",
    "pixId":       "550e8400-...-446655440000",
    ...
  }
}

✅ SETTLED é quando você pode liberar o produto/serviço. Para a maioria dos casos AUTHORIZED já é seguro (o dinheiro está garantido), mas conservadores devem aguardar SETTLED.

C) Polling (fallback, não recomendado)

Se você não consome webhooks, pode pollar via outras rotas — mas não recomendamos para Pix avulso (não há endpoint público de status para Pix Checkout). Use webhooks.

Como exibir o QR Code

Frontend web — QR visual + copia-e-cola

<div id="qr-image"></div>
<input type="text" id="qr-text" readonly value="00020126580014..." />
<button onclick="copy()">Copiar código Pix</button>

<script src="https://cdn.jsdelivr.net/npm/qrcode/build/qrcode.min.js"></script>
<script>
  QRCode.toCanvas(
    document.getElementById('qr-image'),
    '00020126580014BR.GOV.BCB.PIX0136...',  // o qrCode da resposta
    { width: 256 }
  );

  function copy() {
    navigator.clipboard.writeText(document.getElementById('qr-text').value);
  }
</script>

Frontend mobile

A maioria das libs nativas (Flutter, React Native, iOS, Android) tem componente de QR. Use o qrCode do passo 2 como input.

Idempotência — `orderId`

Recomendamos sempre mandar orderId único:

Permite correlacionar o webhook ao pedido no seu sistema.
Ajuda no suporte (cliente reclamou que pagou? Busque pelo orderId).
Não é tecnicamente uma chave de idempotência (a API não bloqueia 2 Pix com mesmo orderId hoje), mas é a referência cruzada que você vai querer ter.

⚠️ Não cobre o cliente 2x: se o front demorar e o usuário clicar 2x no botão "Pagar", você pode acabar gerando 2 QRs. Trate isso no front (debounce, lock state).

Erros comuns

HTTP	Causa	Solução
`400`	Campo obrigatório faltando	Cheque `transactionalToken`, `amount`, `currency`.
`401`	JWT expirado	Renovar via `/oauth/token`.
`403`	IP não autorizado ou token inválido	Confirme allowlist de IP com suporte.
`403` (no `/checkout`)	`transactionalToken` expirou entre os passos 1 e 2	Refazer o `/initialize`.

Boas práticas

Sempre mande orderId — facilita correlação e suporte.
Cache JWT por 3600s, não regenere a cada Pix.
Não cacheie o transactionalToken — gere um por venda.
Use webhooks em produção. Polling não é viável para Pix Checkout.
Mostre expiresAt ao cliente — "Pague em até X minutos" reduz dúvidas.
Bloqueie duplo-clique no botão "Pagar" no front — evita gerar 2 QRs.
Trate AUTHORIZED como pago na maioria dos casos (o valor está garantido). Só aguarde SETTLED se for fluxo crítico.
Logs: o qrCode não é sensível, mas evite logar JWT/token.

Limitações conhecidas

Sem endpoint público de status — você depende de webhooks para confirmar pagamento. Se webhooks falharem, abra suporte.
Sem cancelamento — Pix Checkout não tem rota de void. Para "cancelar", basta deixar expirar (expiresAt).
Sem split nativo — para split em Pix, use Payment Links (que aceita Pix com split configurável).
Sem parcelamento — Pix é à vista. Para parcelar, use Acquiring (cartão).

FAQ

Quanto tempo o QR fica válido? Vem em expiresAt na resposta. Padrão atual: alguns minutos. Após isso, status vira EXPIRED automaticamente.

Posso reutilizar o mesmo QR em vários clientes? Não. Cada Pix Checkout é one-time. Para múltiplos pagamentos, gere um QR por cliente.

E se o cliente pagar depois do expiresAt? O banco do pagador rejeita a operação — o pagamento não acontece. Crie um novo Pix.

Posso fazer split com Pix Checkout? Não diretamente. Para Pix com split, use a categoria Payment Links (que internamente cria o Pix com split).

Recebo dinheiro na conta antes ou depois do SETTLED? SETTLED é o sinal de que liquidou. Antes disso (AUTHORIZED), o crédito está garantido mas ainda não compensado.

Pix avulso vs Pix Automático — qual usar?

Pix Checkout (esta categoria) — cobrança única, cliente paga no momento.
Pix Automático — débito recorrente, cliente autoriza uma vez e o sistema cobra automaticamente nos vencimentos seguintes.

Posso devolver/estornar um Pix? Não há rota de estorno na Autra hoje. Para devolver, faça uma transferência Pix manual de volta para o pagador (operação separada via Banking).

Qual a diferença para o Pix dos Payment Links?

Pix Checkout — você gera o QR e exibe no seu próprio frontend.
Payment Links — você gera um link/URL hospedado pela Autra que aceita Pix (e cartão e boleto). Use Payment Links se quer página de checkout pronta sem desenvolver UI.