Create a recurring series
Registers a RULE — weekly or monthly, with exactly one termination criterion — plus the payment template every occurrence is stamped from, and materializes the first window of occurrences in the same transaction. Use it when the payer is committing to a standing payment rather than to one order; a single future payment is the scheduled-payments route. The payee is resolved once, at creation: send payeeKey with initiationType DICT or destination with MANUAL, never both — a body carrying the other type’s block is refused rather than resolved from one of them: a well-formed block with 422 PIX-0751; one with a missing field by request validation first (400 PIX-0002), and one with an invalid field likewise (400 PIX-0003). QR_CODE is refused on this route (PIX-0751). Supply exactly one of paymentCount, endDate and indefinite: sending none is refused (PIX-0761) rather than read as open-ended, and sending two is refused (PIX-0762) rather than reconciled. No ceiling is placed on the number of payments — REG-Art.37-A forbids limiting the quantity of a user’s transactions. THE MONTHLY CALENDAR RULE (IN BCB 513/2024 art. 13): the reference day is derived from firstPaymentDate and PRESERVED across occurrences, and when a month has no such day — 29, 30 or 31 — that occurrence moves to the FIRST DAY OF THE FOLLOWING MONTH, after which the reference day returns. A series on day 31 therefore pays on 1 March AND on 31 March: two occurrences in the same month. Shifting off a non-business day is a different matter and does not happen — Pix settles every day, so a non-business date is executed as it stands. The response carries the occurrences created now, not the whole series: an indefinite series has no finite set of rows, and materializedThrough states how far the window currently reaches. The available balance is NOT touched, here or by the occurrences (REG-Art.9 caput): nothing moves until each scheduled date.
Autorizações
JWT bearer token issued by the identity provider.
Cabeçalhos
REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Within one hour of the first 2xx answer, replaying the same key with a divergent method, URL or body is PIX-0031 @ 412.
1 - 64Corpo
Payer account UUID. The payer travels in the body rather than in a header because a series is written once and read for months afterwards, so it belongs to the record rather than to the transport.
"0195948b-bf02-7e4f-9a1b-2c3d4e5f6a7b"
Amount of EVERY occurrence, in BRL with two decimals. The available balance is NOT touched at creation, nor by the occurrences this call materializes.
"150.00"
How the destination is resolved, once, at creation. DICT reads the directory and requires payeeKey; MANUAL requires destination. The two blocks are mutually exclusive: a DICT body that also carries destination, or a MANUAL body that also carries payeeKey, is refused rather than resolved from one of them. A well-formed block of another type is refused with 422 PIX-0751; one with a missing field fails request validation first (400 PIX-0002), and one with an invalid field likewise (400 PIX-0003). The key is stored with the series because REG-Art.9 section 5 makes the directory re-lookup mandatory before EVERY occurrence settles. QR_CODE is REFUSED on this route with PIX-0751: a BR Code names one collection, and a series reusing it would pay that same collection every period. Use the single scheduled-payments route for a BR Code.
MANUAL, DICT, QR_CODE "DICT"
The rule that describes the series.
Always BRL. Present for forward compatibility only.
BRL "BRL"
Free-text memo carried by every occurrence, at most 140 characters -- the RmtInf ceiling. Stored and returned VERBATIM.
140"Aluguel"
The payee's account and owner. Required when initiationType is MANUAL; refused on DICT (422 PIX-0751; first 400 PIX-0002 if a field of it is missing, 400 PIX-0003 if one is invalid).
Caller-owned annotation, stored and returned verbatim. This service never reads a key nor derives behaviour from a value. Absent and empty are distinct: absent stays null on read.
The Pix key to resolve. Required when initiationType is DICT; refused on MANUAL (422 PIX-0751; first 400 PIX-0002 if a field of it is missing, 400 PIX-0003 if one is invalid).
Only IPAY can be scheduled. Pix Saque (OTHR) and Pix Troco (GSCB) are point-in-time operations and REG-Art.11-P prohibits scheduling them.
IPAY "IPAY"
Resposta
Idempotent replay: the same X-Idempotency key was sent with the same request within one hour of the first 2xx answer, so the original creation's response is returned unchanged. The series was NOT created a second time.
Payer account.
"0195948b-bf02-7e4f-9a1b-2c3d4e5f6a7b"
Amount of every occurrence, in BRL.
"150.00"
Always BRL.
"BRL"
The payee as photographed at creation. On a DICT series it is compared, before EVERY occurrence settles, against a fresh directory answer (REG-Art.9 section 6), which is why it is stored rather than re-resolved; the occurrences of a MANUAL series are sent to it as photographed, with no second lookup.
Series identifier.
"01a0d8fb-1a8b-7a10-b3c4-d5e6f7a8b9c0"
How the destination was resolved at creation.
MANUAL, DICT, QR_CODE "DICT"
Civil date of the series' final payment, when it has one. Null on an indefinite series, where reporting one would be a fabrication.
"2028-07-10"
Civil date up to which occurrences exist -- the edge of the materialized window. Occurrences beyond it do not exist yet. Null on a series that has never been materialized.
"2027-10-10"
The currently materialized occurrences, oldest first -- NOT necessarily the whole series. materializedThrough states how far the window reaches, and a long-running series is enumerated in full through GET /v1/scheduled-payments?recurrence_id=. Empty and never null.
Always IPAY: REG-Art.11-P prohibits scheduling any other purpose.
IPAY "IPAY"
The rule the occurrences are computed from.
The payer as photographed at creation.
Situation of the SERIES, not of any one occurrence: a cancelled series still has settled occurrences behind it, and each occurrence carries its own status.
ACTIVE, COMPLETED, CANCELLED "ACTIVE"
The payer's memo, carried by every occurrence and returned exactly as stored.
"Aluguel"
The annotation the caller sent at creation, returned verbatim. Absent when none was sent -- this service never invents one.
The directory key a DICT-initiated series resolved at creation. It is kept because the mandatory re-lookup needs the key that was used, and a key is not one of the payee's attributes -- it cannot be reconstructed from the photograph above.