Skip to navigation

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:

CampoObrigatórioRegra
frequencysimweekly, monthly, quarterly, semiannual ou annual.
firstPaymentDatesimYYYY-MM-DD.
lastPaymentDatenãoSem ele, a recorrência não tem fim. Não pode ser antes de firstPaymentDate.
valueum dos doisValor fixo de toda cobrança.
maximumValueum dos doisTeto para cobranças de valor variável. Enviar os dois responde 422 automatic_pix_value_mismatch.
paymentRetrynãotrue permite retentativa depois de uma liquidação que falhou.
contract.numbersimNúmero do contrato que o pagador vê.
contract.descriptionnãoTexto exibido ao pagador.
debtornão (sim no QR composto)taxNumber e name de quem a cobrança se refere, quando não é o pagador.

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

POST /v1/accounts/{accountId}/pix/automatic/recurrences
{
"frequency": "monthly",
"firstPaymentDate": "2026-11-25",
"lastPaymentDate": "2027-10-25",
"value": 149.9,
"paymentRetry": true,
"contract": { "number": "CONTRATO-1001", "description": "Plano mensal" },
"payer": {
"ispb": "99999004",
"taxNumber": "12345678909",
"branch": "0001",
"account": "123456",
"ibgeCode": "3550308",
"name": "MARIA DA SILVA"
},
"requestExpiration": "2026-11-10T23:59:59-03:00"
}

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.

POST /v1/accounts/{accountId}/pix/automatic/composite-qr-codes/static
POST /v1/accounts/{accountId}/pix/automatic/composite-qr-codes/due-date
{
"identifier": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"pixKey": "3f1c0b6e-9a2d-4c71-8e55-1b7a0d4c9e21",
"value": 49.9,
"message": "Primeira mensalidade",
"requestExpiration": "2026-11-20T23:59:59-03:00",
"recurrence": {
"frequency": "monthly",
"firstPaymentDate": "2026-12-25",
"maximumValue": 200,
"contract": { "number": "CONTRATO-1001" },
"debtor": { "taxNumber": "12345678909", "name": "MARIA DA SILVA" }
}
}
  • identifier é um UUID seu, único por conta. Fora do formato UUID, a resposta é 400 invalid_field; repetir responde 409 automatic_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 (taxNumber e name) é 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 em recurrence.
  • Na rota due-date, dueDate é obrigatório. daysAfterDueDate, deduction, discount, interest e penalty são opcionais. Na rota static esses 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

GET /v1/accounts/{accountId}/pix/automatic/recurrences
GET /v1/accounts/{accountId}/pix/automatic/recurrences/{recurrenceId}

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.