Skip to navigation

Pix Automático — visão geral

O Pix Automático é a cobrança recorrente do arranjo Pix. O pagador autoriza uma vez no app do banco dele, e a sua conta agenda cada cobrança sem nova confirmação. A conta CorpX é sempre a recebedora.

A feature automatic_pix nasce desligada para todos os tenants. Enquanto estiver off, toda rota em /v1/accounts/{accountId}/pix/automatic responde 403 feature_disabled. A CorpX liga a feature pelo painel administrativo depois do contrato. Desligar depois não cancela recorrência já autorizada.

Escopo da credencial: pix.automatic. As leituras também aceitam read. No painel, ver exige pix_automatic.view e emitir ou adiar exige pix_automatic.manage.

Como começa uma recorrência

CaminhoRotaQuando usar
Pedido de autorizaçãoPOST /pix/automatic/recurrencesVocê já tem banco, agência e conta do pagador. O pedido chega ao app do banco dele.
QR composto imediatoPOST /pix/automatic/composite-qr-codes/staticO pagador paga a primeira cobrança agora e, no mesmo QR, autoriza as próximas.
QR composto com vencimentoPOST /pix/automatic/composite-qr-codes/due-dateIgual ao anterior, com vencimento, juros, multa, desconto e abatimento.

Detalhes em Recorrências e QR composto.

Ciclo de vida

recorrência awaiting_authorization ──► authorized ──► (agendamentos)
│ │
├──► rejected └──► canceled
├──► expired
└──► request_failed / authorization_failed
agendamento created ──► confirmed ──► settled
│ │
│ └──► liquidação falhou ──► retentativa (até 3 datas)
└──► rejected / confirmation_failed / expired

Cada mudança relevante gera um webhook pix.automatic.* e um evento pix_automatic.* na timeline, ancorado no recurrenceId.

WebhookQuando
pix.automatic.recurrence.authorizedO pagador autorizou. A partir daqui você agenda.
pix.automatic.recurrence.rejectedO pagador ou o banco dele recusou.
pix.automatic.recurrence.expiredO pedido expirou sem resposta, ou a recorrência foi cancelada.
pix.automatic.recurrence.failedO pedido falhou antes de chegar ao pagador.
pix.automatic.scheduling.confirmedO banco do pagador confirmou a cobrança agendada.
pix.automatic.scheduling.rejectedO banco do pagador recusou a cobrança.
pix.automatic.scheduling.failedA cobrança não foi confirmada a tempo.
pix.automatic.settlement.completedO dinheiro entrou na conta. Também sai pix.in.completed.
pix.automatic.settlement.failedO dinheiro não entrou. Dá para pedir retentativa.
pix.automatic.qrcode.paidO QR composto foi pago. Também sai pix.in.completed.

Payloads em Webhooks.

Dois identificadores

  • recurrenceId é o UUID que a API devolve na criação. É o id da recorrência nesta API, no webhook e na timeline.
  • recurrenceIdentifier (RR… ou RN…) é o id do arranjo Pix. Aparece quando o arranjo atribui e é o que o pagador vê no banco dele.

Toda rota com {recurrenceId} aceita os dois. O RR…/RN… só é reconhecido depois que a recorrência passou por esta API ou por um webhook da conta.

Próximos passos

  1. Recorrências e QR composto: criar, listar e consultar.
  2. Agendamentos e retentativas: cobrar, adiar e tentar de novo.