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 da transação, retornado na criação do Pix e também nos webhooks (`operationData.pixId`).
`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 estabelecimento (merchant) cadastrado no tenant (usado no documentId do initialize e do checkout).
(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": "12345678000190" }

documentId é o CPF ou CNPJ do estabelecimento (merchant) cadastrado no seu tenant — somente números. Não é o documento do pagador.

Resposta 200:

{ "code": "ACCEPTED", "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...",
  "documentId":         "12345678000190",
  "amount":             99.90,
  "currency":           "BRL",
  "description":        "Pedido #1234",
  "orderId":            "pedido-abc-123"
}

Resposta 200:

{
  "pixId":     "cdb445694be7486e830f720658f9a1a1",
  "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 orderId (o seu ID de pedido) — ele volta em operationData.orderId nos webhooks, então é a chave mais simples pra ligar o pagamento ao seu pedido (veja o Passo 4).

⚠️ 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.
`documentId`	sim	CPF/CNPJ do estabelecimento (merchant), só dígitos — o mesmo do initialize.
`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 `acquiring.financial_transaction` (recomendado em produção)

Quando o pagamento é confirmado, a Autra dispara um webhook e o status vai para AUTHORIZED. Se você assina os webhooks da Autra, recebe o evento em segundos.

{
  "eventId":    "a58720d1-0a70-4012-b718-936e521f81b8",
  "eventType":  "acquiring.financial_transaction",
  "occurredAt": "2026-07-27T22:18:42Z",
  "status":     "AUTHORIZED",
  "operationData": {
    "subject":     "FINANCIAL_TRANSACTION",
    "productType": "PIX",
    "orderId":     "pedido-abc-123",
    "pixId":       "cdb445694be7486e830f720658f9a1a1",
    "payload": {
      "slug":              "A13CA0...",
      "muid":              "1a0b5369...",
      "transactionStatus": "AUTHORIZED",
      "totalAmount":       10,
      "currency":          "BRL"
    }
  }
}

Correlação: o orderId que você enviou no create volta em operationData.orderId — essa é a forma mais simples de ligar o evento ao seu pedido. Também vem o pixId (o mesmo devolvido na criação) e, em payload, o slug (identificador da transação, usado no vínculo com a liquidação).

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

B) Webhook `acquiring.payout` (liquidação)

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

{
  "eventId":    "41f4ffd2-285b-40c3-aec8-655800e00676",
  "eventType":  "acquiring.payout",
  "occurredAt": "2026-07-27T22:18:43Z",
  "operationData": {
    "subject":     "PAYOUT",
    "productType": "PIX",
    "orderId":     "pedido-abc-123",
    "pixId":       "cdb445694be7486e830f720658f9a1a1",
    "payload": {
      "payoutId":               "A13CA0...",
      "status":                 "SETTLED",
      "amount":                 10,
      "expectedSettlementDate": "2026-07-27"
    }
  }
}

🔑 Correlação: o orderId volta também aqui, em operationData.orderId — use-o pra ligar a liquidação ao seu pedido. Como alternativa, o payoutId (em payload) é igual ao slug do acquiring.financial_transaction, então você também pode casar slug → payoutId se preferir.

✅ 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`, `documentId`, `amount`, `currency`.
`404`	Estabelecimento não encontrado para este tenant	Confirme que o `documentId` é um merchant cadastrado no seu tenant.
`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.