Recurrences and composite QR
Prerequisites in Pix Automático — overview: the automatic_pix feature enabled and the pix.automatic scope.
Recurrence terms
The three creation paths share the same terms:
The scheme blocks the same contract for 24 hours, a pending request for the same contract and payer, and an identical proposal rejected or canceled less than 30 days ago. In those cases the response is 409 automatic_pix_contract_blocked.
Authorization request
payer.ispb, payer.taxNumber, payer.branch, payer.account and payer.ibgeCode (7-digit IBGE code of the payer’s city) are required; a missing one returns 400 missing_field, and a malformed ibgeCode returns 400 invalid_field. requestExpiration is optional: after today and up to 30 days ahead, in Brasília time; without it, the settlement bank uses 30 days. An ISPB that does not exist or is not in Pix Automático returns 422 automatic_pix_payer_bank_unavailable. The receiving account must be an active legal entity; otherwise 422 automatic_pix_receiver_ineligible.
The response is 201 with the recurrence in awaiting_authorization. Keep the recurrenceId. The payer’s decision arrives by webhook: pix.automatic.recurrence.authorized, .rejected, .expired or .failed.
Composite QR
One QR that charges now and, once paid, takes the payer to authorize the recurrence.
identifieris your UUID, unique per account. A value that is not a UUID returns 400invalid_field; repeating it returns 409automatic_pix_identifier_in_use.requestExpirationis required: deadline of the recurrence offer, after today and up to 30 days ahead. Without an offset, Brasília time applies.recurrence.debtor(taxNumberandname) is required on composite QRs.pixKeyis a key of the account itself.valueis the amount of this first charge. The terms of the next ones go inrecurrence.- On the
due-dateroute,dueDateis required.daysAfterDueDate,deduction,discount,interestandpenaltyare optional. Thestaticroute ignores those fields.
The 201 response carries pixCopyPaste, image (base64 PNG), qrCodeId and the recurrenceId. When the payer pays, pix.in.completed (the credit) and pix.automatic.qrcode.paid (the link to the recurrence) are sent. Then the authorization result arrives as pix.automatic.recurrence.*.
List and get
Both reads are live at the settlement bank. The list filters by startDate, endDate (exclusive), status, journey, frequency, payerTaxNumber and debtorTaxNumber. Without a period, the last 30 days in the Brasília time zone apply. Pagination uses page (from 1) and pageSize (up to 100), and the response carries items, totalItems, totalPages and hasNext.
The single read carries history with every status change and, after authorization, payerMaximumValue: the ceiling the payer chose. A recurrence of another account returns 404.