Pular para o conteúdo principal

Pix Automático: recorrência com mandato

Resposta rápida: Pix Automático é cobrança recorrente autorizada uma vez pelo pagador no próprio banco: você cria uma recorrência (rec), o pagador autoriza, e a partir daí cada ciclo é uma cobrança recorrente (cobr) que o banco dele debita sem nova interação.

O que muda em relação à cobrança imediata​

Cobrança imediata (cob)Pix Automático (rec + cobr)
Quem age em cada pagamentoO pagador, sempreNinguém: o banco do pagador debita
AutorizaçãoImplícita no pagamentoMandato aprovado uma vez, no app do banco do pagador
Objeto principaltxididRec (recorrência) e, por ciclo, um cobr com txid
CancelamentoNão se aplicaSó o pagador cancela, no banco dele
RecebedorChave PixConta do recebedor amarrada à recorrência

A consequência de projeto mais importante: o mandato pertence à conta recebedora daquela recorrência. Trocar de conta depois obriga cada pagador a autorizar de novo — a decisão de qual conta recebe vem antes do primeiro assinante, não depois.

As três peças​

  1. rec — a recorrência. O mandato: periodicidade, data inicial e final, valor de referência, vínculo (contrato, devedor, objeto) e política de retentativa. Nasce CRIADA e só serve para cobrar quando vira APROVADA.
  2. solicrec — a solicitação de confirmação. Pede ao PSP do pagador que apresente a autorização a ele, identificando destinatário por agência, conta, CPF/CNPJ e ISPB do participante.
  3. cobr — a cobrança recorrente. Um por ciclo, com idRec, data de vencimento e valor. É o que efetivamente vira dinheiro.

Jornadas de autorização​

A especificação nomeia quatro jornadas, e a diferença entre elas é de onde sai o BR Code que o pagador autoriza:

JornadaComo o pagador chega à autorizaçãoQR composto
1A autorização pega carona numa cobrança que ele já vai pagar — a rec aponta ativacao.dadosJornada.txid pra essa cob/cobvnão tem QR próprio
2A recorrência tem payload próprio, com location criada em /locrec{ jornada: "JORNADA_2", pixCopiaECola }
3Recorrência mais uma cobrança imediata, num QR só{ jornada: "JORNADA_3", ... }
4Recorrência mais uma cobrança com vencimento{ jornada: "JORNADA_4", ... }

O enum de dadosQR.jornada tem exatamente três valores — JORNADA_2, JORNADA_3 e JORNADA_4. A Jornada 1 não aparece nele porque não há QR pra compor: a autorização viaja na cobrança existente.

O QR vem da leitura, não da criação​

POST /rec devolve o idRec e nada pra mostrar. O BR Code aparece no GET /rec/{idRec}, e o que você pede determina a jornada:

RequisiçãoRetorno
GET /rec/{idRec}QR composto só da recorrência (Jornada 2)
GET /rec/{idRec}?txid={txid de cob}QR da cobrança imediata + recorrência (Jornada 3)
GET /rec/{idRec}?txid={txid de cobv}QR da cobrança com vencimento + recorrência (Jornada 4)

dadosQR.jornada e dadosQR.pixCopiaECola só vêm quando as location necessárias estão preenchidas — na recorrência para a Jornada 2, e também na cobrança para as jornadas 3 e 4. Fluxo que espera BR Code de volta da criação fica sem nada pra pôr na tela.

Qual delas usar é decisão de produto: a 1 aproveita um pagamento que já existe, a 2 não depende de nenhum.

Periodicidade e retentativa​

periodicidade aceita SEMANAL, MENSAL, TRIMESTRAL, SEMESTRAL e ANUAL.

politicaRetentativa tem dois valores, e a escolha é de negócio, não técnica:

ValorEfeito
NAO_PERMITEFalhou o ciclo, não há nova tentativa
PERMITE_3R_7DAté três novas tentativas em sete dias

Assinatura com público de renda variável tende a se beneficiar da retentativa; cobrança de valor alto, nem sempre.

O que não muda​

Autenticação, mTLS e disciplina de webhook são as mesmas da cobrança imediata: mesmo host, mesmo fluxo de token, mesma exigência de CA. Pix Automático não é outra API — é outro conjunto de recursos na mesma.

Usado em​