Skip to navigation

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:

FieldRequiredRule
frequencyyesweekly, monthly, quarterly, semiannual or annual.
firstPaymentDateyesYYYY-MM-DD.
lastPaymentDatenoWithout it the recurrence has no end. Cannot be before firstPaymentDate.
valueone of the twoFixed amount of every charge.
maximumValueone of the twoCeiling for variable-amount charges. Sending both returns 422 automatic_pix_value_mismatch.
paymentRetrynotrue allows retries after a failed settlement.
contract.numberyesContract number the payer sees.
contract.descriptionnoText shown to the payer.
debtorno (yes on composite QRs)taxNumber and name of whom the charge refers to, when it is not the payer.

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

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": "Monthly plan" },
"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 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.

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": "First installment",
"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 is your UUID, unique per account. A value that is not a UUID returns 400 invalid_field; repeating it returns 409 automatic_pix_identifier_in_use.
  • requestExpiration is required: deadline of the recurrence offer, after today and up to 30 days ahead. Without an offset, Brasília time applies.
  • recurrence.debtor (taxNumber and name) is required on composite QRs.
  • pixKey is a key of the account itself.
  • value is the amount of this first charge. The terms of the next ones go in recurrence.
  • On the due-date route, dueDate is required. daysAfterDueDate, deduction, discount, interest and penalty are optional. The static route 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

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

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.