> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /pt/openapi/v3-current/pix-lerian-spi.yaml post /scheduled-payment-recurrences openapi: 3.1.0 info: contact: name: Lerian Studio url: https://lerian.studio description: Public API for outbound Pix transfers, refunds, and scheduled payments. license: name: Lerian Studio General License title: Pix Lerian — Payments version: 1.1.0 servers: - url: https://api.example.com/spi/v1 description: >- Replace the example host with the URL provided during environment onboarding. security: - BearerAuth: [] tags: - description: Create, list, and retrieve Pix refunds. name: Refunds - name: Scheduled Payments description: Register, list, retrieve, and cancel scheduled Pix payments. - description: Initiate, process, list, and retrieve outbound Pix transfers. name: Transfers - description: >- Register, list, retrieve, and cancel recurring series of scheduled Pix payments. name: Scheduled Payment Recurrences paths: /scheduled-payment-recurrences: post: tags: - Scheduled Payment Recurrences summary: Create a recurring series description: >- 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. operationId: createScheduledPaymentRecurrence parameters: - description: >- 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. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string requestBody: content: application/json: examples: dict: description: >- Pix Lerian resolves the payee from the directory at creation and again before every occurrence settles. Send payeeKey only: a destination alongside it is refused -- 422 PIX-0751 when well formed, 400 PIX-0002 when a field of it is missing, 400 PIX-0003 when one is invalid. summary: DICT -- monthly rent to a Pix key, twelve payments value: accountId: 0195948b-bf02-7e4f-9a1b-2c3d4e5f6a7b amount: '150.00' currency: BRL initiationType: DICT purpose: IPAY payeeKey: keyType: EMAIL keyValue: joao.pereira@example.com description: Aluguel metadata: contractRef: A-4471 recurrence: periodicity: MONTHLY firstPaymentDate: '2027-08-10' paymentCount: 12 manual: description: >- The caller supplies the payee's account and owner, and the person type is derived from the document. Send destination only: a payeeKey alongside it is refused -- 422 PIX-0751 when well formed, 400 PIX-0002 when a field of it is missing, 400 PIX-0003 when one is invalid. summary: MANUAL -- weekly payment to bank details, until an end date value: accountId: 0195948b-bf02-7e4f-9a1b-2c3d4e5f6a7b amount: '80.00' currency: BRL initiationType: MANUAL purpose: IPAY destination: account: branch: '0001' number: '98765' participant: '18236120' type: CACC owner: document: '12345678000195' name: Escola Exemplo LTDA description: Aulas semanais recurrence: periodicity: WEEKLY firstPaymentDate: '2027-08-02' endDate: '2027-10-25' schema: $ref: '#/components/schemas/CreateRecurrenceBody' required: true responses: '200': content: application/json: example: id: 01a0d8fb-1a8b-7a10-b3c4-d5e6f7a8b9c0 accountId: 0195948b-bf02-7e4f-9a1b-2c3d4e5f6a7b amount: '150.00' currency: BRL status: ACTIVE initiationType: DICT purpose: IPAY description: Aluguel metadata: contractRef: A-4471 recurrence: periodicity: MONTHLY firstPaymentDate: '2027-08-10' paymentCount: 12 endDate: null indefinite: false referenceDayOfMonth: 10 source: branch: '0001' accountNumber: '1234567' accountType: CACC ispb: '60746948' personType: NATURAL_PERSON taxId: '12345678909' name: Ana Souza destination: branch: '0001' accountNumber: '7654321' accountType: CACC ispb: '18236120' personType: NATURAL_PERSON taxId: '98765432100' name: Joao Pereira payeeKey: keyType: EMAIL keyValue: joao.pereira@example.com materializedThrough: '2027-10-10' lastPaymentDate: '2028-07-10' createdAt: '2026-09-25T14:32:10.123456Z' updatedAt: '2026-09-25T14:32:10.123456Z' occurrences: - id: 01a0d8fb-1a8c-7b21-8c3d-4e5f6a7b8c91 accountId: 0195948b-bf02-7e4f-9a1b-2c3d4e5f6a7b scheduledDate: '2027-08-10' amount: '150.00' currency: BRL initiationType: DICT purpose: IPAY description: Aluguel source: branch: '0001' accountNumber: '1234567' accountType: CACC ispb: '60746948' personType: NATURAL_PERSON taxId: '12345678909' name: Ana Souza destination: branch: '0001' accountNumber: '7654321' accountType: CACC ispb: '18236120' personType: NATURAL_PERSON taxId: '98765432100' name: Joao Pereira status: PENDING firstWindowOpensAt: '2027-08-10T00:00:00-03:00' cancellationCutoff: '2027-08-09T23:59:59.999999-03:00' createdAt: '2026-09-25T14:32:10.123456Z' updatedAt: '2026-09-25T14:32:10.123456Z' attempts: [] - id: 01a0d8fb-1a8d-7b22-8c3d-4e5f6a7b8c92 accountId: 0195948b-bf02-7e4f-9a1b-2c3d4e5f6a7b scheduledDate: '2027-09-10' amount: '150.00' currency: BRL initiationType: DICT purpose: IPAY description: Aluguel source: branch: '0001' accountNumber: '1234567' accountType: CACC ispb: '60746948' personType: NATURAL_PERSON taxId: '12345678909' name: Ana Souza destination: branch: '0001' accountNumber: '7654321' accountType: CACC ispb: '18236120' personType: NATURAL_PERSON taxId: '98765432100' name: Joao Pereira status: PENDING firstWindowOpensAt: '2027-09-10T00:00:00-03:00' cancellationCutoff: '2027-09-09T23:59:59.999999-03:00' createdAt: '2026-09-25T14:32:10.123456Z' updatedAt: '2026-09-25T14:32:10.123456Z' attempts: [] - id: 01a0d8fb-1a8e-7b23-8c3d-4e5f6a7b8c93 accountId: 0195948b-bf02-7e4f-9a1b-2c3d4e5f6a7b scheduledDate: '2027-10-10' amount: '150.00' currency: BRL initiationType: DICT purpose: IPAY description: Aluguel source: branch: '0001' accountNumber: '1234567' accountType: CACC ispb: '60746948' personType: NATURAL_PERSON taxId: '12345678909' name: Ana Souza destination: branch: '0001' accountNumber: '7654321' accountType: CACC ispb: '18236120' personType: NATURAL_PERSON taxId: '98765432100' name: Joao Pereira status: PENDING firstWindowOpensAt: '2027-10-10T00:00:00-03:00' cancellationCutoff: '2027-10-09T23:59:59.999999-03:00' createdAt: '2026-09-25T14:32:10.123456Z' updatedAt: '2026-09-25T14:32:10.123456Z' attempts: [] schema: $ref: '#/components/schemas/RecurrenceDetailView' description: >- 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. '201': content: application/json: example: id: 01a0d8fb-1a8b-7a10-b3c4-d5e6f7a8b9c0 accountId: 0195948b-bf02-7e4f-9a1b-2c3d4e5f6a7b amount: '150.00' currency: BRL status: ACTIVE initiationType: DICT purpose: IPAY description: Aluguel metadata: contractRef: A-4471 recurrence: periodicity: MONTHLY firstPaymentDate: '2027-08-10' paymentCount: 12 endDate: null indefinite: false referenceDayOfMonth: 10 source: branch: '0001' accountNumber: '1234567' accountType: CACC ispb: '60746948' personType: NATURAL_PERSON taxId: '12345678909' name: Ana Souza destination: branch: '0001' accountNumber: '7654321' accountType: CACC ispb: '18236120' personType: NATURAL_PERSON taxId: '98765432100' name: Joao Pereira payeeKey: keyType: EMAIL keyValue: joao.pereira@example.com materializedThrough: '2027-10-10' lastPaymentDate: '2028-07-10' createdAt: '2026-09-25T14:32:10.123456Z' updatedAt: '2026-09-25T14:32:10.123456Z' occurrences: - id: 01a0d8fb-1a8c-7b21-8c3d-4e5f6a7b8c91 accountId: 0195948b-bf02-7e4f-9a1b-2c3d4e5f6a7b scheduledDate: '2027-08-10' amount: '150.00' currency: BRL initiationType: DICT purpose: IPAY description: Aluguel source: branch: '0001' accountNumber: '1234567' accountType: CACC ispb: '60746948' personType: NATURAL_PERSON taxId: '12345678909' name: Ana Souza destination: branch: '0001' accountNumber: '7654321' accountType: CACC ispb: '18236120' personType: NATURAL_PERSON taxId: '98765432100' name: Joao Pereira status: PENDING firstWindowOpensAt: '2027-08-10T00:00:00-03:00' cancellationCutoff: '2027-08-09T23:59:59.999999-03:00' createdAt: '2026-09-25T14:32:10.123456Z' updatedAt: '2026-09-25T14:32:10.123456Z' attempts: [] - id: 01a0d8fb-1a8d-7b22-8c3d-4e5f6a7b8c92 accountId: 0195948b-bf02-7e4f-9a1b-2c3d4e5f6a7b scheduledDate: '2027-09-10' amount: '150.00' currency: BRL initiationType: DICT purpose: IPAY description: Aluguel source: branch: '0001' accountNumber: '1234567' accountType: CACC ispb: '60746948' personType: NATURAL_PERSON taxId: '12345678909' name: Ana Souza destination: branch: '0001' accountNumber: '7654321' accountType: CACC ispb: '18236120' personType: NATURAL_PERSON taxId: '98765432100' name: Joao Pereira status: PENDING firstWindowOpensAt: '2027-09-10T00:00:00-03:00' cancellationCutoff: '2027-09-09T23:59:59.999999-03:00' createdAt: '2026-09-25T14:32:10.123456Z' updatedAt: '2026-09-25T14:32:10.123456Z' attempts: [] - id: 01a0d8fb-1a8e-7b23-8c3d-4e5f6a7b8c93 accountId: 0195948b-bf02-7e4f-9a1b-2c3d4e5f6a7b scheduledDate: '2027-10-10' amount: '150.00' currency: BRL initiationType: DICT purpose: IPAY description: Aluguel source: branch: '0001' accountNumber: '1234567' accountType: CACC ispb: '60746948' personType: NATURAL_PERSON taxId: '12345678909' name: Ana Souza destination: branch: '0001' accountNumber: '7654321' accountType: CACC ispb: '18236120' personType: NATURAL_PERSON taxId: '98765432100' name: Joao Pereira status: PENDING firstWindowOpensAt: '2027-10-10T00:00:00-03:00' cancellationCutoff: '2027-10-09T23:59:59.999999-03:00' createdAt: '2026-09-25T14:32:10.123456Z' updatedAt: '2026-09-25T14:32:10.123456Z' attempts: [] schema: $ref: '#/components/schemas/RecurrenceDetailView' description: Created '400': content: application/json: schema: $ref: '#/components/schemas/LegacyErrorEnvelope' examples: idempotencyGate: summary: Idempotency gate refusal value: code: PIX-0030 title: Idempotency Key Required message: >- The X-Idempotency header is required for this operation and must be within the accepted length. undecodableBody: summary: >- PIX-0010 -- the body is not decodable as this operation's JSON value: code: PIX-0010 title: Client Error message: >- The request could not be processed due to a client-side error. application/problem+json: examples: invalidFieldValues: summary: PIX-0003 -- a field fails its validation rule value: type: https://errors.lerian.studio/v1/PIX-0003 title: Bad Request status: 400 detail: >- Your request contains one or more fields with an invalid data type. errors: - message: periodicity must be one of [WEEKLY MONTHLY] location: recurrence.periodicity code: PIX-0003 missingFields: summary: PIX-0002 -- a required field is missing value: type: https://errors.lerian.studio/v1/PIX-0002 title: Bad Request status: 400 detail: Your request is missing one or more required fields. errors: - message: destination.account.number is a required field location: destination.account.number - message: destination.account.participant is a required field location: destination.account.participant - message: destination.account.type is a required field location: destination.account.type - message: destination.owner.document is a required field location: destination.owner.document - message: destination.owner.name is a required field location: destination.owner.name code: PIX-0002 schema: $ref: '#/components/schemas/Detail' description: >- Two shapes share this status, one per media type. application/problem+json is request validation, which refused the body before any rule of this operation was read, with errors[] naming each field: PIX-0002 a required field is missing -- what an incomplete payee block of either type answers; PIX-0003 a field fails its rule (enum, format, check digits, length) -- what a complete payee block with an invalid field answers. application/json is the legacy {code,title,message} envelope, for refusals that answer before validation runs: PIX-0010 the body is not decodable as this operation's JSON -- malformed, or a field of the wrong JSON type, such as a string where the payeeKey object belongs; and, from the idempotency gate: X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- The payer account does not resolve to an account visible to the caller (PIX-0750). '409': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- The payee key is registered to the PAYER's own account (PIX-0124), and a payer cannot schedule payments to their own key. Nothing was created; do not retry. '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: >- The X-Idempotency header was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- X-Idempotency replayed with a divergent request -- a different method, URL (including the path parameter) or body (PIX-0031). Legacy {code,title,message} envelope, NOT problem+json. '422': content: application/problem+json: examples: foreignBlock: summary: >- PIX-0751 -- a block another initiation type reads is present; remove it value: type: https://errors.lerian.studio/v1/PIX-0751 title: Unprocessable Entity status: 422 detail: >- The payload does not fit the declared initiation type: a field that type requires is missing or invalid, or a field that only another initiation type reads is present. errors: - message: >- payeeKey is not allowed when initiationType is MANUAL: the payee is the destination sent location: payeeKey code: PIX-0751 missingBlock: summary: >- PIX-0751 with no errors -- the block the initiation type requires is absent (supply it), or initiationType is QR_CODE, which a series cannot be initiated from. The same bare body also answers a zero amount. value: type: https://errors.lerian.studio/v1/PIX-0751 title: Unprocessable Entity status: 422 detail: >- The payload does not fit the declared initiation type: a field that type requires is missing or invalid, or a field that only another initiation type reads is present. code: PIX-0751 schema: $ref: '#/components/schemas/Detail' description: >- The request is well formed and cannot be accepted. Read the code, not the status: PIX-0761 no termination criterion was supplied -- add exactly one; PIX-0762 more than one was supplied -- remove the others; PIX-0764 the first payment date is past, beyond this participant's scheduling horizon, or the end date precedes it; PIX-0751 the payload lacks the block its initiationType requires -- supply it; this refusal carries no field detail -- or carries the other type's block -- a destination on DICT, a payeeKey on MANUAL -- in which case errors names that field, and it must be removed -- or declares QR_CODE, which a series cannot be initiated from; PIX-0755 the directory has no entry for the payee key; PIX-0766 the participant's materialization horizon is not usable, which is a configuration fault rather than a fault in this request and needs an operator. '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Internal Server Error '502': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- DICT Hub could not resolve the payee key (PIX-0700): unreachable, a server error, or any answer that says nothing about the key. The series was NOT created and nothing was charged. Retrying is safe. '503': content: application/json: example: code: PIX-0032 title: Idempotency Unavailable message: >- The request was not processed because the idempotency store is unavailable. Please retry. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- Replay cache unavailable on this fail-closed route, so the mutation was refused rather than executed without replay protection (PIX-0032). Legacy {code,title,message} envelope, NOT problem+json. default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error components: schemas: CreateRecurrenceBody: additionalProperties: false properties: accountId: description: >- 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. examples: - 0195948b-bf02-7e4f-9a1b-2c3d4e5f6a7b format: uuid type: string amount: description: >- Amount of EVERY occurrence, in BRL with two decimals. The available balance is NOT touched at creation, nor by the occurrences this call materializes. examples: - '150.00' type: string currency: description: Always BRL. Present for forward compatibility only. enum: - BRL examples: - BRL type: string description: description: >- Free-text memo carried by every occurrence, at most 140 characters -- the RmtInf ceiling. Stored and returned VERBATIM. examples: - Aluguel maxLength: 140 type: string destination: $ref: '#/components/schemas/DestinationBody' description: >- 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). initiationType: description: >- 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. enum: - MANUAL - DICT - QR_CODE examples: - DICT type: string metadata: additionalProperties: {} description: >- 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. examples: - contractRef: A-4471 type: object payeeKey: $ref: '#/components/schemas/PayeeKeyBody' description: >- 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). purpose: description: >- 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. enum: - IPAY examples: - IPAY type: string recurrence: $ref: '#/components/schemas/RecurrenceSpecBody' description: The rule that describes the series. required: - accountId - amount - initiationType - recurrence type: object RecurrenceDetailView: additionalProperties: false properties: accountId: description: Payer account. examples: - 0195948b-bf02-7e4f-9a1b-2c3d4e5f6a7b type: string amount: description: Amount of every occurrence, in BRL. examples: - '150.00' type: string createdAt: format: date-time type: string currency: description: Always BRL. examples: - BRL type: string description: description: >- The payer's memo, carried by every occurrence and returned exactly as stored. examples: - Aluguel type: string destination: $ref: '#/components/schemas/ParticipantView' description: >- 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. id: description: Series identifier. examples: - 01a0d8fb-1a8b-7a10-b3c4-d5e6f7a8b9c0 type: string initiationType: description: How the destination was resolved at creation. enum: - MANUAL - DICT - QR_CODE examples: - DICT type: string lastPaymentDate: description: >- Civil date of the series' final payment, when it has one. Null on an indefinite series, where reporting one would be a fabrication. examples: - '2028-07-10' format: date type: - string - 'null' materializedThrough: description: >- 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. examples: - '2027-10-10' format: date type: - string - 'null' metadata: additionalProperties: {} description: >- The annotation the caller sent at creation, returned verbatim. Absent when none was sent -- this service never invents one. examples: - contractRef: A-4471 type: object occurrences: description: >- 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. items: $ref: '#/components/schemas/ScheduledPaymentView' type: array payeeKey: $ref: '#/components/schemas/PayeeKeyView' description: >- 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. purpose: description: 'Always IPAY: REG-Art.11-P prohibits scheduling any other purpose.' enum: - IPAY examples: - IPAY type: string recurrence: $ref: '#/components/schemas/RecurrenceSpecView' description: The rule the occurrences are computed from. source: $ref: '#/components/schemas/ParticipantView' description: The payer as photographed at creation. status: description: >- 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. enum: - ACTIVE - COMPLETED - CANCELLED examples: - ACTIVE type: string updatedAt: format: date-time type: string required: - occurrences - id - accountId - amount - currency - status - initiationType - purpose - recurrence - source - destination - materializedThrough - lastPaymentDate - createdAt - updatedAt type: object LegacyErrorEnvelope: additionalProperties: false properties: code: description: PIX-XXXX error code type: string message: description: Human-readable error message type: string title: description: Short error title type: string required: - code - title - message type: object Detail: additionalProperties: true properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object DestinationBody: additionalProperties: false properties: account: $ref: '#/components/schemas/DestinationAccountBody' owner: $ref: '#/components/schemas/DestinationOwnerBody' required: - account - owner type: object PayeeKeyBody: additionalProperties: false properties: keyType: description: Kind of Pix key. enum: - EMAIL - PHONE - CPF - CNPJ - EVP examples: - EMAIL type: string keyValue: description: >- The key itself. Resolved at creation to photograph the payee, and resolved AGAIN on the scheduled date: REG-Art.9§5 makes the re-lookup mandatory because a key can be reassigned in between. examples: - joao.pereira@example.com type: string required: - keyType - keyValue type: object RecurrenceSpecBody: additionalProperties: false properties: endDate: description: >- Termination by civil date. It may equal firstPaymentDate, which is a legitimate series of one payment. examples: - '2028-07-10' format: date type: string firstPaymentDate: description: >- Civil date of the first payment, in America/Sao_Paulo. Never an instant: a date that is still today in UTC can already be yesterday here. It is used VERBATIM as the first occurrence and, on a monthly series, is what the reference day is derived from. examples: - '2027-08-10' format: date type: string indefinite: description: >- An open-ended series. This IS a termination criterion the payer chose -- supply exactly one of the three. Sending none is refused with PIX-0761 rather than read as open-ended: silence is a series nobody can say when to stop paying. examples: - false type: boolean paymentCount: description: >- Termination by number of payments. NO ceiling is imposed: REG-Art.37-A forbids limiting the quantity of a user's transactions. examples: - 12 format: int64 minimum: 1 type: integer periodicity: description: >- How often the series pays. QUARTERLY, SEMIANNUAL and ANNUALLY belong to Pix Automatico and are refused here by request validation (400 PIX-0003). enum: - WEEKLY - MONTHLY examples: - MONTHLY type: string required: - periodicity - firstPaymentDate type: object ParticipantView: additionalProperties: false properties: accountNumber: examples: - '123456' type: string accountType: enum: - CACC - SVGS - TRAN - SLRY examples: - CACC type: string branch: examples: - '0001' type: string ispb: description: 8-digit BACEN participant identifier. examples: - '32074986' type: string name: examples: - Ana Souza type: string personType: enum: - NATURAL_PERSON - LEGAL_PERSON examples: - NATURAL_PERSON type: string taxId: description: CPF or CNPJ, digits only. examples: - '39053344705' type: string required: - accountType - ispb - personType - taxId - name type: object ScheduledPaymentView: additionalProperties: false properties: accountId: description: Payer account. examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string amount: description: Amount to settle, in BRL. examples: - '150.00' type: string attempts: description: >- Every attempt of the scheduled day, oldest first. Empty before that date, and never null. items: $ref: '#/components/schemas/ScheduleAttemptView' type: - array - 'null' cancellationCutoff: description: >- The first instant a cancellation is REFUSED. Cancellation is accepted right up to it and refused AT it, and it is strictly before the first window so the two can never overlap. format: date-time type: string cancelledReason: description: >- Present exactly when status is CANCELLED. A cancellation the payer asked for and one the domain performed are deliberately distinguishable. enum: - USER_REQUEST - OWNERSHIP_MISMATCH - KEY_NOT_FOUND - RECURRENCE_CANCELLED type: string createdAt: format: date-time type: string currency: description: Always BRL. examples: - BRL type: string description: description: >- The payer's memo, returned exactly as it was stored. Markup is not interpreted here and was not escaped on the way in; escaping belongs to whoever renders it. examples: - Aluguel de setembro type: string destination: $ref: '#/components/schemas/ParticipantView' description: >- The payee as photographed at creation. On a DICT schedule it is compared on the scheduled date against a fresh directory answer (REG-Art.9§6), which is why it is stored rather than re-resolved; a MANUAL or QR_CODE schedule is sent to it as photographed, with no second lookup. firstWindowOpensAt: description: >- When the first settlement window of the scheduled date opens (IN 513 art. 12 caput). Photographed at creation. format: date-time type: string id: description: Schedule identifier. examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string initiationType: description: How the destination was resolved. enum: - MANUAL - DICT - QR_CODE examples: - DICT type: string purpose: description: 'Always IPAY: REG-Art.11-P prohibits scheduling any other purpose.' enum: - IPAY examples: - IPAY type: string scheduledDate: description: Civil settlement date in AAAA-MM-DD, in America/Sao_Paulo. examples: - '2026-09-10' format: date type: string source: $ref: '#/components/schemas/ParticipantView' description: The payer as photographed at creation. status: description: >- Lifecycle status. DISPATCHED_OUTCOME_UNKNOWN is NOT terminal: the order is awaiting reconciliation and will resolve to SETTLED or FAILED. It does NOT assert that the order reached the rail -- it also covers an order that provably did not, whose reserved funds are still being released. enum: - PENDING - EXECUTING - DISPATCHED_OUTCOME_UNKNOWN - AWAITING_RETRY - SETTLED - CANCELLED - FAILED examples: - PENDING type: string transferId: description: The transfer that settled this schedule, once it has. type: string updatedAt: format: date-time type: string required: - id - accountId - scheduledDate - amount - currency - initiationType - purpose - source - destination - status - firstWindowOpensAt - cancellationCutoff - createdAt - updatedAt - attempts type: object PayeeKeyView: additionalProperties: false properties: keyType: description: Kind of Pix key. enum: - EMAIL - PHONE - CPF - CNPJ - EVP examples: - EMAIL type: string keyValue: description: The key itself, as it was resolved. examples: - joao.pereira@example.com type: string required: - keyType - keyValue type: object RecurrenceSpecView: additionalProperties: false properties: endDate: description: >- Termination by civil date, when that is the criterion. Null otherwise. examples: - '2028-07-10' format: date type: - string - 'null' firstPaymentDate: description: Civil date of the first payment, exactly as the payer chose it. examples: - '2027-08-10' format: date type: string indefinite: description: >- True when the series is open-ended. Exactly one of the three criteria is set. examples: - false type: boolean paymentCount: description: >- Termination by number of payments, when that is the criterion. Null otherwise. examples: - 12 format: int64 type: - integer - 'null' periodicity: description: How often the series pays. enum: - WEEKLY - MONTHLY examples: - MONTHLY type: string referenceDayOfMonth: description: >- Day of the month a MONTHLY series pays on, derived from firstPaymentDate and PRESERVED across occurrences. Null on a weekly series. When a month has no such day -- 29, 30, 31 -- IN BCB 513/2024 art. 13 moves that occurrence to the FIRST DAY OF THE FOLLOWING MONTH and the reference day returns afterwards, so a day-31 series pays on 1 March and again on 31 March. examples: - 10 format: int64 type: - integer - 'null' required: - periodicity - firstPaymentDate - paymentCount - endDate - indefinite - referenceDayOfMonth type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object DestinationAccountBody: additionalProperties: false properties: branch: description: Branch code at the receiving institution. examples: - '0001' type: string number: description: Account number at the receiving institution. examples: - '654321' type: string participant: description: 8-digit BACEN ISPB of the receiving institution. examples: - '60746948' type: string type: description: >- Account type. SLRY (salary account) is refused by request validation (400 PIX-0003): a salary account cannot receive a Pix, and the rail would refuse it only on the scheduled date. enum: - CACC - SVGS - TRAN examples: - CACC type: string required: - number - participant - type type: object DestinationOwnerBody: additionalProperties: false properties: document: description: >- Payee CPF or CNPJ, digits only. The check digits are verified, and the person type is derived from it. examples: - '11222333000181' type: string name: description: Payee name as it should appear on the receipt. examples: - Mercado Central LTDA type: string required: - document - name type: object ScheduleAttemptView: additionalProperties: false properties: attemptNumber: examples: - 1 format: int64 type: integer endToEndId: description: >- The identifier the attempt dispatched under. Reconciliation of an unknown outcome happens by this value, and it is never minted twice. type: string finishedAt: description: Present exactly when outcome is. format: date-time type: string id: type: string isLastAttempt: description: >- Whether the day's window schedule allowed a further attempt after this one. type: boolean outcome: description: >- How the attempt ended. The two OPERATIONAL_FAILURE members are distinct because only the pre-dispatch one is safe to retry. enum: - SETTLED - INSUFFICIENT_FUNDS - INSUFFICIENT_LIMIT - OWNERSHIP_MISMATCH - KEY_NOT_FOUND - OPERATIONAL_FAILURE_PRE_DISPATCH - OPERATIONAL_FAILURE_POST_DISPATCH type: string providerChannel: description: >- The CSM channel the attempt went out on. UNKNOWN is a real answer from a rail that cannot report one. enum: - PRIMARY - SECONDARY - UNKNOWN type: string startedAt: format: date-time type: string required: - id - attemptNumber - isLastAttempt - startedAt type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.