> ## 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.2.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 - description: >- Hold the funds of a received Pix in a cautionary block (MED 2.0), return them to the payer, or give them back to the account holder. name: Balance Locks 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, an identical resend returns the original response, status included, with X-Idempotency-Replayed: true, and reusing the 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: '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. Route-guard refusals (PIX-0010) answer in the legacy {code,title,message} envelope too. '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 is held by a request still running or whose receipt could not be stored, or was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- Refused under this X-Idempotency (PIX-0031): the first request under it is still running (with Retry-After: 1), its receipt could not be stored and the key is held for the hour, or the request differs from the first (method, URL, body or identity header). An earlier request under this key may already have executed. Legacy {code,title,message} envelope, NOT problem+json. '415': content: application/json: example: code: PIX-0016 title: Unsupported Media Type message: >- The request body must be sent with Content-Type: application/json. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- The non-empty request body is missing an accepted JSON Content-Type (PIX-0016), answered in the legacy {code,title,message} envelope over application/json, 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-0758 the first payment is today and it is already 08:00 or later in America/Sao_Paulo -- start the series on a later date; 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; PIX-0328 the payer's ledger account is blocked -- unblock it in the ledger and send again; PIX-0332 the payer's ledger account is closed and can send nothing. '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. PIX-0705: the ledger could not read the payer account (unreachable, or an answer that does not say the account is absent). PIX-0702: the CRM gave no verdict on the payer's holder (unreachable, refused this platform's credential, or a failure that does not say the holder is absent or malformed). 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 fields: additionalProperties: type: string description: Per-field detail, keyed by the field or header the refusal names type: object headers: additionalProperties: type: string description: Per-header detail, keyed by the request header the refusal names type: object 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. Today is accepted only before 08:00 in America/Sao_Paulo (PIX-0758). 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-character BACEN participant identifier (digits or uppercase letters). 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. CHARGE_AMOUNT_CHANGED and CHARGE_NOT_PAYABLE: on the scheduled date the QR charge asked another amount, or the receiver refused reading it (the charge was removed, concluded or expired); nothing was debited. A failed check of the receiver's site or signature cancels nothing: like a receiver that does not answer, it pays the recorded amount. enum: - USER_REQUEST - OWNERSHIP_MISMATCH - KEY_NOT_FOUND - CHARGE_AMOUNT_CHANGED - CHARGE_NOT_PAYABLE - 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-character BACEN ISPB (digits or uppercase letters) 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 - CHARGE_AMOUNT_CHANGED - CHARGE_NOT_PAYABLE - 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.