Recorrências e QR composto
Pré-requisitos em Pix Automático — visão geral: feature automatic_pix ligada e escopo pix.automatic.
Termos da recorrência
Os três caminhos de criação usam os mesmos termos:
O arranjo bloqueia o mesmo contrato por 24 horas, um pedido pendente para o mesmo contrato e pagador e uma proposta idêntica recusada ou cancelada há menos de 30 dias. Nesses casos a resposta é 409 automatic_pix_contract_blocked.
Pedido de autorização
payer.ispb, payer.taxNumber, payer.branch, payer.account e payer.ibgeCode (código IBGE do município do pagador, 7 dígitos) são obrigatórios; faltando um, a resposta é 400 missing_field, e ibgeCode fora do formato responde 400 invalid_field. requestExpiration é opcional: depois de hoje e até 30 dias, no fuso de Brasília; sem ele, o liquidante usa 30 dias. ISPB inexistente ou fora do Pix Automático responde 422 automatic_pix_payer_bank_unavailable. A conta recebedora precisa ser PJ ativa; caso contrário, 422 automatic_pix_receiver_ineligible.
A resposta é 201 com a recorrência em awaiting_authorization. Guarde o recurrenceId. A decisão do pagador chega por webhook: pix.automatic.recurrence.authorized, .rejected, .expired ou .failed.
QR composto
Um QR que cobra agora e, ao ser pago, leva o pagador a autorizar a recorrência.
identifieré um UUID seu, único por conta. Fora do formato UUID, a resposta é 400invalid_field; repetir responde 409automatic_pix_identifier_in_use.requestExpirationé obrigatório: validade da oferta de recorrência, depois de hoje e até 30 dias. Sem offset, vale o fuso de Brasília.recurrence.debtor(taxNumberename) é obrigatório no QR composto.pixKeyé uma chave da própria conta.valueé o valor desta primeira cobrança. Os termos das próximas ficam emrecurrence.- Na rota
due-date,dueDateé obrigatório.daysAfterDueDate,deduction,discount,interestepenaltysão opcionais. Na rotastaticesses campos são ignorados.
A resposta 201 traz pixCopyPaste, image (PNG em base64), qrCodeId e o recurrenceId. Quando o pagador paga, saem pix.in.completed (o crédito) e pix.automatic.qrcode.paid (o vínculo com a recorrência). Depois vem o resultado da autorização em pix.automatic.recurrence.*.
Listar e consultar
As duas leituras são ao vivo no liquidante. A lista filtra por startDate, endDate (exclusivo), status, journey, frequency, payerTaxNumber e debtorTaxNumber. Sem período, vale os últimos 30 dias no fuso de Brasília. A paginação usa page (a partir de 1) e pageSize (até 100), e a resposta traz items, totalItems, totalPages e hasNext.
A consulta individual traz history com cada mudança de status e, depois da autorização, payerMaximumValue: o teto que o pagador escolheu. Recorrência de outra conta responde 404.