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: /refunds: get: description: Returns a cursor-paginated page of refunds for the calling account. operationId: listRefunds x-mint: href: /pt/reference/interfaces/pix-lerian/spi/list-refunds parameters: - description: Account UUID in: header name: X-Account-Id required: true schema: description: Account UUID examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string - description: Filter by original transfer UUID explode: false in: query name: transferId schema: description: Filter by original transfer UUID type: string - description: Filter by refund status (lowercase) explode: false in: query name: status schema: description: Filter by refund status (lowercase) examples: - completed type: string - description: Filter by direction (lowercase) explode: false in: query name: direction schema: description: Filter by direction (lowercase) examples: - out type: string - description: Opaque cursor returned by the previous page explode: false in: query name: after schema: description: Opaque cursor returned by the previous page type: string - description: Page size (1-100, default 20) explode: false in: query name: limit schema: description: Page size (1-100, default 20) examples: - '20' type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/RefundsListOutput' description: OK '400': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0403 title: Bad Request status: 400 detail: Missing or malformed required fields for refund. code: PIX-0403 schema: $ref: '#/components/schemas/Detail' description: Missing, duplicated, or malformed X-Account-Id, or invalid transferId, status, direction, cursor, or limit filter input (PIX-0001, PIX-0017, PIX-0020, PIX-0403). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: The server could not complete the request. Please try again later. code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Unexpected server error (PIX-0000). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: List Pix refunds for an account tags: - Refunds /refunds/{id}: get: description: Returns a single refund scoped to the calling account. operationId: getRefund x-mint: href: /pt/reference/interfaces/pix-lerian/spi/get-refund parameters: - description: Account UUID in: header name: X-Account-Id required: true schema: description: Account UUID examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string - description: Refund UUID in: path name: id required: true schema: description: Refund UUID examples: - 0196080a-1234-7890-abcd-ef0123456789 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/RefundCashoutOutput' description: OK '400': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0403 title: Bad Request status: 400 detail: Missing or malformed required fields for refund. code: PIX-0403 schema: $ref: '#/components/schemas/Detail' description: Missing, duplicated, or malformed X-Account-Id or refund UUID (PIX-0001, PIX-0015, PIX-0017, PIX-0403). '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0420 title: Not Found status: 404 detail: Refund ID does not exist for this organization. code: PIX-0420 schema: $ref: '#/components/schemas/Detail' description: No refund exists for the supplied UUID in the calling account scope (PIX-0420). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: The server could not complete the request. Please try again later. code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Unexpected server error (PIX-0000). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Get a Pix refund by ID tags: - Refunds /refunds/{id}/unblock: post: description: |- Resolves ONE outbound refund that is stuck in `PROCESSING`. Pix Lerian asks the SPI for the outcome of the refund and applies it. The request has no field to state what happened. The refund must have been in `PROCESSING` for at least 90 minutes. If the SPI reports the refund as completed, the refund becomes `COMPLETED`. If the SPI reports it as rejected or failed, the refund becomes `FAILED` and Pix Lerian reverses the debit. If the SPI has no final outcome yet, the call is refused with `PIX-0556`: retry later. If Pix Lerian cannot get the status from the SPI, the call answers `502` (`PIX-0557`) and Pix Lerian changes nothing. A refund that is already in a final status is refused with `PIX-0554`. A refund in any other status is refused with `PIX-0551`. The caller needs the refunds permission with the post action, the same permission that creates a refund. The response is the refund as [Get refund](/pt/reference/interfaces/pix-lerian/spi/get-refund) returns it. operationId: unblockRefund x-mint: href: /pt/reference/interfaces/pix-lerian/spi/unblock-refund 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. Replaying the same key with a different URL, X-Account-Id, X-Actor-Id, X-Override-Reason or X-Override-Ticket is PIX-0031 @ 412. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Refund UUID in: path name: id required: true schema: description: Refund UUID examples: - 0196080a-1234-7890-abcd-ef0123456789 type: string - description: Source account UUID. A refund that exists under a different account is answered 404. in: header name: X-Account-Id required: true schema: description: Source account UUID. A refund that exists under a different account is answered 404. examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string - description: Optional. Identifies the person in your back office who asked for the check. Pix Lerian does not use it to decide the outcome. in: header name: X-Actor-Id schema: maxLength: 255 description: Optional. Identifies the person in your back office who asked for the check. Pix Lerian does not use it to decide the outcome. examples: - ops-maria type: string - description: Optional. Reason for the check. Pix Lerian does not use it to decide the outcome. in: header name: X-Override-Reason schema: maxLength: 512 description: Optional. Reason for the check. Pix Lerian does not use it to decide the outcome. examples: - outcome never arrived type: string - description: Optional. Ticket reference in your own back office. Pix Lerian does not use it to decide the outcome. in: header name: X-Override-Ticket schema: maxLength: 255 description: Optional. Ticket reference in your own back office. Pix Lerian does not use it to decide the outcome. examples: - OPS-4711 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/RefundCashoutOutput' description: OK '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: schema: $ref: '#/components/schemas/Detail' description: "Two shapes share this status, one per media type. application/problem+json: X-Account-Id or the refund UUID is missing or malformed (PIX-0001, PIX-0015, PIX-0017), or an attribution header exceeds its maximum length (PIX-0403). application/json is the legacy {code,title,message} envelope, from the idempotency gate: X-Idempotency absent or longer than 64 bytes (PIX-0030)." '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: No outbound refund exists for the supplied UUID in the calling account scope (PIX-0420). '409': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: "The refund cannot be unblocked now. PIX-0554: it is already in a final status. PIX-0555: it has been in PROCESSING for less than 90 minutes, so retry later. PIX-0551: it is not in PROCESSING. PIX-0556: the SPI has no final outcome yet, so retry later. PIX-0406: the refund changed during the request, so read it again and 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 URL (including the path parameter), X-Account-Id, X-Actor-Id, X-Override-Reason or X-Override-Ticket (PIX-0031). Legacy {code,title,message} envelope, NOT problem+json. '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Unexpected server error (PIX-0000). '502': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: "The call could not conclude. PIX-0557: Pix Lerian could not get the status from the SPI, and it changed nothing. PIX-0553: the debit reversal did not complete." default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Unblock a Pix refund stuck in PROCESSING tags: - Refunds /scheduled-payment-limit-impact: get: description: 'The totals route seen from the other side: given a proposed limit, returns the future schedules that would exceed it, so the institution can see the consequence BEFORE concluding a reduction. This route reads -- it does not apply the reduction and does not judge it. Each item carries its date''s total, so a caller can see why a small schedule is affected rather than only that it is. Nothing affected is an empty page, never null.' operationId: getScheduledPaymentLimitImpact x-mint: href: /pt/reference/interfaces/pix-lerian/spi/get-scheduled-payment-limit-impact parameters: - description: Payer account. explode: false in: query name: account_id schema: description: Payer account. examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string - description: The limit being considered. This route reports what it would break; it does NOT apply the reduction. explode: false in: query name: proposed_limit schema: description: The limit being considered. This route reports what it would break; it does NOT apply the reduction. examples: - '1000.00' type: string - description: Earliest settlement date to consider, inclusive. explode: false in: query name: start_date schema: description: Earliest settlement date to consider, inclusive. format: date type: string - description: Latest settlement date to consider, inclusive. explode: false in: query name: end_date schema: description: Latest settlement date to consider, inclusive. format: date type: string - description: Page size, 1..100. Absent or 0 means 20. A negative value or one above 100 is REFUSED, never clamped -- the same rule the sibling list route follows. explode: false in: query name: limit schema: description: Page size, 1..100. Absent or 0 means 20. A negative value or one above 100 is REFUSED, never clamped -- the same rule the sibling list route follows. format: int64 type: integer maximum: 100 minimum: 0 - description: Opaque cursor from a previous page. explode: false in: query name: cursor schema: description: Opaque cursor from a previous page. type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/LimitImpactPageView' description: OK '400': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: "A query parameter cannot be used. PIX-0020: account_id absent or not a UUID, proposed_limit absent or not a non-negative decimal amount with exactly two places, start_date or end_date not a civil date in AAAA-MM-DD, or limit negative or above 100 (0, like an absent limit, means the default page size of 20) -- the response names each offending parameter. PIX-0789: the cursor is not one this service issued, or it was truncated. Zero IS a valid proposed limit and a meaningful question -- it asks what a total freeze would break." '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' examples: limitNotInteger: summary: Framework binding refusal of a non-integer limit -- no PIX code value: title: Unprocessable Entity status: 422 detail: validation failed errors: - message: invalid integer location: query.limit value: abc description: "end_date is earlier than start_date (PIX-0751, no field detail). An inverted range is refused rather than answered with an empty page, which a caller could not tell from 'nothing is affected'. The same status is also the FRAMEWORK's request-binding refusal of a `limit` that is not an integer: that body carries no PIX-NNNN code and names the parameter in `errors`." "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Schedules a proposed limit would make unviable tags: - Scheduled Payments /scheduled-payment-totals: get: description: 'THIS ROUTE AND ITS SIBLING ARE THE WHOLE OF WHAT THE SWITCH DOES ABOUT DAILY PIX LIMITS. The policy belongs to the client institution, which holds the ISPB and answers to BACEN for it; the Switch does not accumulate, project or decide. It returns the figure the decision needs. The total sums every NON-TERMINAL schedule for that account on that date -- cancelled and failed ones are excluded, because neither will move money. Supplying night_period_start adds the IN 512 art. 7 §7 slice, which is a DIFFERENT rule from the general night period of art. 3: created inside the window, settling the next day, to a natural person distinct from the payer. Omit the parameter and the slice is omitted rather than defaulted.' operationId: getScheduledPaymentTotals x-mint: href: /pt/reference/interfaces/pix-lerian/spi/get-scheduled-payment-totals parameters: - description: 'Payer account. Required: the total is per account, and an unscoped one would be meaningless.' explode: false in: query name: account_id schema: description: 'Payer account. Required: the total is per account, and an unscoped one would be meaningless.' examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string - description: Civil date the total is computed for, in America/Sao_Paulo. explode: false in: query name: scheduled_date schema: description: Civil date the total is computed for, in America/Sao_Paulo. examples: - '2026-09-10' format: date type: string - description: 'Local time the night period opens, HH:MM in America/Sao_Paulo. Absent means the night slice is OMITTED rather than defaulted: where that window opens is the institution''s setting (IN 512 art. 3), and inventing one would publish our number under their name.' explode: false in: query name: night_period_start schema: description: 'Local time the night period opens, HH:MM in America/Sao_Paulo. Absent means the night slice is OMITTED rather than defaulted: where that window opens is the institution''s setting (IN 512 art. 3), and inventing one would publish our number under their name.' examples: - '20:00' type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ScheduledTotalsView' description: OK '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: 'night_period_start is not HH:MM on a 24-hour clock (PIX-0787). The night start is validated here rather than passed to storage, where an unparseable value would surface as an internal error for what is a typo.' "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "A query parameter is missing or malformed (PIX-0020): account_id absent or not a UUID, or scheduled_date absent or not a civil date in AAAA-MM-DD. The response names each offending parameter." "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Total scheduled for an account on a date tags: - Scheduled Payments /scheduled-payments: get: description: "Returns a page of the organization's scheduled payments, newest settlement date first. Paging is by opaque cursor rather than offset: a schedule registered between two pages would shift every later row under an offset and silently skip one. Echo the cursor verbatim. The page carries no attempt history -- that is per-schedule data a list view does not show, and it is on the single-schedule route instead. Filtering by recurrence_id is how the occurrences of a recurring series are enumerated: an occurrence IS a scheduled payment, so it is listed here rather than under a route of its own, which would give the same row two identities." operationId: listScheduledPayments x-mint: href: /pt/reference/interfaces/pix-lerian/spi/list-scheduled-payments parameters: - description: Page size, 1..100. Absent or 0 means 20. A negative value or one above 100 is REFUSED, never clamped -- a clamped page size makes a caller believe it read everything. explode: false in: query name: limit schema: description: Page size, 1..100. Absent or 0 means 20. A negative value or one above 100 is REFUSED, never clamped -- a clamped page size makes a caller believe it read everything. examples: - 20 format: int64 type: integer maximum: 100 minimum: 0 - description: Opaque cursor from a previous page's pagination block. Echo it verbatim -- it is not a document to build. explode: false in: query name: cursor schema: description: Opaque cursor from a previous page's pagination block. Echo it verbatim -- it is not a document to build. type: string - description: Narrow to one payer account. explode: false in: query name: account_id schema: description: Narrow to one payer account. type: string - description: Narrow to one lifecycle status. explode: false in: query name: status schema: description: Narrow to one lifecycle status. enum: - PENDING - EXECUTING - DISPATCHED_OUTCOME_UNKNOWN - AWAITING_RETRY - SETTLED - CANCELLED - FAILED type: string - description: Earliest settlement date to include, inclusive. explode: false in: query name: start_date schema: description: Earliest settlement date to include, inclusive. examples: - '2026-09-01' format: date type: string - description: Latest settlement date to include, inclusive. explode: false in: query name: end_date schema: description: Latest settlement date to include, inclusive. examples: - '2026-09-30' format: date type: string - description: "Narrow to the occurrences of ONE recurring series. This is how a series' occurrences are enumerated: an occurrence IS a scheduled payment, so it is listed here rather than under a route of its own, which would give the same row two identities." explode: false in: query name: recurrence_id schema: description: "Narrow to the occurrences of ONE recurring series. This is how a series' occurrences are enumerated: an occurrence IS a scheduled payment, so it is listed here rather than under a route of its own, which would give the same row two identities." examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ScheduledPaymentsPage' description: OK '400': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: "A filter cannot be used. PIX-0020: account_id or recurrence_id is not a UUID, status is not a scheduled-payment status, start_date or end_date is not a civil date in AAAA-MM-DD, or limit is negative or above 100 (0, like an absent limit, means the default page size of 20) -- the response names each offending parameter. PIX-0003: end_date is earlier than start_date; an inverted range is refused rather than answered with an empty page, because the two are indistinguishable to the caller and only one of them is their mistake. PIX-0789: the cursor is not one this service issued, or it was truncated -- restart the listing without a cursor." '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' example: title: Unprocessable Entity status: 422 detail: validation failed errors: - message: invalid integer location: query.limit value: abc description: "`limit` is not an integer. This is the FRAMEWORK's request-binding refusal, not one of this service's: it carries no PIX-NNNN code, names the offending parameter in `errors`, and happens before any filter is looked at. Every other bad value on this operation is the 400 above instead." "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: List scheduled Pix payments tags: - Scheduled Payments post: description: "Registers a Pix payment for a future civil date, evaluated in America/Sao_Paulo. The available balance is NOT touched here (REG-Art.9 caput): nothing moves until the scheduled date, when the order is sent inside the settlement window IN 513 art. 12 fixes. Non-business days are accepted, because Pix settles every day. Pix Saque (OTHR) and Pix Troco (GSCB) are refused at creation rather than on the scheduled date: REG-Art.11-P prohibits scheduling them, and the rule is knowable now. The payee is photographed at creation. On a DICT schedule the key is resolved again on the scheduled date and compared against that photograph, which is what REG-Art.9§5 requires -- a key can be reassigned in between. A MANUAL or QR_CODE schedule is not looked up again: it is sent to the payee photographed at creation. A schedule can also be born from a BR Code: send initiationType QR_CODE with the emvPayload, including a due-date collection code, and the payee is resolved from the key the code carries. The txId it names and the payload itself are recorded with the schedule and shown on its receipt. The scheduled date you send is the one that is used -- it is NOT checked against the collection's own due date. Send only the block your initiationType reads -- payeeKey for DICT, destination for MANUAL, emvPayload for QR_CODE. The blocks are mutually exclusive: a body carrying another 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)." operationId: createScheduledPayment x-mint: href: /pt/reference/interfaces/pix-lerian/spi/create-scheduled-payment 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. 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: schema: $ref: '#/components/schemas/CreateScheduledPaymentBody' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/ScheduledPaymentView' 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: scheduledDate does not match the 2006-01-02 format location: scheduledDate 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: payeeKey.keyType is a required field location: payeeKey.keyType - message: payeeKey.keyValue is a required field location: payeeKey.keyValue 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: "This organization already created a scheduled payment under the same X-Idempotency key (PIX-0756). Nothing was created and nothing was charged by THIS request; the earlier schedule stands -- find it with GET /scheduled-payments filtered by account and settlement date. Which status you get depends on how long ago the first request was. While the replay record lives, an identical retry replays the original response at 200 and a divergent one is refused with PIX-0031 @ 412. Once that record is gone -- it expires, and it is absent entirely during a cache outage -- any retry of an already-used key answers this 409 instead. IMPORTANT: the key is consumed PERMANENTLY for this organization. Unlike the replay record, the durable constraint behind this status never expires. Send a fresh key for each distinct creation -- a UUID per intent is the safe pattern -- and reuse a key only to retry the creation it already identified. Do not recycle keys from a counter or a per-invoice reference that repeats across cycles. PIX-0124 is the other 409, and it is not about the key header: the payee key (for a QR_CODE schedule, the key the BR Code carries) is registered to the PAYER's own account, and a payer cannot schedule a payment 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: schema: $ref: '#/components/schemas/Detail' 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: "destination is not allowed when initiationType is DICT: the payee is resolved from payeeKey" location: destination code: PIX-0751 missingBlock: summary: PIX-0751 with no errors -- most often the block the initiation type requires is absent; supply it. 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 description: "The request is well formed and cannot be accepted. Read the code, not the status: PIX-0751 the payload lacks the block its initiationType requires -- supply it; this refusal carries no field detail -- or carries a block another initiationType reads -- a destination on DICT, a payeeKey on MANUAL, a payeeKey or destination on QR_CODE, an emvPayload on anything but QR_CODE -- in which case errors names each such field; remove each; PIX-0752 the date is already past in America/Sao_Paulo; PIX-0754 the date is beyond the horizon this participant configured; PIX-0755 the directory has no entry for the payee key -- for a QR_CODE schedule that is the key the BR Code carries; PIX-0304 the emvPayload was read and refused as a BR Code." default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error "200": content: application/json: schema: $ref: "#/components/schemas/ScheduledPaymentView" description: "Idempotent replay: the same X-Idempotency key was sent with the same request, so the original creation's response is returned unchanged. The schedule was NOT created a second time." "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: "An upstream directory could not answer, so the schedule was NOT created and nothing was charged; retrying is safe. PIX-0701: COB Hub could not be reached to decode the emvPayload -- only a QR_CODE creation can answer this. PIX-0700: DICT Hub could not resolve the payee key (unreachable, a server error, or any answer that says nothing about the key) -- a DICT or QR_CODE creation can answer this." summary: Register a scheduled Pix payment tags: - Scheduled Payments /scheduled-payments/{schedule_id}: get: description: 'Returns the schedule together with every attempt of its scheduled day, oldest first. The list is empty and never null before that date. A schedule belonging to another organization answers 404 rather than 403: the read is scoped by organization, so the row is never seen, and answering ''forbidden'' would confirm the identifier exists.' operationId: getScheduledPayment x-mint: href: /pt/reference/interfaces/pix-lerian/spi/get-scheduled-payment parameters: - description: Schedule identifier. in: path name: schedule_id required: true schema: description: Schedule identifier. examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ScheduledPaymentView' description: OK '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: No schedule with that identifier exists for this organization, or it was soft-deleted (PIX-0770). "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: schedule_id is not a UUID (PIX-0015). The response names the parameter; the schedule is never looked up. "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Read one scheduled Pix payment tags: - Scheduled Payments /scheduled-payments/{schedule_id}/cancel: post: description: 'Cancels a schedule at the payer''s request, accepted right up to the cancellation cut-off recorded on it and refused AT that instant. The deadline compared against is the one photographed when the schedule was created, not whatever the configuration derives today: the deadline the payer was told is the deadline they get. Because the cut-off is strictly before the first settlement window, cancelling and executing can never both be in time. Nothing is released -- nothing was held.' operationId: cancelScheduledPayment x-mint: href: /pt/reference/interfaces/pix-lerian/spi/cancel-scheduled-payment 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. 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 - description: Schedule identifier. in: path name: schedule_id required: true schema: description: Schedule identifier. examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ScheduledPaymentView' description: OK '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Two shapes share this status, one per media type. application/problem+json: schedule_id is not a UUID (PIX-0015). The response names the parameter; the schedule is never looked up. application/json is the legacy {code,title,message} envelope, 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: No schedule with that identifier exists for this organization (PIX-0770). '409': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: 'The schedule cannot be cancelled from the state it is in. PIX-0771: it has already settled, been cancelled or failed -- re-read it, a terminal status does not transition. PIX-0773: it is executing, which under the cut-off precedence should be unreachable, so its occurrence is worth investigating rather than retrying.' '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: schema: $ref: '#/components/schemas/Detail' description: 'The cancellation cut-off recorded on this schedule has passed (PIX-0772). Not resolvable by retry: the deadline is the snapshot taken at creation, and at the exact instant it is already refused.' default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error summary: Cancel a scheduled Pix payment tags: - Scheduled Payments /scheduled-payments/{schedule_id}/receipt: get: description: 'Returns the proof of what was agreed: the amount, the settlement date, both parties as photographed at creation, and the cancellation deadline the payer was told. It carries no status and no attempt history on purpose -- a receipt answers what was committed to, and putting the lifecycle in it would make a document people save go stale the moment the schedule moves.' operationId: getScheduledPaymentReceipt x-mint: href: /pt/reference/interfaces/pix-lerian/spi/get-scheduled-payment-receipt parameters: - description: Schedule identifier. in: path name: schedule_id required: true schema: description: Schedule identifier. examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ScheduledPaymentReceiptView' description: OK '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: No schedule with that identifier exists for this organization, or it was soft-deleted (PIX-0770). "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: schedule_id is not a UUID (PIX-0015). The response names the parameter; the schedule is never looked up. "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Read a scheduled payment's receipt tags: - Scheduled Payments /transfers: get: description: "Returns a cursor-paginated page of transfers that involve the calling account (`X-Account-Id`). Use `direction=out` for payments the account sent and `direction=in` for payments it received. Omitting `direction` returns both legs: a payment settled between two accounts of the same organization is stored as two rows (one `OUTBOUND`, one `INBOUND`) sharing an `endToEndId`, so a direction-less query -- including one narrowed by `end_to_end_id` -- can return two items for a single payment. Pass `direction` when you need exactly one leg." operationId: listTransfers x-mint: href: /pt/reference/interfaces/pix-lerian/spi/list-transfers parameters: - description: Account UUID in: header name: X-Account-Id required: true schema: description: Account UUID examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string - description: Filter by transfer status (lowercase) explode: false in: query name: status schema: description: Filter by transfer status (lowercase) examples: - processing type: string - description: "Filter by direction (lowercase): 'in' for received (cash-in), 'out' for sent (cash-out). Omit to list both legs." explode: false in: query name: direction schema: description: "Filter by direction (lowercase): 'in' for received (cash-in), 'out' for sent (cash-out). Omit to list both legs." examples: - out type: string - description: Filter by BACEN end-to-end ID (32 chars) explode: false in: query name: end_to_end_id schema: description: Filter by BACEN end-to-end ID (32 chars) examples: - E12345678202605061030abcdef12345 type: string - description: Opaque cursor returned by the previous page explode: false in: query name: after schema: description: Opaque cursor returned by the previous page type: string - description: Page size (1-100, default 20) explode: false in: query name: limit schema: description: Page size (1-100, default 20) examples: - '20' type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/TransfersListOutput' description: OK '400': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0300 title: Bad Request status: 400 detail: Missing or malformed required fields for transfer initiation. code: PIX-0300 schema: $ref: '#/components/schemas/Detail' description: Missing, duplicated, or malformed X-Account-Id, or invalid status, direction, end-to-end ID, cursor, or limit filter input (PIX-0001, PIX-0017, PIX-0020, PIX-0300). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: The server could not complete the request. Please try again later. code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Unexpected server error (PIX-0000). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: List Pix transfers for an account tags: - Transfers /transfers/cashout/initiate: post: description: Creates a transfer initiation in PENDING state and validates the source account. The amount is supplied at process time. operationId: initiateTransfer x-mint: href: /pt/reference/interfaces/pix-lerian/spi/initiate-transfer 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. 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 - description: Source account UUID in: header name: X-Account-Id required: true schema: description: Source account UUID examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/InitiateTransferBody' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/InitiateTransferOutput' description: Created '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0300 title: Bad Request status: 400 detail: Missing or malformed required fields for transfer initiation. code: PIX-0300 schema: $ref: '#/components/schemas/Detail' description: Missing, duplicated, or malformed request headers/body fields, an initiation-type mismatch, or an invalid source account (PIX-0001-0003, PIX-0010, PIX-0017, PIX-0300-0302). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '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. '415': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0016 title: Unsupported Media Type status: 415 detail: 'The request body must be sent with Content-Type: application/json.' code: PIX-0016 schema: $ref: '#/components/schemas/Detail' description: The non-empty request body is missing an accepted JSON Content-Type (PIX-0016). '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0303 title: Unprocessable Entity status: 422 detail: DICT key lookup returned no results. code: PIX-0303 schema: $ref: '#/components/schemas/Detail' description: The DICT key cannot be resolved, the QR Code cannot be decoded, or the source ledger account is blocked (PIX-0303, PIX-0304, PIX-0328). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: The server could not complete the request. Please try again later. code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Unexpected server error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0700 title: Bad Gateway status: 502 detail: The server could not complete the request. Please try again later. code: PIX-0700 schema: $ref: '#/components/schemas/Detail' description: A required upstream service is unavailable (PIX-0700-0702, PIX-0705). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Initiate a Pix transfer (step 1) tags: - Transfers /transfers/cashout/process: post: description: 'Confirms a previously initiated transfer, debits the source account, and submits the Pix payment for processing. When the submission fails without proof that the order never left (a timeout or a 5xx), the debit is kept and the call answers 201 with status PROCESSING: read the transfer for the outcome. A 502 PIX-0325 answers only an order that provably was not sent, after a revert of the debit was attempted.' operationId: processTransfer x-mint: href: /pt/reference/interfaces/pix-lerian/spi/process-transfer 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. 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 - description: Source account UUID in: header name: X-Account-Id required: true schema: description: Source account UUID examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string - description: "Optional caller-supplied 32-char BACEN endToEndId, accepted for MANUAL initiations only (omit it to let SPI generate one). It is not the idempotency key -- that is X-Idempotency. A DICT or QR_CODE initiation already fixed its endToEndId at initiate (returned as endToEndId) and process reuses it automatically: for those, omit this header; sending it, even with the same value, is refused (PIX-0300) while the initiation is pending -- a retry of a process that already concluded (initiation CONFIRMED) returns the existing transfer, without the header or with a well-formed one." in: header name: X-End-To-End-Id schema: description: "Optional caller-supplied 32-char BACEN endToEndId, accepted for MANUAL initiations only (omit it to let SPI generate one). It is not the idempotency key -- that is X-Idempotency. A DICT or QR_CODE initiation already fixed its endToEndId at initiate (returned as endToEndId) and process reuses it automatically: for those, omit this header; sending it, even with the same value, is refused (PIX-0300) while the initiation is pending -- a retry of a process that already concluded (initiation CONFIRMED) returns the existing transfer, without the header or with a well-formed one." examples: - E12345678202605061030abcdef12345 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ProcessTransferBody' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/TransferResponse' description: Created '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0300 title: Bad Request status: 400 detail: Missing or malformed required fields for transfer initiation. code: PIX-0300 schema: $ref: '#/components/schemas/Detail' description: Missing, duplicated, or malformed request headers/body fields, an invalid end-to-end ID, an X-End-To-End-Id sent for a still-pending DICT or QR_CODE initiation (whose id was fixed at initiate), or a missing/invalid deferred amount (PIX-0001-0003, PIX-0010, PIX-0017, PIX-0300). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0320 title: Not Found status: 404 detail: Initiation ID does not exist. code: PIX-0320 schema: $ref: '#/components/schemas/Detail' description: No initiation exists for the supplied initiationId in the calling account scope (PIX-0320). '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0322 title: Conflict status: 409 detail: Initiation was already confirmed. code: PIX-0322 schema: $ref: '#/components/schemas/Detail' description: The initiation was already confirmed or cancelled, or a concurrent transfer write won the race (PIX-0322, PIX-0326, PIX-0327, PIX-0704). '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. '415': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0016 title: Unsupported Media Type status: 415 detail: 'The request body must be sent with Content-Type: application/json.' code: PIX-0016 schema: $ref: '#/components/schemas/Detail' description: The non-empty request body is missing an accepted JSON Content-Type (PIX-0016). '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0321 title: Unprocessable Entity status: 422 detail: Initiation has expired. code: PIX-0321 schema: $ref: '#/components/schemas/Detail' description: The initiation expired, the debit has insufficient funds, or the ledger account/balance cannot be used (PIX-0321, PIX-0323, PIX-0328, PIX-0329). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: The server could not complete the request. Please try again later. code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Unexpected server error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0324 title: Bad Gateway status: 502 detail: The server could not complete the request. Please try again later. code: PIX-0324 schema: $ref: '#/components/schemas/Detail' description: A required upstream service failed (PIX-0324, PIX-0325, PIX-0705). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Process and confirm a Pix transfer (step 2) tags: - Transfers /transfers/{id}: get: description: "Returns a single transfer that involves the calling account (`X-Account-Id`) on either side of the payment: one the account sent (`type: OUTBOUND`) or one it received (`type: INBOUND`). A transfer the account is neither side of returns 404 `PIX-0340`, the same answer as a transfer that does not exist." operationId: getTransfer x-mint: href: /pt/reference/interfaces/pix-lerian/spi/get-transfer parameters: - description: Account UUID in: header name: X-Account-Id required: true schema: description: Account UUID examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string - description: Transfer UUID in: path name: id required: true schema: description: Transfer UUID examples: - 0196070b-1234-7890-abcd-ef0123456789 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/TransferResponse' description: OK '400': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0300 title: Bad Request status: 400 detail: Missing or malformed required fields for transfer initiation. code: PIX-0300 schema: $ref: '#/components/schemas/Detail' description: Missing, duplicated, or malformed X-Account-Id or transfer UUID (PIX-0001, PIX-0015, PIX-0017, PIX-0300). '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0340 title: Not Found status: 404 detail: Transfer ID does not exist for this organization. code: PIX-0340 schema: $ref: '#/components/schemas/Detail' description: No transfer exists for the supplied UUID in the calling account scope (PIX-0340). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: The server could not complete the request. Please try again later. code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Unexpected server error (PIX-0000). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Get a Pix transfer by ID tags: - Transfers /transfers/{id}/unblock: post: description: |- Resolves ONE outbound transfer that is stuck in `PROCESSING`. Pix Lerian asks the SPI for the outcome of the payment and applies it. The request has no field to state what happened. The transfer must have been in `PROCESSING` for at least 90 minutes. If the SPI reports the payment as completed, the transfer becomes `COMPLETED`. If the SPI reports it as rejected or failed, the transfer becomes `REJECTED` and Pix Lerian reverses the debit. If the SPI has no final outcome yet, the call is refused with `PIX-0556`: retry later. If Pix Lerian cannot get the status from the SPI, the call answers `502` (`PIX-0557`) and Pix Lerian changes nothing. A transfer that is already in a final status is refused with `PIX-0554`. A transfer in any other status is refused with `PIX-0551`. The caller needs the transfers permission with the post action, the same permission that initiates and processes a transfer. The response is the transfer as [Get transfer](/pt/reference/interfaces/pix-lerian/spi/get-transfer) returns it. operationId: unblockTransfer x-mint: href: /pt/reference/interfaces/pix-lerian/spi/unblock-transfer 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. Replaying the same key with a different URL, X-Account-Id, X-Actor-Id, X-Override-Reason or X-Override-Ticket is PIX-0031 @ 412. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Transfer UUID in: path name: id required: true schema: description: Transfer UUID examples: - 0196070b-1234-7890-abcd-ef0123456789 type: string - description: Source account UUID. A transfer that exists under a different account is answered 404. in: header name: X-Account-Id required: true schema: description: Source account UUID. A transfer that exists under a different account is answered 404. examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string - description: Optional. Identifies the person in your back office who asked for the check. Pix Lerian does not use it to decide the outcome. in: header name: X-Actor-Id schema: maxLength: 255 description: Optional. Identifies the person in your back office who asked for the check. Pix Lerian does not use it to decide the outcome. examples: - ops-maria type: string - description: Optional. Reason for the check. Pix Lerian does not use it to decide the outcome. in: header name: X-Override-Reason schema: maxLength: 512 description: Optional. Reason for the check. Pix Lerian does not use it to decide the outcome. examples: - outcome never arrived type: string - description: Optional. Ticket reference in your own back office. Pix Lerian does not use it to decide the outcome. in: header name: X-Override-Ticket schema: maxLength: 255 description: Optional. Ticket reference in your own back office. Pix Lerian does not use it to decide the outcome. examples: - OPS-4711 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/TransferResponse' description: OK '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: schema: $ref: '#/components/schemas/Detail' description: "Two shapes share this status, one per media type. application/problem+json: X-Account-Id or the transfer UUID is missing or malformed (PIX-0001, PIX-0015, PIX-0017), or an attribution header exceeds its maximum length (PIX-0706). application/json is the legacy {code,title,message} envelope, from the idempotency gate: X-Idempotency absent or longer than 64 bytes (PIX-0030)." '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: No outbound transfer exists for the supplied UUID in the calling account scope (PIX-0340). '409': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: "The transfer cannot be unblocked now. PIX-0554: it is already in a final status. PIX-0555: it has been in PROCESSING for less than 90 minutes, so retry later. PIX-0551: it is not in PROCESSING. PIX-0556: the SPI has no final outcome yet, so retry later. PIX-0327: the transfer changed during the request, so read it again and 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 URL (including the path parameter), X-Account-Id, X-Actor-Id, X-Override-Reason or X-Override-Ticket (PIX-0031). Legacy {code,title,message} envelope, NOT problem+json. '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Unexpected server error (PIX-0000). '502': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: "The call could not conclude. PIX-0557: Pix Lerian could not get the status from the SPI, and it changed nothing. PIX-0553: the debit reversal did not complete." default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Unblock a Pix transfer stuck in PROCESSING tags: - Transfers /transfers/{id}/refunds: post: description: "Issues a refund against a previously completed CASHIN transfer with a structured pacs.004 reasonCode. A refund the rail refuses answers 422 PIX-0013 and its debit is reverted; if that revert does not complete, the refund stays PROCESSING. A provider send that fails without proving the pacs.004 was not sent (a timeout, a 5xx) compensates nothing and answers 201 with status PROCESSING, as a refund the provider accepts without a provider reference does: the debit stays recorded until the outcome arrives by end-to-end id (GET the refund or wait for its callback). A retry with the same X-Idempotency key within one hour of the first 2xx answer replays that refund with 200 instead of creating a second one, including when the request timed out while the provider was answering. Only a 2xx is replayed: after a 5xx or a 409 PIX-0406 the refund may still be PROCESSING with its debit, so list the transfer's refunds (GET /spi/v1/refunds?transferId=) before any retry." operationId: createRefund x-mint: href: /pt/reference/interfaces/pix-lerian/spi/create-refund 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. 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 - description: Account UUID in: header name: X-Account-Id required: true schema: description: Account UUID examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string - description: Original transfer UUID in: path name: id required: true schema: description: Original transfer UUID examples: - 0196070b-1234-7890-abcd-ef0123456789 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateRefundBody' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/RefundCashoutOutput' description: Created '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0403 title: Bad Request status: 400 detail: Missing or malformed required fields for refund. code: PIX-0403 schema: $ref: '#/components/schemas/Detail' description: Missing, duplicated, or malformed request headers/path/body fields, an invalid amount/reason, or another invalid refund input (PIX-0001-0003, PIX-0010, PIX-0015, PIX-0017, PIX-0403). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0400 title: Not Found status: 404 detail: Original transfer does not exist. code: PIX-0400 schema: $ref: '#/components/schemas/Detail' description: The original transfer does not exist in the calling account scope (PIX-0400). '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0406 title: Conflict status: 409 detail: The refund changed during this request. Retry the operation. code: PIX-0406 schema: $ref: '#/components/schemas/Detail' description: A concurrent refund update won the race, or the operation reached another conflicting state (PIX-0406, PIX-0704). '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. '415': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0016 title: Unsupported Media Type status: 415 detail: 'The request body must be sent with Content-Type: application/json.' code: PIX-0016 schema: $ref: '#/components/schemas/Detail' description: The non-empty request body is missing an accepted JSON Content-Type (PIX-0016). '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0401 title: Unprocessable Entity status: 422 detail: Original transfer is not in COMPLETED status. code: PIX-0401 schema: $ref: '#/components/schemas/Detail' description: The original transfer is not completed, the refund exceeds the remaining amount, the ledger account/balance cannot be used, or the rail refused the refund (PIX-0013, PIX-0401, PIX-0402, PIX-0328, PIX-0329). On PIX-0013 the debit is reverted; if that revert does not complete, the refund stays PROCESSING. '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: The server could not complete the request. Please try again later. code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Unexpected server error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0404 title: Bad Gateway status: 502 detail: The server could not complete the request. Please try again later. code: PIX-0404 schema: $ref: '#/components/schemas/Detail' description: A required upstream service failed (PIX-0404, PIX-0405, PIX-0705). '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 summary: Create an outbound Pix refund (MED) tags: - Refunds /scheduled-payment-recurrences: get: description: "Returns a page of the organization's series, newest first. Creation order is the only ordering a series can offer: a series has no settlement date of its own -- its occurrences carry those -- which is also why this route takes no date range. To ask which payments fall in a period, or to see the occurrences of one series, use GET /v1/scheduled-payments with recurrence_id. Paging is by opaque cursor rather than offset: a series registered between two pages would shift every later row under an offset and silently skip one. Echo the cursor verbatim. The status filter takes the SERIES' statuses (ACTIVE, COMPLETED, CANCELLED), not an occurrence's -- a cancelled series still has settled occurrences behind it." operationId: listScheduledPaymentRecurrences parameters: - description: Page size, 1..100. Absent or 0 means 20. explode: false in: query name: limit schema: default: 20 description: Page size, 1..100. Absent or 0 means 20. examples: - 20 format: int64 maximum: 100 minimum: 0 type: integer - description: Opaque cursor from a previous page. Echo it verbatim -- it is not a document to build. explode: false in: query name: cursor schema: description: Opaque cursor from a previous page. Echo it verbatim -- it is not a document to build. type: string - description: Narrow to one payer account. explode: false in: query name: account_id schema: description: Narrow to one payer account. format: uuid type: string - description: "Narrow to one series status. These are the SERIES' statuses, not an occurrence's: a cancelled series still has settled occurrences behind it." explode: false in: query name: status schema: description: "Narrow to one series status. These are the SERIES' statuses, not an occurrence's: a cancelled series still has settled occurrences behind it." enum: - ACTIVE - COMPLETED - CANCELLED type: string responses: "200": content: application/json: example: items: - 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" schema: $ref: "#/components/schemas/RecurrencesPage" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: The request could not be bound, or a filter cannot be used. The cursor is not one this service issued or it was truncated (PIX-0789); a status is not a SERIES status, account_id is not a UUID, or limit is negative or above 100 (PIX-0020, naming each offending parameter; 0, like an absent limit, means the default page size of 20). An occurrence status such as PENDING or SETTLED is refused rather than answered with an empty page, because the two vocabularies sit side by side and an empty page would read as 'you have no series'. Restart a cursor listing without the cursor. "422": content: application/problem+json: example: title: Unprocessable Entity status: 422 detail: validation failed errors: - message: invalid integer location: query.limit value: abc schema: $ref: "#/components/schemas/Detail" description: "`limit` is not an integer. This is the FRAMEWORK's request-binding refusal, not one of this service's: it carries no PIX-NNNN code, names the offending parameter in `errors`, and happens before any filter is looked at. Every other bad value on this operation -- an unknown status, a malformed cursor, a non-UUID account_id -- is the 400 above instead." "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: List recurring series tags: - Scheduled Payment Recurrences x-mint: href: /pt/reference/interfaces/pix-lerian/spi/list-recurring-series post: 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: 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. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" 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 summary: Create a recurring series tags: - Scheduled Payment Recurrences x-mint: href: /pt/reference/interfaces/pix-lerian/spi/create-recurring-series /scheduled-payment-recurrences/{recurrence_id}: get: description: "Returns the series -- its rule, both parties as photographed at creation, and the window edge -- together with the occurrences currently materialized for it, oldest first. The list is empty and never null, and it is a WINDOW rather than the whole calendar: materializedThrough says how far it reaches, and a long-running series is enumerated in full through GET /v1/scheduled-payments with recurrence_id. A series belonging to another organization answers 404 rather than 403: the read is scoped by organization, so the row is never seen, and answering 'forbidden' would confirm the identifier exists." operationId: getScheduledPaymentRecurrence parameters: - description: Series identifier. in: path name: recurrence_id required: true schema: description: Series identifier. examples: - 01a0d8fb-1a8b-7a10-b3c4-d5e6f7a8b9c0 format: uuid type: string 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-10T03:00:00Z" cancellationCutoff: "2027-08-10T02:59:59.999999Z" 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-10T03:00:00Z" cancellationCutoff: "2027-09-10T02:59:59.999999Z" 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-10T03:00:00Z" cancellationCutoff: "2027-10-10T02:59:59.999999Z" createdAt: "2026-09-25T14:32:10.123456Z" updatedAt: "2026-09-25T14:32:10.123456Z" attempts: [] schema: $ref: "#/components/schemas/RecurrenceDetailView" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: recurrence_id is not a UUID (PIX-0015). The response names the parameter; the series is never looked up. "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No series with that identifier exists for this organization (PIX-0760). A series belonging to another organization answers this too: the read is scoped by organization, and distinguishing the two cases would only help someone probing the identifier space. An identifier that is not a UUID is a DIFFERENT answer -- the binding contract refuses it with 400 before the query runs, and the response names the field." "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Read one recurring series tags: - Scheduled Payment Recurrences x-mint: href: /pt/reference/interfaces/pix-lerian/spi/get-recurring-series /scheduled-payment-recurrences/{recurrence_id}/cancel: post: description: "Stops the series at the payer's request and, with it, the occurrences already materialized for it that are still PENDING. It is the right call when the payer wants the standing payment to end; to drop a single date and keep the series running, cancel that occurrence through POST /v1/scheduled-payments/{schedule_id}/cancel instead. Nothing is released -- nothing was held. WHAT IT DOES NOT STOP. It moves only PENDING occurrences to CANCELLED. It does not change an occurrence in any other status (EXECUTING, DISPATCHED_OUTCOME_UNKNOWN, AWAITING_RETRY, SETTLED, FAILED or CANCELLED), and skippedOccurrences counts those. READING THE RESPONSE. cancelledOccurrences and skippedOccurrences PARTITION the occurrences the series had: every one of them is in exactly one count, which is what lets a client reconcile the figures against the pending occurrences it was displaying a moment earlier. They describe THIS request and are not properties of the series -- re-reading the series afterwards does not report them again. CANCELLING TWICE. The second request meets a series that is already CANCELLED and is refused with PIX-0765, whether or not the replay cache is reachable. The occurrences the first request stopped do not return to PENDING, so a repeat can never undo it. A COMPLETED SERIES CAN STILL BE CANCELLED. completed means every occurrence the series will ever have has been created -- not that they have been paid. A short series reaches that state while every one of its payments is still in the future, so this route accepts it and stops the pending occurrences. A series that really has finished paying is accepted too and truthfully reports zero cancelled." operationId: cancelScheduledPaymentRecurrence 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. 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 - description: Series identifier. in: path name: recurrence_id required: true schema: description: Series identifier. examples: - 01a0d8fb-1a8b-7a10-b3c4-d5e6f7a8b9c0 format: uuid type: string responses: "200": content: application/json: example: recurrenceId: 01a0d8fb-1a8b-7a10-b3c4-d5e6f7a8b9c0 status: CANCELLED cancelledOccurrences: 5 skippedOccurrences: 1 schema: $ref: "#/components/schemas/RecurrenceCancellationView" description: OK "400": content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Two shapes share this status, one per media type. application/problem+json: recurrence_id is not a UUID (PIX-0015). The response names the parameter; the series is never looked up. application/json is the legacy {code,title,message} envelope, 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: "No series with that identifier exists for this organization (PIX-0760). A series belonging to another organization answers this too: the write is scoped by the organization on the validated credential, so the row is never seen, and answering 'forbidden' would confirm the identifier exists somewhere." "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The series has already been cancelled (PIX-0765). Re-read it rather than retrying: this is the durable backstop behind the degrading idempotency posture, and it is also the answer a repeated cancellation gets. A COMPLETED series is NOT refused -- completed means every occurrence the series will ever have has been created, not that they have been paid, so its pending occurrences are still stoppable here." "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. "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Cancel a recurring series tags: - Scheduled Payment Recurrences x-mint: href: /pt/reference/interfaces/pix-lerian/spi/cancel-recurring-series /scheduled-payment-recurrences/{recurrence_id}/receipt: get: description: "Returns the proof of what the payer committed to when they created the series: when it was registered, the amount of each payment, the first payment date, the frequency, the number of payments when one was chosen, and the last payment date when the series has one. It is a DIFFERENT document from the single schedule's receipt and shares no field with it -- a series has no settlement date of its own and a single schedule has no frequency, so one shared schema would leave half the fields null on either side. paymentCount and lastPaymentDate are null on an indefinite series, where stating either would be a fabrication. cancellationCutoff is the deadline of the NEXT pending occurrence, because a cut-off belongs to a date and a series spans many; it is null when no occurrence is pending. The receipt carries no status and no history on purpose -- a document people save should not go stale the moment the series moves." operationId: getScheduledPaymentRecurrenceReceipt parameters: - description: Series identifier. in: path name: recurrence_id required: true schema: description: Series identifier. examples: - 01a0d8fb-1a8b-7a10-b3c4-d5e6f7a8b9c0 format: uuid type: string responses: "200": content: application/json: example: recurrenceId: 01a0d8fb-1a8b-7a10-b3c4-d5e6f7a8b9c0 scheduledAt: "2026-09-25T14:32:10.123456Z" amount: "150.00" firstPaymentDate: "2027-08-10" periodicity: MONTHLY paymentCount: 12 lastPaymentDate: "2028-07-10" payer: branch: "0001" accountNumber: "1234567" accountType: CACC ispb: "60746948" personType: NATURAL_PERSON taxId: "12345678909" name: Ana Souza payee: branch: "0001" accountNumber: "7654321" accountType: CACC ispb: "18236120" personType: NATURAL_PERSON taxId: "98765432100" name: Joao Pereira description: Aluguel metadata: contractRef: A-4471 cancellationCutoff: "2027-08-10T02:59:59.999999Z" schema: $ref: "#/components/schemas/RecurrenceReceiptView" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: recurrence_id is not a UUID (PIX-0015). The response names the parameter; the series is never looked up. "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No series with that identifier exists for this organization (PIX-0760). A series belonging to another organization answers this too: the read is scoped by organization, and distinguishing the two cases would only help someone probing the identifier space. An identifier that is not a UUID is a DIFFERENT answer -- the binding contract refuses it with 400 before the query runs, and the response names the field." "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Read a recurring series' receipt tags: - Scheduled Payment Recurrences x-mint: href: /pt/reference/interfaces/pix-lerian/spi/get-recurring-series-receipt components: schemas: AccountDetails: additionalProperties: false properties: branch: examples: - '0001' type: string number: examples: - '0007654321' type: string participant: examples: - '87654321' type: string type: examples: - CACC type: string required: - branch - number - participant - type type: object CreateRefundBody: additionalProperties: false properties: amount: description: Refund amount examples: - '100.00' type: string reason: description: Human-readable refund reason examples: - Estorno solicitado pelo pagador type: string reasonCode: description: pacs.004 RtrRsnInf reason code examples: - MD06 type: string enum: - MD06 - SL02 - FR01 - BE08 required: - amount - reasonCode - reason type: object CreateScheduledPaymentBody: additionalProperties: false properties: accountId: description: Payer account UUID. examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string amount: description: Amount to settle, in BRL with two decimals. The available balance is NOT touched at creation. 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, at most 140 characters -- the RmtInf ceiling. Stored and returned VERBATIM: markup is not interpreted, escaped or stripped, and escaping belongs to whoever renders it.' examples: - Aluguel de setembro type: string destination: $ref: '#/components/schemas/DestinationBody' description: The payee's account and owner. Required when initiationType is MANUAL; refused on DICT and QR_CODE (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. DICT reads the directory and requires payeeKey; MANUAL requires destination; QR_CODE requires emvPayload and resolves the payee from the key the BR Code carries. Each type reads only its own block: a payeeKey, destination or emvPayload sent on a type that does not read it is refused rather than ignored: well formed with 422 PIX-0751, a block with a missing field by request validation first (400 PIX-0002), one with an invalid field likewise (400 PIX-0003)." enum: - MANUAL - DICT - QR_CODE examples: - DICT type: string payeeKey: $ref: '#/components/schemas/PayeeKeyBody' description: The Pix key to resolve. Required when initiationType is DICT; refused on MANUAL and QR_CODE (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, so they are refused at creation rather than on the scheduled date. enum: - IPAY examples: - IPAY type: string scheduledDate: description: 'Civil settlement date in AAAA-MM-DD, evaluated in America/Sao_Paulo. Never an instant: a date that is still today in UTC can already be yesterday here. Non-business days are accepted -- Pix settles every day.' examples: - '2026-09-10' format: date type: string emvPayload: description: "The BR Code the payer scanned or pasted, sent WHOLE and unmodified. Required when initiationType is QR_CODE and rejected on any other type. It is stored verbatim and shown on the receipt: normalising or re-serialising it breaks the CRC-16 the standard embeds, and the receipt would then display a code that pays nobody. A due-date collection BR Code is accepted; the txId it carries is recorded with the schedule." examples: - 00020101021226900014br.gov.bcb.pix2568qrcodepix.exemplo.com.br/cobv/8f3a1c2d4e5b6f7a8b9c0d1e2f3a4b5c52040000530398654071500.005802BR5919Mercado Central LTDA6008BRASILIA62070503***6304A1B2 type: string required: - accountId - scheduledDate - amount - initiationType 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 DestinationAccountOutput: additionalProperties: false properties: branch: examples: - '0001' type: string number: examples: - '0007654321' type: string participant: examples: - '87654321' type: string type: examples: - CACC type: string required: - branch - number - participant - type type: object DestinationAccountReq: additionalProperties: false properties: branch: examples: - '0001' type: string number: examples: - '0007654321' type: string participant: examples: - '87654321' type: string type: examples: - CACC type: string required: - branch - number - participant - type type: object DestinationBody: additionalProperties: false properties: account: $ref: '#/components/schemas/DestinationAccountBody' owner: $ref: '#/components/schemas/DestinationOwnerBody' required: - account - owner type: object DestinationOutput: additionalProperties: false properties: account: $ref: '#/components/schemas/DestinationAccountOutput' key: examples: - '+5511999998888' type: string owner: $ref: '#/components/schemas/DestinationOwnerOutput' required: - account - owner 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 DestinationOwnerOutput: additionalProperties: false properties: document: examples: - '12345678901' type: string name: examples: - João da Silva type: string tradeName: examples: - Empresa Exemplo LTDA type: string type: examples: - NATURAL_PERSON type: string required: - document - name type: object DestinationOwnerReq: additionalProperties: false properties: document: examples: - '12345678901' type: string name: examples: - João da Silva type: string tradeName: examples: - Empresa Exemplo LTDA type: string required: - document - name type: object DestinationReq: additionalProperties: false properties: account: $ref: '#/components/schemas/DestinationAccountReq' owner: $ref: '#/components/schemas/DestinationOwnerReq' required: - account - owner 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 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 FeeChargeResponse: additionalProperties: false properties: applied: examples: - true type: boolean calculationType: examples: - FIXED type: string fees: items: $ref: '#/components/schemas/FeeEntryResponse' type: - array - 'null' netAmount: examples: - '98.50' type: string totalAmount: examples: - '1.50' type: string required: - applied type: object FeeEntryResponse: additionalProperties: false properties: amount: examples: - '1.50' type: string calculationType: examples: - FIXED type: string calculationValue: examples: - '1.50' type: string creditAccount: examples: - 019606a3-5d6e-7f80-1a2b-345678901bcd type: string feeLabel: examples: - PIX_TRANSFER_FEE type: string required: - feeLabel - amount type: object InitiateTransferBody: additionalProperties: false properties: description: description: Free-form payment description examples: - Pagamento de aluguel type: string destination: $ref: '#/components/schemas/DestinationReq' description: Manual destination (MANUAL initiation only) emv: description: EMV BR Code payload (QR_CODE initiation only) examples: - 00020101021126360014br.gov.bcb.pix0114+5511999998888520400005303986540510.005802BR5913JOAO DA SILVA6008BRASILIA62070503***63045B56 type: string endToEndId: description: "Optional caller-supplied 32-char BACEN endToEndId (E-prefixed). DICT and QR_CODE only: the key is looked up in DICT under it and the transfer is later sent under the same id; omit it to let SPI generate one, returned as endToEndId. Ignored for MANUAL." examples: - E12345678202605061030abcdef12345 type: string initiationType: description: Resolution strategy for the destination examples: - DICT type: string key: description: DICT key (DICT initiation only) examples: - '+5511999998888' type: string required: - initiationType type: object InitiateTransferOutput: additionalProperties: false properties: amount: examples: - '10.00' type: string createdAt: examples: - '2026-05-06T10:30:00Z' format: date-time type: string description: examples: - Pagamento de aluguel type: string destination: $ref: '#/components/schemas/DestinationOutput' emv: examples: - 00020101021126360014br.gov.bcb.pix0114+5511999998888520400005303986540510.005802BR5913JOAO DA SILVA6008BRASILIA62070503***63045B56 type: string endToEndId: examples: - E12345678202605061030abcdef12345 type: string description: "BACEN end-to-end id fixed at initiate for DICT and QR_CODE: the id the DICT lookup was made under, reused automatically by process as the transfer's id (do not send X-End-To-End-Id at process: it is refused for DICT and QR_CODE). Absent for MANUAL." expiresAt: examples: - '2026-05-06T10:35:00Z' format: date-time type: string id: examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string initiationType: examples: - DICT type: string qrCodeDetails: {} source: $ref: '#/components/schemas/SourceDestination' updatedAt: examples: - '2026-05-06T10:30:00Z' format: date-time type: string required: - id - initiationType - expiresAt - createdAt - updatedAt type: object LedgerInfo: additionalProperties: false properties: destinationOperationId: examples: - 019606a5-7f80-7182-3c4d-56789012cdf1 type: string revert: $ref: '#/components/schemas/LedgerRevertInfo' sourceOperationId: examples: - 019606a5-7f80-7182-3c4d-56789012cdf0 type: string transactionId: examples: - 019606a5-7f80-7182-3c4d-56789012cdef type: string type: object LedgerRevertInfo: additionalProperties: false properties: destinationOperationId: examples: - 019606a5-7f80-7182-3c4d-56789012cdf1 type: string sourceOperationId: examples: - 019606a5-7f80-7182-3c4d-56789012cdf0 type: string transactionId: examples: - 019606a5-7f80-7182-3c4d-56789012cdef type: string 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 LimitImpactItemView: additionalProperties: false properties: amount: type: string dateTotal: description: 'Total scheduled for that date. It travels with the row so the caller sees WHY a schedule is affected rather than only that it is: a small schedule sharing its date with a large one is unviable because of the other, and without this that reads as a bug.' type: string recurrenceId: type: string scheduleId: type: string scheduledDate: format: date type: string required: - scheduleId - scheduledDate - amount - dateTotal type: object LimitImpactPageView: additionalProperties: false properties: items: description: The affected schedules, soonest first. Empty when nothing is affected -- never null. items: $ref: '#/components/schemas/LimitImpactItemView' type: - array - 'null' nextCursor: type: string proposedLimit: description: Echoed back, so the page is self-describing when it is saved or forwarded. type: string required: - proposedLimit - items type: object OwnerDetails: additionalProperties: false properties: document: examples: - '12345678901' type: string name: examples: - João da Silva type: string tradeName: examples: - Empresa Exemplo LTDA type: string type: examples: - NATURAL_PERSON type: string required: - document - name 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 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 ProcessTransferBody: additionalProperties: false properties: amount: description: Confirmed amount (required unless locked by a static QR) examples: - '100.00' type: string initiationId: description: Initiation UUID returned by step 1 examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string required: - initiationId type: object RefundCashoutOutput: additionalProperties: false properties: accountId: examples: - 019606a0-1a2b-7c3d-8e4f-567890123abc type: string amount: examples: - '100.00' type: string createdAt: examples: - '2026-05-06T10:45:00Z' format: date-time type: string deletedAt: format: date-time type: string description: examples: - Estorno solicitado pelo pagador type: string id: examples: - 019606b1-3b4c-7d8e-9f01-234567890dee type: string ledger: $ref: '#/components/schemas/LedgerInfo' metadata: additionalProperties: {} type: object originalEndToEndId: examples: - E12345678202605061030abcdef12345 type: string reasonCode: examples: - MD06 type: string returnEndToEndId: examples: - D12345678202605061045fedcba54321 type: string status: examples: - COMPLETED type: string type: examples: - OUTBOUND type: string updatedAt: examples: - '2026-05-06T10:45:30Z' format: date-time type: string required: - id - originalEndToEndId - status - type - amount - reasonCode - createdAt - updatedAt type: object RefundsListOutput: additionalProperties: false properties: items: items: $ref: '#/components/schemas/RefundCashoutOutput' type: - array - 'null' next_cursor: examples: - eyJpZCI6IjAxOTYwNmIxLTNiNGMtN2Q4ZS05ZjAxLTIzNDU2Nzg5MGRlZSJ9 type: string prev_cursor: examples: - eyJpZCI6IjAxOTYwNmIxLTNiNGMtN2Q4ZS05ZjAxLTIzNDU2Nzg5MGRlZSJ9 type: string required: - items 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 ScheduledPaymentReceiptView: additionalProperties: false properties: amount: description: Amount to settle, in BRL. type: string cancellationCutoff: description: The deadline recorded for this schedule -- the one the payer was told, not one recomputed today. format: date-time type: string description: description: The payer's memo, exactly as stored. Not escaped here and not escaped on the way in. type: string payee: $ref: '#/components/schemas/ParticipantView' description: The payee as photographed at creation. payer: $ref: '#/components/schemas/ParticipantView' description: The payer as photographed at creation. scheduleId: description: Schedule identifier. type: string scheduledAt: description: When the schedule was registered. format: date-time type: string scheduledDate: description: Civil settlement date in AAAA-MM-DD. format: date type: string brCodePayload: description: The BR Code the payer submitted, stored and returned VERBATIM -- re-serialising it would break the CRC-16 the standard embeds, and the receipt would show a code that pays nobody. Present only when initiationType is QR_CODE. examples: - 00020101021226900014br.gov.bcb.pix2568qrcodepix.exemplo.com.br/cobv/8f3a1c2d4e5b6f7a8b9c0d1e2f3a4b5c52040000530398654071500.005802BR5919Mercado Central LTDA6008BRASILIA62070503***6304A1B2 type: string txId: description: Identifier of the due-date collection this schedule pays, as carried by the BR Code. Present only when initiationType is QR_CODE. examples: - COBV20260910MERCADOCENTRAL0001 type: string required: - scheduleId - scheduledDate - amount - scheduledAt - payer - payee - cancellationCutoff 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 ScheduledPaymentsPage: additionalProperties: false properties: items: description: The page, newest settlement date first. Never null. items: $ref: '#/components/schemas/ScheduledPaymentView' type: - array - 'null' nextCursor: description: Pass back as cursor for the following page. Absent on the last page -- its absence is how the listing ends, not an empty items array. type: string required: - items type: object ScheduledTotalsView: additionalProperties: false properties: accountId: type: string currency: examples: - BRL type: string nightPeriodScheduleCount: format: int64 type: integer nightPeriodTotal: description: 'The IN 512 art. 7 §7 slice: created inside the night period, settling the NEXT day, to a natural person distinct from the payer. This is NOT the general night period of art. 3 -- it is a separate rule with its own fixed shape. Present only when night_period_start was supplied.' type: string scheduleCount: description: How many schedules the total sums, so a zero total can be told apart from an absent one. format: int64 type: integer scheduledDate: format: date type: string total: description: Sum of every NON-TERMINAL schedule for that account on that date. Cancelled and failed schedules are excluded, because neither will move money. type: string required: - accountId - scheduledDate - total - currency - scheduleCount type: object SourceDestination: additionalProperties: false properties: account: $ref: '#/components/schemas/AccountDetails' key: examples: - '+5511999998888' type: string owner: $ref: '#/components/schemas/OwnerDetails' type: object TransferResponse: additionalProperties: false properties: accountId: examples: - 019606a0-1a2b-7c3d-8e4f-567890123abc type: string aliasId: type: string alreadyRefundedAmount: description: Cross-mechanism settled and reserved refund amount. Returned only for INBOUND transfers. examples: - '60.00' type: string amount: examples: - '100.00' type: string createdAt: examples: - '2026-05-06T10:30:00Z' format: date-time type: string currency: examples: - BRL type: string deletedAt: format: date-time type: string description: examples: - Pagamento de aluguel type: string destination: $ref: '#/components/schemas/SourceDestination' endToEndId: examples: - E12345678202605061030abcdef12345 type: string feeCharge: $ref: '#/components/schemas/FeeChargeResponse' id: examples: - 019606a2-4c5d-7e8f-90a1-345678901bcd type: string initiatedAt: examples: - '2026-05-06T10:30:00Z' format: date-time type: string initiationType: examples: - DICT type: string ledger: $ref: '#/components/schemas/LedgerInfo' metadata: additionalProperties: {} type: object paymentType: examples: - PIX type: string purpose: examples: - IACT type: string remainingRefundableAmount: description: Amount minus alreadyRefundedAmount. Returned only for INBOUND transfers and can be negative. examples: - '40.00' type: string source: $ref: '#/components/schemas/SourceDestination' status: examples: - COMPLETED type: string type: examples: - OUTBOUND type: string updatedAt: examples: - '2026-05-06T10:30:05Z' format: date-time type: string urgency: examples: - HIGH type: string required: - id - endToEndId - status - type - amount - createdAt - updatedAt type: object TransfersListOutput: additionalProperties: false properties: items: items: $ref: '#/components/schemas/TransferResponse' type: - array - 'null' next_cursor: examples: - eyJpZCI6IjAxOTYwNmEyLTRjNWQtN2U4Zi05MGExLTM0NTY3ODkwMTJjZCJ9 type: string prev_cursor: examples: - eyJpZCI6IjAxOTYwNmEyLTRjNWQtN2U4Zi05MGExLTM0NTY3ODkwMTJjY30= type: string required: - items 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 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 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 RecurrenceCancellationView: additionalProperties: false properties: cancelledOccurrences: description: How many occurrences this request moved to CANCELLED. It counts ONLY the ones that were still PENDING, and it is the row count of the write itself rather than a census taken beforehand. examples: - 5 format: int64 type: integer recurrenceId: description: The series that was stopped. examples: - 01a0d8fb-1a8b-7a10-b3c4-d5e6f7a8b9c0 type: string skippedOccurrences: description: How many materialized occurrences this request did not change, because they were not PENDING. Together with cancelledOccurrences it accounts for every occurrence the series had. examples: - 1 format: int64 type: integer status: description: The series' status after the operation. Always CANCELLED on a 200 -- a series that could not be stopped answers PIX-0765 instead of reporting an unchanged status. enum: - ACTIVE - COMPLETED - CANCELLED examples: - CANCELLED type: string required: - recurrenceId - status - cancelledOccurrences - skippedOccurrences 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 RecurrenceReceiptView: additionalProperties: false properties: amount: description: Amount of every occurrence, in BRL. examples: - "150.00" type: string cancellationCutoff: description: Deadline to cancel the NEXT pending occurrence. A cut-off belongs to a date and a series spans many, so this is the one field here that is not a property of the series itself. Null when no occurrence is pending -- there is then nothing left to cancel in the materialized window. format: date-time type: - string - "null" description: description: The payer's memo, exactly as stored. examples: - Aluguel type: string firstPaymentDate: description: Civil date of the first payment. examples: - "2027-08-10" format: date type: string lastPaymentDate: description: Civil date of the final payment, when the series has one. Null on an indefinite series. examples: - "2028-07-10" format: date type: - string - "null" metadata: additionalProperties: {} description: The annotation the caller sent at creation, returned verbatim. examples: - contractRef: A-4471 type: object payee: $ref: "#/components/schemas/ParticipantView" description: The payee as photographed at creation. payer: $ref: "#/components/schemas/ParticipantView" description: The payer as photographed at creation. paymentCount: description: How many payments the series has in all, when the payer terminated it by count. Null otherwise -- an indefinite series has no total, and reporting one would be a fabrication. examples: - 12 format: int64 type: - integer - "null" periodicity: description: How often the series pays. enum: - WEEKLY - MONTHLY examples: - MONTHLY type: string recurrenceId: description: Series identifier. examples: - 01a0d8fb-1a8b-7a10-b3c4-d5e6f7a8b9c0 type: string scheduledAt: description: When the series was registered. format: date-time type: string required: - recurrenceId - scheduledAt - amount - firstPaymentDate - periodicity - paymentCount - lastPaymentDate - payer - payee - cancellationCutoff 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 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 RecurrenceView: 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 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: - id - accountId - amount - currency - status - initiationType - purpose - recurrence - source - destination - materializedThrough - lastPaymentDate - createdAt - updatedAt type: object RecurrencesPage: additionalProperties: false properties: items: description: The page, newest first. Never null. items: $ref: "#/components/schemas/RecurrenceView" type: array nextCursor: description: Pass back as cursor for the following page. Absent on the last page -- its absence is how the listing ends, not an empty items array. type: string required: - items type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http