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.3.0 servers: - url: https://api.example.com/spi/v1 description: Replace the example host with the URL provided during environment onboarding. security: - BearerAuth: [] tags: - description: Create, list, and retrieve Pix refunds. name: Refunds - name: Scheduled Payments description: Register, list, retrieve, and cancel scheduled Pix payments. - description: Initiate, process, list, and retrieve outbound Pix transfers. name: Transfers - description: Register, list, retrieve, and cancel recurring series of scheduled Pix payments. name: Scheduled Payment Recurrences - description: Hold the funds of a received Pix in a cautionary block (MED 2.0), return them to the payer, or give them back to the account holder. name: Balance Locks paths: /refunds: get: description: Returns a cursor-paginated page of refunds for the calling account. operationId: listRefunds x-mint: href: /en/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' application/json: example: code: PIX-0001 title: Missing Headers in Request message: Your request is missing one or more required header params. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" 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). Route-guard refusals (PIX-0001) answer in the legacy {code,title,message} envelope over application/json, NOT problem+json. '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: /en/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' application/json: example: code: PIX-0001 title: Missing Headers in Request message: Your request is missing one or more required header params. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: Missing, duplicated, or malformed X-Account-Id or refund UUID (PIX-0001, PIX-0015, PIX-0017, PIX-0403). Route-guard refusals (PIX-0001) answer in the legacy {code,title,message} envelope over application/json, NOT problem+json. '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](/en/reference/interfaces/pix-lerian/spi/get-refund) returns it. operationId: unblockRefund x-mint: href: /en/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. An identical resend within 1 hour returns the original response, status included, with X-Idempotency-Replayed: true. Reusing the 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 is held by a request still running or whose receipt could not be stored, or was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: 'The first request under this X-Idempotency is still running (with Retry-After: 1), or the key was 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: /en/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: /en/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: /en/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: /en/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. An identical resend within 1 hour returns the original response, status included, with X-Idempotency-Replayed: true. Reusing the key with a divergent method, URL or body is PIX-0031 @ 412." in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string requestBody: content: application/json: 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. Route-guard refusals (PIX-0010) answer in the legacy {code,title,message} envelope too." '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: The payer account does not resolve to an account visible to the caller (PIX-0750). '409': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: "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 201 response 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 is held by a request still running or whose receipt could not be stored, or was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: "Refused under this X-Idempotency (PIX-0031): the first request under it is still running (with Retry-After: 1), its receipt could not be stored and the key is held for the hour, or the request differs from the first (method, URL, body or identity header). An earlier request under this key may already have executed. Legacy {code,title,message} envelope, NOT problem+json." '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-0758 the date is today and it is already 08:00 or later in America/Sao_Paulo -- no window would attempt the order; schedule a later date or send an immediate Pix; 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; PIX-0328 the payer's ledger account is blocked -- unblock it in the ledger and send again; PIX-0332 the payer's ledger account is closed and can send nothing." 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 "502": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "An upstream service 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 or refused this platform's credential, or the receiver behind it gave no answer on the charge -- 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. PIX-0705: the ledger could not read the payer account (unreachable, or an answer that does not say the account is absent). PIX-0702: the CRM gave no verdict on the payer's holder (unreachable, refused this platform's credential, or a failure that does not say the holder is absent or malformed)." "415": content: application/json: example: code: PIX-0016 title: Unsupported Media Type message: "The request body must be sent with Content-Type: application/json." schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: The non-empty request body is missing an accepted JSON Content-Type (PIX-0016), answered in the legacy {code,title,message} envelope over application/json, NOT problem+json. 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: /en/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: /en/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. An identical resend within 1 hour returns the original response, status included, with X-Idempotency-Replayed: true. Reusing the key with a divergent method, URL or body is PIX-0031 @ 412." in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - 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 is held by a request still running or whose receipt could not be stored, or was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: "Refused under this X-Idempotency (PIX-0031): the first request under it is still running (with Retry-After: 1), its receipt could not be stored and the key is held for the hour, or the request differs from the first (method, URL, body or identity header). An earlier request under this key may already have executed. Legacy {code,title,message} envelope, NOT problem+json." '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: /en/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: /en/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' application/json: example: code: PIX-0001 title: Missing Headers in Request message: Your request is missing one or more required header params. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" 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). Route-guard refusals (PIX-0001) answer in the legacy {code,title,message} envelope over application/json, NOT problem+json. '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: /en/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. An identical resend within 1 hour returns the original response, status included, with X-Idempotency-Replayed: true. Reusing the key with a divergent method, URL or body is PIX-0031 @ 412." in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - 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. Route-guard refusals (PIX-0001, PIX-0010) answer in the legacy {code,title,message} envelope too. '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header is held by a request still running or whose receipt could not be stored, or was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: "Refused under this X-Idempotency (PIX-0031): the first request under it is still running (with Retry-After: 1), its receipt could not be stored and the key is held for the hour, or the request differs from the first (method, URL, body or identity header). An earlier request under this key may already have executed. Legacy {code,title,message} envelope, NOT problem+json." '415': content: application/json: example: code: PIX-0016 title: Unsupported Media Type message: "The request body must be sent with Content-Type: application/json." schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: The non-empty request body is missing an accepted JSON Content-Type (PIX-0016), answered in the legacy {code,title,message} envelope over application/json, NOT problem+json. '422': content: application/problem+json: 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); PIX-0701 also answers a dynamic QR whose receiver gave no answer on the charge, and the call can be tried again. 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, once the reversal of the debit is recorded. When the reversal is not recorded, the call answers 500.' operationId: processTransfer x-mint: href: /en/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. An identical resend within 1 hour returns the original response, status included, with X-Idempotency-Replayed: true. Reusing the key with a divergent method, URL or body is PIX-0031 @ 412." in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - 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. Route-guard refusals (PIX-0001, PIX-0010) answer in the legacy {code,title,message} envelope too. '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 is held by a request still running or whose receipt could not be stored, or was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: "Refused under this X-Idempotency (PIX-0031): the first request under it is still running (with Retry-After: 1), its receipt could not be stored and the key is held for the hour, or the request differs from the first (method, URL, body or identity header). An earlier request under this key may already have executed. Legacy {code,title,message} envelope, NOT problem+json." '415': content: application/json: example: code: PIX-0016 title: Unsupported Media Type message: "The request body must be sent with Content-Type: application/json." schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: The non-empty request body is missing an accepted JSON Content-Type (PIX-0016), answered in the legacy {code,title,message} envelope over application/json, NOT problem+json. '422': content: application/problem+json: 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 (PIX-0321), the debit has insufficient funds (PIX-0323), the ledger refused the debit for another reason (PIX-0332) or because another write moved the balance, which a new attempt can clear (PIX-0333), the ledger account/balance cannot be used (PIX-0328, PIX-0329), or more than one ledger fee package matches the transaction (PIX-0331); none of these debited anything. The ledger answer does not show the transfer amount moved to the rail (a different, unreadable or missing rail leg), so the order was not sent and the debit revert was attempted -- the transfer ends REJECTED with ledger.revert when it completes; when it does not, it ends FAILED, if the state write fails it stays PENDING with no ledger.revert. Do not start a new initiation until the transfer shows ledger.revert (PIX-0330). PIX-0334: the provider or the rail rejected the payment after the debit, and the debit was reversed; the order will not settle, and a new attempt needs a new end-to-end id." '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: /en/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' application/json: example: code: PIX-0001 title: Missing Headers in Request message: Your request is missing one or more required header params. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: Missing, duplicated, or malformed X-Account-Id or transfer UUID (PIX-0001, PIX-0015, PIX-0017, PIX-0300). Route-guard refusals (PIX-0001) answer in the legacy {code,title,message} envelope over application/json, NOT problem+json. '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](/en/reference/interfaces/pix-lerian/spi/get-transfer) returns it. operationId: unblockTransfer x-mint: href: /en/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. An identical resend within 1 hour returns the original response, status included, with X-Idempotency-Replayed: true. Reusing the 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 is held by a request still running or whose receipt could not be stored, or was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: 'The first request under this X-Idempotency is still running (with Retry-After: 1), or the key was 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 replays the original 201 response, with X-Idempotency-Replayed: true, instead of creating a second refund, including when the request timed out while the provider was answering. After a 5xx or a 409 PIX-0406, the same key answers the refund that the first attempt created, in its current state, with 201 and without X-Idempotency-Replayed, as long as that refund is not FAILED: the refund can still be PROCESSING with its debit, so read it with GET to see its outcome. A resend that keeps answering 412 PIX-0031 with Retry-After: 1 is still in flight. The same key with a different transfer, amount, reasonCode or reason answers 412 PIX-0031. Once the refund is FAILED and no replay record is left, the key is free and a retry under it creates a new refund." operationId: createRefund x-mint: href: /en/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. An identical resend within 1 hour returns the original response, status included, with X-Idempotency-Replayed: true. Reusing the key with a divergent method, URL or body is PIX-0031 @ 412." in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - 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. Route-guard refusals (PIX-0001, PIX-0010) answer in the legacy {code,title,message} envelope too. '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 is held by a request still running or whose receipt could not be stored, or was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0031 title: Precondition Failed status: 412 detail: The X-Idempotency header is held by a request still running or whose receipt could not be stored, or was already used with a different request. code: PIX-0031 schema: $ref: "#/components/schemas/Detail" description: "Two refusals share this status. The refund row's, problem+json: the X-Idempotency key already holds a refund for a different transfer, amount, reasonCode or reason (PIX-0031). The replay gate's, which answers first, follows. Refused under this X-Idempotency (PIX-0031): the first request under it is still running (with Retry-After: 1), its receipt could not be stored and the key is held for the hour, or the request differs from the first (method, URL, body or identity header). An earlier request under this key may already have executed. Legacy {code,title,message} envelope, NOT problem+json." '415': content: application/json: example: code: PIX-0016 title: Unsupported Media Type message: "The request body must be sent with Content-Type: application/json." schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: The non-empty request body is missing an accepted JSON Content-Type (PIX-0016), answered in the legacy {code,title,message} envelope over application/json, NOT problem+json. '422': content: application/problem+json: 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 or balance cannot be used, or the rail refused the refund (PIX-0013, PIX-0401, PIX-0402, PIX-0328, PIX-0329). PIX-0323: the holder who received the Pix no longer has the funds; nothing is debited, the refund ends FAILED and its X-Idempotency is freed. PIX-0331: more than one ledger fee package matches the refund. PIX-0332: the ledger account is closed or its status forbids sending. PIX-0013 and PIX-0330: the rail refused the refund, or the ledger answer does not show the refund amount moved to the rail, so the refund was not sent; Pix Lerian reverts the debit, and the refund ends FAILED once the reversal is recorded. If the reversal 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); PIX-0405 includes a ledger refusal after an automatic retry (the debit may stand). 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: /en/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, an identical resend returns the original response, status included, with X-Idempotency-Replayed: true, and reusing the key with a divergent method, URL or body is PIX-0031 @ 412.' in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string requestBody: content: application/json: examples: dict: description: "Pix Lerian resolves the payee from the directory at creation and again before every occurrence settles. Send payeeKey only: a destination alongside it is refused -- 422 PIX-0751 when well formed, 400 PIX-0002 when a field of it is missing, 400 PIX-0003 when one is invalid." summary: DICT -- monthly rent to a Pix key, twelve payments value: accountId: 0195948b-bf02-7e4f-9a1b-2c3d4e5f6a7b amount: "150.00" currency: BRL initiationType: DICT purpose: IPAY payeeKey: keyType: EMAIL keyValue: joao.pereira@example.com description: Aluguel metadata: contractRef: A-4471 recurrence: periodicity: MONTHLY firstPaymentDate: "2027-08-10" paymentCount: 12 manual: description: "The caller supplies the payee's account and owner, and the person type is derived from the document. Send destination only: a payeeKey alongside it is refused -- 422 PIX-0751 when well formed, 400 PIX-0002 when a field of it is missing, 400 PIX-0003 when one is invalid." summary: MANUAL -- weekly payment to bank details, until an end date value: accountId: 0195948b-bf02-7e4f-9a1b-2c3d4e5f6a7b amount: "80.00" currency: BRL initiationType: MANUAL purpose: IPAY destination: account: branch: "0001" number: "98765" participant: "18236120" type: CACC owner: document: "12345678000195" name: Escola Exemplo LTDA description: Aulas semanais recurrence: periodicity: WEEKLY firstPaymentDate: "2027-08-02" endDate: "2027-10-25" schema: $ref: "#/components/schemas/CreateRecurrenceBody" required: true responses: "201": content: application/json: example: id: 01a0d8fb-1a8b-7a10-b3c4-d5e6f7a8b9c0 accountId: 0195948b-bf02-7e4f-9a1b-2c3d4e5f6a7b amount: "150.00" currency: BRL status: ACTIVE initiationType: DICT purpose: IPAY description: Aluguel metadata: contractRef: A-4471 recurrence: periodicity: MONTHLY firstPaymentDate: "2027-08-10" paymentCount: 12 endDate: null indefinite: false referenceDayOfMonth: 10 source: branch: "0001" accountNumber: "1234567" accountType: CACC ispb: "60746948" personType: NATURAL_PERSON taxId: "12345678909" name: Ana Souza destination: branch: "0001" accountNumber: "7654321" accountType: CACC ispb: "18236120" personType: NATURAL_PERSON taxId: "98765432100" name: Joao Pereira payeeKey: keyType: EMAIL keyValue: joao.pereira@example.com materializedThrough: "2027-10-10" lastPaymentDate: "2028-07-10" createdAt: "2026-09-25T14:32:10.123456Z" updatedAt: "2026-09-25T14:32:10.123456Z" occurrences: - id: 01a0d8fb-1a8c-7b21-8c3d-4e5f6a7b8c91 accountId: 0195948b-bf02-7e4f-9a1b-2c3d4e5f6a7b scheduledDate: "2027-08-10" amount: "150.00" currency: BRL initiationType: DICT purpose: IPAY description: Aluguel source: branch: "0001" accountNumber: "1234567" accountType: CACC ispb: "60746948" personType: NATURAL_PERSON taxId: "12345678909" name: Ana Souza destination: branch: "0001" accountNumber: "7654321" accountType: CACC ispb: "18236120" personType: NATURAL_PERSON taxId: "98765432100" name: Joao Pereira status: PENDING firstWindowOpensAt: "2027-08-10T00:00:00-03:00" cancellationCutoff: "2027-08-09T23:59:59.999999-03:00" createdAt: "2026-09-25T14:32:10.123456Z" updatedAt: "2026-09-25T14:32:10.123456Z" attempts: [] - id: 01a0d8fb-1a8d-7b22-8c3d-4e5f6a7b8c92 accountId: 0195948b-bf02-7e4f-9a1b-2c3d4e5f6a7b scheduledDate: "2027-09-10" amount: "150.00" currency: BRL initiationType: DICT purpose: IPAY description: Aluguel source: branch: "0001" accountNumber: "1234567" accountType: CACC ispb: "60746948" personType: NATURAL_PERSON taxId: "12345678909" name: Ana Souza destination: branch: "0001" accountNumber: "7654321" accountType: CACC ispb: "18236120" personType: NATURAL_PERSON taxId: "98765432100" name: Joao Pereira status: PENDING firstWindowOpensAt: "2027-09-10T00:00:00-03:00" cancellationCutoff: "2027-09-09T23:59:59.999999-03:00" createdAt: "2026-09-25T14:32:10.123456Z" updatedAt: "2026-09-25T14:32:10.123456Z" attempts: [] - id: 01a0d8fb-1a8e-7b23-8c3d-4e5f6a7b8c93 accountId: 0195948b-bf02-7e4f-9a1b-2c3d4e5f6a7b scheduledDate: "2027-10-10" amount: "150.00" currency: BRL initiationType: DICT purpose: IPAY description: Aluguel source: branch: "0001" accountNumber: "1234567" accountType: CACC ispb: "60746948" personType: NATURAL_PERSON taxId: "12345678909" name: Ana Souza destination: branch: "0001" accountNumber: "7654321" accountType: CACC ispb: "18236120" personType: NATURAL_PERSON taxId: "98765432100" name: Joao Pereira status: PENDING firstWindowOpensAt: "2027-10-10T00:00:00-03:00" cancellationCutoff: "2027-10-09T23:59:59.999999-03:00" createdAt: "2026-09-25T14:32:10.123456Z" updatedAt: "2026-09-25T14:32:10.123456Z" attempts: [] schema: $ref: "#/components/schemas/RecurrenceDetailView" description: Created "400": content: application/json: 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. Route-guard refusals (PIX-0010) answer in the legacy {code,title,message} envelope too." "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: The payer account does not resolve to an account visible to the caller (PIX-0750). "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: The payee key is registered to the PAYER's own account (PIX-0124), and a payer cannot schedule payments to their own key. Nothing was created; do not retry. "412": content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header is held by a request still running or whose receipt could not be stored, or was already used with a different request. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: "Refused under this X-Idempotency (PIX-0031): the first request under it is still running (with Retry-After: 1), its receipt could not be stored and the key is held for the hour, or the request differs from the first (method, URL, body or identity header). An earlier request under this key may already have executed. Legacy {code,title,message} envelope, NOT problem+json." "422": content: application/problem+json: examples: foreignBlock: summary: PIX-0751 -- a block another initiation type reads is present; remove it value: type: https://errors.lerian.studio/v1/PIX-0751 title: Unprocessable Entity status: 422 detail: "The payload does not fit the declared initiation type: a field that type requires is missing or invalid, or a field that only another initiation type reads is present." errors: - message: "payeeKey is not allowed when initiationType is MANUAL: the payee is the destination sent" location: payeeKey code: PIX-0751 missingBlock: summary: PIX-0751 with no errors -- the block the initiation type requires is absent (supply it), or initiationType is QR_CODE, which a series cannot be initiated from. The same bare body also answers a zero amount. value: type: https://errors.lerian.studio/v1/PIX-0751 title: Unprocessable Entity status: 422 detail: "The payload does not fit the declared initiation type: a field that type requires is missing or invalid, or a field that only another initiation type reads is present." code: PIX-0751 schema: $ref: "#/components/schemas/Detail" description: "The request is well formed and cannot be accepted. Read the code, not the status: PIX-0761 no termination criterion was supplied -- add exactly one; PIX-0762 more than one was supplied -- remove the others; PIX-0764 the first payment date is past, beyond this participant's scheduling horizon, or the end date precedes it; PIX-0758 the first payment is today and it is already 08:00 or later in America/Sao_Paulo -- start the series on a later date; PIX-0751 the payload lacks the block its initiationType requires -- supply it; this refusal carries no field detail -- or carries the other type's block -- a destination on DICT, a payeeKey on MANUAL -- in which case errors names that field, and it must be removed -- or declares QR_CODE, which a series cannot be initiated from; PIX-0755 the directory has no entry for the payee key; PIX-0766 the participant's materialization horizon is not usable, which is a configuration fault rather than a fault in this request; PIX-0328 the payer's ledger account is blocked -- unblock it in the ledger and send again; PIX-0332 the payer's ledger account is closed and can send nothing." "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "502": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "DICT Hub could not resolve the payee key (PIX-0700): unreachable, a server error, or any answer that says nothing about the key. PIX-0705: the ledger could not read the payer account (unreachable, or an answer that does not say the account is absent). PIX-0702: the CRM gave no verdict on the payer's holder (unreachable, refused this platform's credential, or a failure that does not say the holder is absent or malformed). The series was NOT created and nothing was charged. Retrying is safe." "503": content: application/json: example: code: PIX-0032 title: Idempotency Unavailable message: The request was not processed because the idempotency store is unavailable. Please retry. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: Replay cache unavailable on this fail-closed route, so the mutation was refused rather than executed without replay protection (PIX-0032). Legacy {code,title,message} envelope, NOT problem+json. default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error "415": content: application/json: example: code: PIX-0016 title: Unsupported Media Type message: "The request body must be sent with Content-Type: application/json." schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: The non-empty request body is missing an accepted JSON Content-Type (PIX-0016), answered in the legacy {code,title,message} envelope over application/json, NOT problem+json. summary: Create a recurring series tags: - Scheduled Payment Recurrences x-mint: href: /en/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: /en/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. An identical resend within 1 hour returns the original response, status included, with X-Idempotency-Replayed: true. Reusing the key with a divergent method, URL or body is PIX-0031 @ 412." in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - 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 is held by a request still running or whose receipt could not be stored, or was already used with a different request. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: "Refused under this X-Idempotency (PIX-0031): the first request under it is still running (with Retry-After: 1), its receipt could not be stored and the key is held for the hour, or the request differs from the first (method, URL, body or identity header). An earlier request under this key may already have executed. Legacy {code,title,message} envelope, NOT problem+json." "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: /en/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: /en/reference/interfaces/pix-lerian/spi/get-recurring-series-receipt /balance-locks: get: description: |- Lists the cautionary blocks of your institution, oldest update first. Filter by `origin_system`, `status` (repeatable), `updated_before` and `external_ref`. The list uses cursor pagination: pass `next_cursor` as `cursor` to read the next page; `next_cursor` is `null` on the last page. `limit` defaults to 20 and is at most 100. A non-integer `limit` is refused with `400` (`PIX-0020`). The `status` of a lock tells which operation applies. A `PENDING` lock can be settled, released or closed. A `SETTLING` lock waits for the confirmation of its settlement, and one whose devolution failed can also be closed. An `AWAITING_CREDIT` lock waits for the parked credit of its Pix and can only be released. operationId: listBalanceLocks parameters: - description: Scope of the calling consumer (e.g. med-infraction). Omit to list across every origin_system. explode: false in: query name: origin_system schema: description: Scope of the calling consumer (e.g. med-infraction). Omit to list across every origin_system. type: string - description: "Filter by status (repeatable): PENDING, SETTLING, RELEASED, SETTLED, AWAITING_CREDIT" explode: true in: query name: status schema: description: "Filter by status (repeatable): PENDING, SETTLING, RELEASED, SETTLED, AWAITING_CREDIT" examples: - - PENDING items: type: string type: - array - "null" - description: Only balance locks with updated_at before this RFC 3339 timestamp explode: false in: query name: updated_before schema: description: Only balance locks with updated_at before this RFC 3339 timestamp type: string - description: Restrict to a single grouping operation explode: false in: query name: external_ref schema: description: Restrict to a single grouping operation 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 - description: Opaque cursor returned by the previous page explode: false in: query name: cursor schema: description: Opaque cursor returned by the previous page type: string responses: "200": content: application/json: example: items: - lock_id: 01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60 origin_system: med-infraction external_ref: med-2026-000123 end_to_end_id: E12345678202610271032k7Qm2Xp9Ld4 status: PENDING requested_amount: "150.75" effective_amount: "100.26" settled_amount: null payment_type: null pix_end_to_end_id: null settling_at: null surplus_midaz_tx_id: null created_at: "2026-10-27T10:41:07Z" updated_at: "2026-10-27T10:41:07Z" - lock_id: 01a17cf5-983a-7d13-a4c8-2e9f51b06d37 origin_system: med-infraction external_ref: med-2026-000123 end_to_end_id: E12345678202610271032k7Qm2Xp9Ld4 status: PENDING requested_amount: "50.49" effective_amount: "50.49" settled_amount: null payment_type: null pix_end_to_end_id: null settling_at: null surplus_midaz_tx_id: null created_at: "2026-10-27T10:43:52Z" updated_at: "2026-10-27T10:43:52Z" next_cursor: null schema: $ref: "#/components/schemas/ListBalanceLocksOutput" description: OK "400": content: application/problem+json: example: 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. code: PIX-0003 schema: $ref: "#/components/schemas/Detail" description: An unknown status, an updated_before that is not RFC 3339 (PIX-0003), or a non-integer limit (PIX-0020). "500": content: application/json: example: code: PIX-0000 title: Internal Server Error message: The server encountered an unexpected error. Please try again later. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" 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 cautionary blocks tags: - Balance Locks x-mint: href: /en/reference/interfaces/pix-lerian/spi/list-cautionary-blocks post: description: |- Places a cautionary block (MED 2.0) on the funds of a Pix that your institution received. Pix Lerian creates a pending ledger transaction that moves the funds from the available balance of the credited account to the blocking account. The amount held is the smaller of the requested amount and the available balance: `effective_amount` is what was held, and it can be lower than `requested_amount`. The blocking account of your institution must be configured. An inbound Pix transfer with this `end_to_end_id` must be completed, with available balance on the credited account, or have its ledger credit parked. For a Pix whose credit is parked, the lock holds at once (`PENDING`) when the ledger already lists that credit. Otherwise the lock is stored as `AWAITING_CREDIT`: nothing is held yet, and the credit of the Pix holds the funds before it completes the transfer. `request_ref` identifies the creation. A replay with the same payload returns the existing lock with `201`; the same `request_ref` with another payload is refused with `409` (`PIX-0012`). Another hold on the same transaction needs another `request_ref`. A retry after a failed create (`502`) reuses the amount that the failed attempt computed, so a hold that the attempt placed becomes this lock. A retry whose earlier hold no longer stands is refused with `422` (`PIX-0013`). Next, return the funds to the payer with [Settle a cautionary block](/en/reference/interfaces/pix-lerian/spi/settle-a-cautionary-block) or [Settle every cautionary block of a Pix](/en/reference/interfaces/pix-lerian/spi/settle-every-cautionary-block-of-a-pix), or give them back to the account holder with [Release a cautionary block](/en/reference/interfaces/pix-lerian/spi/release-a-cautionary-block-to-the-account-holder). operationId: createBalanceLock 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. An identical resend within 1 hour returns the original response, status included, with X-Idempotency-Replayed: true. Reusing the key with a divergent method, URL or body is PIX-0031 @ 412." in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string requestBody: content: application/json: examples: hold: summary: Hold the funds of a suspicious received Pix value: request_ref: med-2026-000123-hold-1 external_ref: med-2026-000123 origin_system: med-infraction end_to_end_id: E12345678202610271032k7Qm2Xp9Ld4 amount: "150.75" asset: BRL schema: $ref: "#/components/schemas/CreateBalanceLockBody" required: true responses: "201": content: application/json: example: lock_id: 01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60 midaz_tx_id: 01a17cf3-133d-7a52-8e19-0c4b6d2f7a91 status: PENDING requested_amount: "150.75" effective_amount: "100.26" created_at: "2026-10-27T10:41:07Z" schema: $ref: "#/components/schemas/CreateBalanceLockResponse" description: The hold, created now or replayed by request_ref. "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-0003 title: Bad Request status: 400 detail: Your request contains one or more fields with an invalid data type. code: PIX-0003 schema: $ref: "#/components/schemas/Detail" description: Missing or invalid body fields, or a body that is not valid JSON (PIX-0002, PIX-0003, PIX-0010). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. Route-guard refusals (PIX-0010) answer in the legacy {code,title,message} envelope too. "409": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0012 title: Conflict status: 409 detail: The entity already exists or conflicts with an existing resource. code: PIX-0012 schema: $ref: "#/components/schemas/Detail" description: request_ref was already used with a different payload (PIX-0012). "412": content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header is held by a request still running or whose receipt could not be stored, or was already used with a different request. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: "Refused under this X-Idempotency (PIX-0031): the first request under it is still running (with Retry-After: 1), its receipt could not be stored and the key is held for the hour, or the request differs from the first (method, URL, body or identity header). An earlier request under this key may already have executed. Legacy {code,title,message} envelope, NOT problem+json." "415": content: application/json: example: code: PIX-0016 title: Unsupported Media Type message: "The request body must be sent with Content-Type: application/json." schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: The non-empty request body is missing an accepted JSON Content-Type (PIX-0016), answered in the legacy {code,title,message} envelope over application/json, NOT problem+json. "422": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0013 title: Unprocessable Entity status: 422 detail: The operation could not be processed due to a business rule violation. code: PIX-0013 schema: $ref: "#/components/schemas/Detail" description: No INBOUND transfer matches end_to_end_id that is completed or has its ledger credit parked, the locks waiting for that parked credit already sum to its amount, the credited account has no available balance to hold, the ledger refused the hold for another business reason, or the hold an earlier attempt placed under this request_ref no longer stands (PIX-0013); the ledger account is blocked or has no balance for the asset (PIX-0328, PIX-0329); the participant's blocking account is not configured (PIX-0650); an account has no ledger alias (PIX-0655). "500": content: application/json: example: code: PIX-0000 title: Internal Server Error message: The server encountered an unexpected error. Please try again later. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" 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-0652 title: Bad Gateway status: 502 detail: The server could not complete the request. Please try again later. code: PIX-0652 schema: $ref: "#/components/schemas/Detail" description: "The ledger call failed, another write moved the balance while the ledger placed the hold, the create could not tell whether a hold already stands under request_ref, or storing an AWAITING_CREDIT lock failed: retry with the same request_ref (PIX-0652). With a detail naming overrides.allowFeeSkip, the ledger that holds the blocking account does not enable it, so nothing was held: retry with the same request_ref once it is enabled." default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Create a cautionary block tags: - Balance Locks x-mint: href: /en/reference/interfaces/pix-lerian/spi/create-a-cautionary-block /balance-locks/audit: get: description: |- Returns the audit records of the manual interventions on one lock (`lock_id`) or on one group settlement (`refund_ref`), newest first. Send exactly one of the two. A record exists for every close and surplus return, for every release that moved funds out of the blocking account, and for every other release or settlement confirmation that carried an attribution header (`X-Actor-Id`, `X-Override-Reason` or `X-Override-Ticket`). Each record carries the actor declared in `X-Actor-Id` (Pix Lerian does not check it against the access token), the reason, the ticket and the request ID. An ID with no record returns an empty `entries` list, not `404`. operationId: listBalanceLockAudit parameters: - description: Per-block override lookup (mutually exclusive with refund_ref) explode: false in: query name: lock_id schema: description: Per-block override lookup (mutually exclusive with refund_ref) type: string - description: Group override lookup (mutually exclusive with lock_id) explode: false in: query name: refund_ref schema: description: Group override lookup (mutually exclusive with lock_id) type: string responses: "200": content: application/json: example: entries: - id: 01a17e29-5544-7b96-8d2a-3f0e71c9a4b8 lock_id: 01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60 action: CLOSE actor: backoffice.ops@example.com reason: manual devolution paid by Pix ticket: MED-4821 request_id: 01a17e29-5302-7c0a-b5e1-94d2f6a83c17 correlation_id: med-2026-000123 created_at: "2026-10-27T16:20:00Z" schema: $ref: "#/components/schemas/ListBalanceLockAuditResponse" description: OK "400": content: application/problem+json: example: 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. code: PIX-0003 schema: $ref: "#/components/schemas/Detail" description: Neither or both of lock_id and refund_ref (PIX-0003), or a lock_id that is not a UUID (PIX-0020). "500": content: application/json: example: code: PIX-0000 title: Internal Server Error message: The server encountered an unexpected error. Please try again later. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" 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 cautionary block audit records tags: - Balance Locks x-mint: href: /en/reference/interfaces/pix-lerian/spi/list-cautionary-block-audit-records /balance-locks/settle: post: description: |- Returns to the payer, in one devolution, the funds that the locks of one received Pix hold, and moves every lock to `SETTLING`. With `pix_refund`, Pix Lerian sends one return (pacs.004) of the original transaction. With `pix_manual`, it pays one Pix (pacs.008) from the blocking account to the bank account that you give. Pix Lerian derives `settle_amount` from the locks and the ceiling: you do not send it. Every lock in `lock_ids` must be `PENDING` (a lock still `AWAITING_CREDIT` is refused with `409`, `PIX-0012`), belong to your institution and share the same `end_to_end_id` and `external_ref`. `original_amount` must not exceed the received transaction: [Quote the amount left to settle](/en/reference/interfaces/pix-lerian/spi/quote-the-amount-left-to-settle) tells what is left. For a lock opened for a MED infraction (`origin_system` `med-infraction`), use [Settle refund](/en/reference/interfaces/pix-lerian/dict/settle-refund) instead: DICT holds MED state that this route cannot see. The group settles all or nothing: a group with a lock whose surplus was already returned is refused with `409` (`PIX-0656`) before any lock is reserved. The call is idempotent by `refund_ref`, and a retry must send the same `lock_ids`: a `refund_ref` already bound to a lock outside `lock_ids` is refused with `400` (`PIX-0003`). A dispatch that fails without proof that the devolution was not sent (a timeout, a `5xx`) answers success, and every lock stays `SETTLING` until the outcome is confirmed. A `pix_manual` surplus is returned when the settlement is confirmed, not by this call. When the rail reports the outcome of the devolution, send it with [Confirm a group settlement](/en/reference/interfaces/pix-lerian/spi/confirm-a-group-settlement). operationId: createGroupSettle 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. An identical resend within 1 hour returns the original response, status included, with X-Idempotency-Replayed: true. Reusing the key with a divergent method, URL or body is PIX-0031 @ 412." in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string requestBody: content: application/json: examples: pixManual: summary: "pixManual: one Pix from the blocking account to the payer's account" value: refund_ref: med-2026-000123-group-devolution lock_ids: - 01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60 - 01a17cf5-983a-7d13-a4c8-2e9f51b06d37 original_amount: "150.75" original_end_to_end_id: E12345678202610271032k7Qm2Xp9Ld4 pix_manual: ispb: "12345678" branch: "0001" account: "1234567" account_type: CC document: "12345678909" asset: BRL description: MED devolution to the payer pixRefund: summary: "pixRefund: one pacs.004 returning both locks" value: refund_ref: med-2026-000123-group-devolution lock_ids: - 01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60 - 01a17cf5-983a-7d13-a4c8-2e9f51b06d37 original_amount: "150.75" original_end_to_end_id: E12345678202610271032k7Qm2Xp9Ld4 pix_refund: return_reason_code: FR01 asset: BRL schema: $ref: "#/components/schemas/CreateGroupSettleBody" required: true responses: "200": content: application/json: example: refund_ref: med-2026-000123-group-devolution payment_type: PIX_REFUND status: SETTLING original_amount: "150.75" already_settled: "0" settle_amount: "150.75" surplus_amount: "0" lock_ids: - 01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60 - 01a17cf5-983a-7d13-a4c8-2e9f51b06d37 initiated_at: "2026-10-27T14:05:12Z" schema: $ref: "#/components/schemas/CreateGroupSettleResponse" 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: example: 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. code: PIX-0003 schema: $ref: "#/components/schemas/Detail" description: Missing or invalid body fields, a body that is not valid JSON, a lock_ids set with an unknown, duplicated or mixed lock, an original_end_to_end_id other than the locks' own, or a refund_ref bound to a lock outside lock_ids or replayed with a different request (PIX-0002, PIX-0003, PIX-0010). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. Route-guard refusals (PIX-0010) answer in the legacy {code,title,message} envelope too. "409": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0012 title: Conflict status: 409 detail: The entity already exists or conflicts with an existing resource. code: PIX-0012 schema: $ref: "#/components/schemas/Detail" description: "A lock is not PENDING or is bound to another refund_ref, has an unlock in progress, a pixRefund group holds a lock whose hold a pixManual settle already committed, or a pixManual group holds a lock whose hold was made in a blocking account other than the one configured now (the detail names it: unlock that lock) (PIX-0012); a reset (a FAILED confirm or the settle's own compensation) left part of the group SETTLING under this refund_ref: a FAILED confirm resets the rest, then retry, but once the rest is closed with /close this refund_ref keeps answering it, so settle the reset locks under a new one (PIX-0653); or a lock already returned its surplus (PIX-0656)." "412": content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header is held by a request still running or whose receipt could not be stored, or was already used with a different request. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: "Refused under this X-Idempotency (PIX-0031): the first request under it is still running (with Retry-After: 1), its receipt could not be stored and the key is held for the hour, or the request differs from the first (method, URL, body or identity header). An earlier request under this key may already have executed. Legacy {code,title,message} envelope, NOT problem+json." "415": content: application/json: example: code: PIX-0016 title: Unsupported Media Type message: "The request body must be sent with Content-Type: application/json." schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: The non-empty request body is missing an accepted JSON Content-Type (PIX-0016), answered in the legacy {code,title,message} envelope over application/json, NOT problem+json. "422": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0654 title: Unprocessable Entity status: 422 detail: There is nothing left to settle for this block. code: PIX-0654 schema: $ref: "#/components/schemas/Detail" description: "`original_amount` exceeds the received transaction, or that transaction is not found (`PIX-0013`). Nothing is left to settle (`PIX-0654`). A ledger account is blocked (`PIX-0328`), or a `pix_refund` debit leg holds no ledger balance (`PIX-0329`). The ledger refused the debit because the account is closed or its status forbids sending (`PIX-0332`), or because more than one fee package matches it (`PIX-0331`): nothing was debited. The ledger answer does not show the settled amount moved to the rail, so the order was not sent and Pix Lerian attempted to revert the debit (`PIX-0330`). A `pix_manual` settlement has no blocking account configured (`PIX-0650`) or an account has no ledger alias (`PIX-0655`)." "500": content: application/json: example: code: PIX-0000 title: Internal Server Error message: The server encountered an unexpected error. Please try again later. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" 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-0652 title: Bad Gateway status: 502 detail: The server could not complete the request. Please try again later. code: PIX-0652 schema: $ref: "#/components/schemas/Detail" description: "A ledger call failed, including a ledger refusal after an automatic retry, so the debit can stand and a lock can stay `SETTLING` (`PIX-0652`). When the detail names `overrides.allowFeeSkip` on a `pix_manual` settlement, the ledger refused the transfer out of the blocking account: settle again with `pix_manual` once the setting is on, or release the lock." default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Settle every cautionary block of a Pix tags: - Balance Locks x-mint: href: /en/reference/interfaces/pix-lerian/spi/settle-every-cautionary-block-of-a-pix /balance-locks/settle-quote: get: description: |- Returns, for the received Pix identified by its original `end_to_end_id`, the `original_amount`, the amount `already_settled` by both devolution mechanisms (`pix_manual` locks that are `SETTLING` or `SETTLED`, and outbound refunds that are `PROCESSING` or `COMPLETED`), and `available_to_settle`, their difference. The difference can be zero or negative. The call is read-only: it holds nothing, so the value can be stale against a concurrent close. The settle and close operations enforce the ceiling themselves. Call it before you settle, to size the devolution: a settle whose `original_amount` minus `already_settled` is zero or less is refused with `422` (`PIX-0654`). operationId: getSettleQuote parameters: - description: Canonical original end-to-end id of the INBOUND transfer to quote the settle ceiling for explode: false in: query name: end_to_end_id required: true schema: description: Canonical original end-to-end id of the INBOUND transfer to quote the settle ceiling for examples: - E12345678202610271032k7Qm2Xp9Ld4 type: string responses: "200": content: application/json: example: original_amount: "150.75" already_settled: "100.26" available_to_settle: "50.49" schema: $ref: "#/components/schemas/SettleQuoteResponse" description: OK "400": content: application/problem+json: example: 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. code: PIX-0003 schema: $ref: "#/components/schemas/Detail" description: end_to_end_id is missing or is not a valid end-to-end or return id (PIX-0003). "422": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0013 title: Unprocessable Entity status: 422 detail: The operation could not be processed due to a business rule violation. code: PIX-0013 schema: $ref: "#/components/schemas/Detail" description: No INBOUND transfer matches end_to_end_id (PIX-0013). "500": content: application/json: example: code: PIX-0000 title: Internal Server Error message: The server encountered an unexpected error. Please try again later. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" 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: Quote the amount left to settle tags: - Balance Locks x-mint: href: /en/reference/interfaces/pix-lerian/spi/quote-the-amount-left-to-settle /balance-locks/settle/confirm: post: description: |- Applies the outcome of a group devolution to every lock of the group: `SUCCESS` settles them, and `FAILED` returns them to `PENDING`. Send `SUCCESS` with the `end_to_end_id` of the devolution: the D-prefixed return ID of a `pix_refund` group, or the E-prefixed payment ID of a `pix_manual` group. Any other ID is refused with `409` (`PIX-0012`) and nothing changes. Omit `result` to read the current state of the group without changing it. A retryable `409` (`PIX-0653`) means that the debit of the devolution, or its outcome on the rail, is not confirmed yet: nothing changes, so repeat the call later. A group whose surplus was already returned is refused with `409` (`PIX-0656`) and stays `SETTLING`. A `pix_manual` surplus is returned once, when every lock is `SETTLED`. If that return fails, the group stays `SETTLED` and the answer is `200` without `surplus_midaz_tx_id`; this does not prove that the surplus stayed blocked, because a ledger timeout can have moved it. Check the ledger, then use [Return a settlement surplus to the account holder](/en/reference/interfaces/pix-lerian/spi/return-a-settlement-surplus-to-the-account-holder). `X-Actor-Id`, `X-Override-Reason` and `X-Override-Ticket` are optional. Sending any of them records the confirmation in the audit trail. For a lock opened for a MED infraction (`origin_system` `med-infraction`), use [Confirm settle refund](/en/reference/interfaces/pix-lerian/dict/confirm-settle-refund) instead: DICT holds MED state that this route cannot see. operationId: confirmGroupSettle 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. An identical resend within 1 hour returns the original response, status included, with X-Idempotency-Replayed: true. Reusing the key with a divergent method, URL or body is PIX-0031 @ 412." in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Who is acting. Declared by the caller; not verified against the access token in: header name: X-Actor-Id schema: description: Who is acting. Declared by the caller; not verified against the access token examples: - backoffice.ops@example.com type: string - description: Why the caller is acting in: header name: X-Override-Reason schema: description: Why the caller is acting examples: - manual devolution paid by Pix type: string - description: Ticket reference in: header name: X-Override-Ticket schema: description: Ticket reference examples: - MED-4821 type: string - description: Correlation id in: header name: X-Correlation-Id schema: description: Correlation id examples: - med-2026-000123 type: string - description: Request id in: header name: X-Request-Id schema: description: Request id examples: - 01a17e29-5302-7c0a-b5e1-94d2f6a83c17 type: string requestBody: content: application/json: examples: failed: summary: "FAILED: the rail rejected the devolution, every lock goes back to PENDING" value: refund_ref: med-2026-000123-group-devolution result: FAILED poll: summary: "No result: read the group's current state" value: refund_ref: med-2026-000123-group-devolution success: summary: "SUCCESS: the rail paid the devolution" value: refund_ref: med-2026-000123-group-devolution result: SUCCESS end_to_end_id: D87654321202610271405g7Bv3Nc9Jw2 schema: $ref: "#/components/schemas/ConfirmGroupSettleBody" required: true responses: "200": content: application/json: example: refund_ref: med-2026-000123-group-devolution payment_type: PIX_REFUND status: SETTLED pix_end_to_end_id: D87654321202610271405g7Bv3Nc9Jw2 original_amount: "150.75" already_settled: "0" settle_amount: "150.75" surplus_amount: "0" settled_at: "2026-10-27T14:06:03Z" schema: $ref: "#/components/schemas/ConfirmGroupSettleResponse" 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: example: 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. code: PIX-0003 schema: $ref: "#/components/schemas/Detail" description: A duplicated or padded attribution header (PIX-0001), a missing refund_ref (PIX-0002), a result other than SUCCESS or FAILED, SUCCESS without end_to_end_id, an invalid end_to_end_id or an oversized attribution header (PIX-0003), or a body that is not valid JSON (PIX-0010). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. Route-guard refusals (PIX-0001, PIX-0010) answer in the legacy {code,title,message} envelope too. "404": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0011 title: Not Found status: 404 detail: No entity was found for the given ID. Please make sure to use the correct ID. code: PIX-0011 schema: $ref: "#/components/schemas/Detail" description: No lock carries this refund_ref, including a group a FAILED confirm already reset (PIX-0011). "409": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0653 title: Conflict status: 409 detail: The balance lock's settlement is not final yet; retry once it is. code: PIX-0653 schema: $ref: "#/components/schemas/Detail" description: The group is not SETTLING, FAILED was reported over a devolution the rail already paid, SUCCESS named an end_to_end_id other than the group's devolution, SUCCESS over a lock whose transfer back to the holder a close the holder paid has in progress, or a concurrent update won (PIX-0012); FAILED while the devolution is still in flight, or either result while the group's debit is unconfirmed, retryable (PIX-0653); FAILED over a group that already returned its surplus (PIX-0656). "412": content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header is held by a request still running or whose receipt could not be stored, or was already used with a different request. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: "Refused under this X-Idempotency (PIX-0031): the first request under it is still running (with Retry-After: 1), its receipt could not be stored and the key is held for the hour, or the request differs from the first (method, URL, body or identity header). An earlier request under this key may already have executed. Legacy {code,title,message} envelope, NOT problem+json." "415": content: application/json: example: code: PIX-0016 title: Unsupported Media Type message: "The request body must be sent with Content-Type: application/json." schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: The non-empty request body is missing an accepted JSON Content-Type (PIX-0016), answered in the legacy {code,title,message} envelope over application/json, NOT problem+json. "422": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0328 title: Unprocessable Entity status: 422 detail: The ledger account is blocked and cannot be used for the requested operation. code: PIX-0328 schema: $ref: "#/components/schemas/Detail" description: FAILED on a pixRefund group whose re-hold, or SUCCESS whose cancel of a left-behind re-hold, finds a blocked ledger account (PIX-0328), a closed one or one whose status forbids sending, which refused the hold (PIX-0332), an account without a ledger alias (PIX-0655), or no blocking account configured for the participant (PIX-0650). "500": content: application/json: example: code: PIX-0000 title: Internal Server Error message: The server encountered an unexpected error. Please try again later. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" 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). With attribution headers, the confirm may already have taken effect when the audit record fails. "502": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0652 title: Bad Gateway status: 502 detail: The server could not complete the request. Please try again later. code: PIX-0652 schema: $ref: "#/components/schemas/Detail" description: "SUCCESS whose ledger search for, or cancel of, a block's left-behind re-hold failed: every block stays SETTLING, repeat it (PIX-0652). FAILED on a pixRefund group whose re-hold failed in the ledger, or was refused after an automatic retry so it may stand: the blocks not yet reset stay SETTLING, repeat it (PIX-0652). With a detail naming overrides.allowFeeSkip, repeat it once the setting is enabled on the ledger that holds the blocking account." default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Confirm a group settlement tags: - Balance Locks x-mint: href: /en/reference/interfaces/pix-lerian/spi/confirm-a-group-settlement /balance-locks/{lock_id}/close: post: description: |- Marks a `PENDING` or `SETTLING` lock `SETTLED`, with `closed_manually` `true`, for a devolution that your institution paid by Pix through Pix Lerian outside the automatic settlement. Pix Lerian sends no Pix. `settled_amount` records what was paid and counts in what was already returned of the received transaction, so a later settle of another lock is capped to what is left. `X-Actor-Id` and `X-Override-Reason` are required. `payment_type` is required when you close a `PENDING` lock. `end_to_end_id` must name a completed Pix of your institution paid to the payer of the received transaction: a devolution of the received Pix itself or, on a `pix_manual` lock, a Pix to the payer's account. Any other Pix, or one that is in flight, rejected or failed, is refused with `422` (`PIX-0013`). A lock still `AWAITING_CREDIT` is refused with `409` (`PIX-0012`). When nothing was paid to the payer, or the payer was repaid through another channel, release the lock instead. Never settle a lock that was already repaid: the devolution would be paid twice. A failed ledger search or cancel answers `502` (`PIX-0652`): repeat the call. Pix Lerian records every close in the audit trail. A `pix_manual` lock closed with a surplus returns it with [Return a settlement surplus to the account holder](/en/reference/interfaces/pix-lerian/spi/return-a-settlement-surplus-to-the-account-holder). For a lock opened for a MED infraction (`origin_system` `med-infraction`), use [Blocks close refund](/en/reference/interfaces/pix-lerian/dict/blocks-close-refund) instead: DICT holds MED state that this route cannot see. operationId: closeBalanceLock 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. An identical resend within 1 hour returns the original response, status included, with X-Idempotency-Replayed: true. Reusing the key with a divergent method, URL or body is PIX-0031 @ 412." in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Balance lock UUID in: path name: lock_id required: true schema: description: Balance lock UUID examples: - 01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60 type: string - description: Who is acting. Declared by the caller; not verified against the access token in: header name: X-Actor-Id required: true schema: description: Who is acting. Declared by the caller; not verified against the access token examples: - backoffice.ops@example.com type: string - description: Why the caller is acting in: header name: X-Override-Reason required: true schema: description: Why the caller is acting examples: - manual devolution paid by Pix type: string - description: Ticket reference in: header name: X-Override-Ticket schema: description: Ticket reference examples: - MED-4821 type: string - description: Correlation id in: header name: X-Correlation-Id schema: description: Correlation id examples: - med-2026-000123 type: string - description: Request id in: header name: X-Request-Id schema: description: Request id examples: - 01a17e29-5302-7c0a-b5e1-94d2f6a83c17 type: string requestBody: content: application/json: examples: close: summary: Close a SETTLING lock whose devolution failed, the payer repaid by a manual Pix value: end_to_end_id: D87654321202610271405r4Tn8Wq2Kx6 notes: devolution failed on the rail, payer repaid by a manual Pix, ticket MED-4821 closePartial: summary: Close a SETTLING pixRefund lock whose devolution failed, the payer repaid part of it by a manual Pix value: end_to_end_id: D87654321202610271405r4Tn8Wq2Kx6 settled_amount: "60.13" notes: devolution failed on the rail, payer repaid 60.13 of 100.26 by a manual Pix, ticket MED-4821 schema: $ref: "#/components/schemas/CloseBalanceLockBody" required: true responses: "200": content: application/json: example: lock_id: 01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60 status: SETTLED pix_end_to_end_id: D87654321202610271405r4Tn8Wq2Kx6 closed_manually: true closed_at: "2026-10-27T16:20:00Z" schema: $ref: "#/components/schemas/CloseBalanceLockResponse" 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: example: 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. code: PIX-0003 schema: $ref: "#/components/schemas/Detail" description: A duplicated or padded attribution header (PIX-0001); a missing end_to_end_id (PIX-0002); a missing X-Actor-Id or X-Override-Reason, an oversized attribution header, payment_type missing on a PENDING lock or different from a SETTLING lock's own, settled_amount above a PENDING lock's effective_amount or other than what a SETTLING lock's settle reserved, or another invalid field (PIX-0003); a body that is not valid JSON (PIX-0010); a lock_id that is not a UUID (PIX-0015). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. Route-guard refusals (PIX-0001, PIX-0010) answer in the legacy {code,title,message} envelope too. "404": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0011 title: Not Found status: 404 detail: No entity was found for the given ID. Please make sure to use the correct ID. code: PIX-0011 schema: $ref: "#/components/schemas/Detail" description: No lock exists for lock_id (PIX-0011). "409": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0012 title: Conflict status: 409 detail: The entity already exists or conflicts with an existing resource. code: PIX-0012 schema: $ref: "#/components/schemas/Detail" description: "The lock is `SETTLED`, `RELEASED` or `AWAITING_CREDIT`, a transfer back to the holder is in progress for it, a `SETTLING` lock has a devolution still in flight or already paid (confirm its settlement first), or the hold of the lock cannot be committed (`PIX-0012`). A surplus of the payment already left the blocking account (`PIX-0656`)." "412": content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header is held by a request still running or whose receipt could not be stored, or was already used with a different request. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: "Refused under this X-Idempotency (PIX-0031): the first request under it is still running (with Retry-After: 1), its receipt could not be stored and the key is held for the hour, or the request differs from the first (method, URL, body or identity header). An earlier request under this key may already have executed. Legacy {code,title,message} envelope, NOT problem+json." "415": content: application/json: example: code: PIX-0016 title: Unsupported Media Type message: "The request body must be sent with Content-Type: application/json." schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: The non-empty request body is missing an accepted JSON Content-Type (PIX-0016), answered in the legacy {code,title,message} envelope over application/json, NOT problem+json. "422": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0013 title: Unprocessable Entity status: 422 detail: The operation could not be processed due to a business rule violation. code: PIX-0013 schema: $ref: "#/components/schemas/Detail" description: "`PIX-0013`: the amounts already returned plus `settled_amount` exceed the received transaction, the transaction is not found, `end_to_end_id` does not name a completed Pix of your institution to the payer, or its amount does not cover `settled_amount`; the hold is untouched. `PIX-0328`: a ledger account is blocked. `PIX-0332`: the transfer back to the holder was refused because the account is closed or its status forbids receiving. `PIX-0655`: an account has no ledger alias." "500": content: application/json: example: code: PIX-0000 title: Internal Server Error message: The server encountered an unexpected error. Please try again later. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" 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). The close writes its audit record in the same transaction, so a failure records neither: retry the close, which finds a transfer back to the holder already made rather than making another." "502": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0652 title: Bad Gateway status: 502 detail: The server could not complete the request. Please try again later. code: PIX-0652 schema: $ref: "#/components/schemas/Detail" description: "The ledger search for the lock's settle compensation re-holds failed, or the ledger did not confirm such a re-hold or a pixRefund lock's hold cancelled, or a pixManual lock's hold committed or cancelled (PIX-0652). Or the transfer of a committed hold back to the holder failed (a refusal after an automatic retry included) or has an unknown outcome: the lock keeps that transfer in progress; retry the close, which never transfers twice (PIX-0652). With a detail naming overrides.allowFeeSkip, the ledger that holds the blocking account does not enable it, so nothing moved: retry once it is enabled." default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Close a cautionary block after a manual return tags: - Balance Locks x-mint: href: /en/reference/interfaces/pix-lerian/spi/close-a-cautionary-block-after-a-manual-return /balance-locks/{lock_id}/return-surplus: post: description: |- Moves a `pix_manual` surplus from the blocking account back to the account holder. Use it when a `pix_manual` settlement paid the payer less than the lock held and the surplus did not go back to the holder: the lock was closed manually, or the surplus return of a settlement confirmation answered without `surplus_midaz_tx_id`. That answer does not prove that the surplus stayed blocked, because a ledger timeout can have moved it. Before you call, search the ledger for a transaction whose metadata carries the `lock_id` and an `origin` of `balance-lock-surplus`, `balance-lock-group-surplus` or `balance-lock-surplus-recovery`. Call only when none exists. The lock must be `SETTLED`: a `SETTLING` lock with a surplus is refused with `409` (`PIX-0653`), so confirm the settlement first. `X-Actor-Id` and `X-Override-Reason` are required. The call is idempotent: a lock with no surplus, or whose surplus was already returned, answers `200` with `surplus_amount` `0`. After a `5xx` that returns no `surplus_midaz_tx_id`, the surplus can have moved: check the ledger before you retry. For a group settlement, call it once for each `lock_id`. Pix Lerian records every call in the audit trail. operationId: returnSurplus 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. An identical resend within 1 hour returns the original response, status included, with X-Idempotency-Replayed: true. Reusing the key with a divergent method, URL or body is PIX-0031 @ 412." in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Balance lock UUID in: path name: lock_id required: true schema: description: Balance lock UUID examples: - 01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60 type: string - description: Who is acting. Declared by the caller; not verified against the access token in: header name: X-Actor-Id required: true schema: description: Who is acting. Declared by the caller; not verified against the access token examples: - backoffice.ops@example.com type: string - description: Why the caller is acting in: header name: X-Override-Reason required: true schema: description: Why the caller is acting examples: - manual devolution paid by Pix type: string - description: Ticket reference in: header name: X-Override-Ticket schema: description: Ticket reference examples: - MED-4821 type: string - description: Correlation id in: header name: X-Correlation-Id schema: description: Correlation id examples: - med-2026-000123 type: string - description: Request id in: header name: X-Request-Id schema: description: Request id examples: - 01a17e29-5302-7c0a-b5e1-94d2f6a83c17 type: string responses: "200": content: application/json: example: lock_id: 01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60 surplus_amount: "0" surplus_midaz_tx_id: 01a17dae-b16e-7f28-9a03-6b1c4d8e2f75 returned_at: "2026-10-27T15:02:41Z" schema: $ref: "#/components/schemas/ReturnSurplusResponse" 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: example: 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. code: PIX-0003 schema: $ref: "#/components/schemas/Detail" description: A duplicated or padded attribution header (PIX-0001), a missing X-Actor-Id or X-Override-Reason or an oversized attribution header (PIX-0003), or a lock_id that is not a UUID (PIX-0015). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. Route-guard refusals (PIX-0001) answer in the legacy {code,title,message} envelope too. "404": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0011 title: Not Found status: 404 detail: No entity was found for the given ID. Please make sure to use the correct ID. code: PIX-0011 schema: $ref: "#/components/schemas/Detail" description: No lock exists for lock_id (PIX-0011). "409": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0653 title: Conflict status: 409 detail: The balance lock's settlement is not final yet; retry once it is. code: PIX-0653 schema: $ref: "#/components/schemas/Detail" description: The lock has a surplus but is not SETTLED yet (PIX-0653). "412": content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header is held by a request still running or whose receipt could not be stored, or was already used with a different request. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: "Refused under this X-Idempotency (PIX-0031): the first request under it is still running (with Retry-After: 1), its receipt could not be stored and the key is held for the hour, or the request differs from the first (method, URL, body or identity header). An earlier request under this key may already have executed. Legacy {code,title,message} envelope, NOT problem+json." "422": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0655 title: Unprocessable Entity status: 422 detail: An account required for this operation has no resolvable alias in the ledger. code: PIX-0655 schema: $ref: "#/components/schemas/Detail" description: A ledger account is blocked (PIX-0328), the surplus return was refused because the account is closed or its status forbids receiving (PIX-0332), or an account has no ledger alias (PIX-0655). "500": content: application/json: example: code: PIX-0000 title: Internal Server Error message: The server encountered an unexpected error. Please try again later. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" 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). The surplus may already be returned when the audit record fails: list the lock first; a retry is a no-op only when surplus_midaz_tx_id is recorded, otherwise reconcile the ledger before retrying." "502": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0652 title: Bad Gateway status: 502 detail: The server could not complete the request. Please try again later. code: PIX-0652 schema: $ref: "#/components/schemas/Detail" description: "A ledger call failed, a refusal after an automatic retry included (PIX-0652). The transfer may still have been applied when the ledger's answer was lost: without a surplus_midaz_tx_id, reconcile before retrying. With a detail naming overrides.allowFeeSkip, the ledger that holds the blocking account does not enable it, so nothing moved: retry once it is enabled." default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Return a settlement surplus to the account holder tags: - Balance Locks x-mint: href: /en/reference/interfaces/pix-lerian/spi/return-a-settlement-surplus-to-the-account-holder /balance-locks/{lock_id}/settle: post: description: |- Starts the return of the funds of one lock to the payer and moves the lock to `SETTLING`. With `pix_refund`, Pix Lerian cancels the ledger hold and sends a return (pacs.004) of the original transaction. With `pix_manual`, it commits the hold to the blocking account and pays one Pix (pacs.008) from there to the bank account that you give. To return every lock of the transaction in one devolution, use [Settle every cautionary block of a Pix](/en/reference/interfaces/pix-lerian/spi/settle-every-cautionary-block-of-a-pix). The lock must be `PENDING` (`AWAITING_CREDIT` is refused with `409`, `PIX-0012`). `original_amount` is the amount of the received transaction: a higher amount, or a transaction that is not found, is refused with `422` (`PIX-0013`). The amount settled is the smallest of the requested amount, what is left to settle and the `effective_amount` of the lock. The call is idempotent by `refund_ref`: a `refund_ref` already bound to other locks is refused with `400` (`PIX-0003`). A lock whose surplus was already returned is refused with `409` (`PIX-0656`). A dispatch that fails without proof that the devolution was not sent (a timeout, a `5xx`) answers success, and the lock stays `SETTLING` until the outcome is confirmed. A `pix_manual` surplus is returned when the settlement is confirmed, not by this call. When the outcome is known, call [Confirm a cautionary block settlement](/en/reference/interfaces/pix-lerian/spi/confirm-a-cautionary-block-settlement). For a lock opened for a MED infraction (`origin_system` `med-infraction`), use [Settle refund](/en/reference/interfaces/pix-lerian/dict/settle-refund) instead: DICT holds MED state that this route cannot see. operationId: createSettle 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. An identical resend within 1 hour returns the original response, status included, with X-Idempotency-Replayed: true. Reusing the key with a divergent method, URL or body is PIX-0031 @ 412." in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Balance lock UUID in: path name: lock_id required: true schema: description: Balance lock UUID examples: - 01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60 type: string requestBody: content: application/json: examples: pixManual: summary: "pixManual: pay part of it to the payer's account (pacs.008); the rest is surplus" value: refund_ref: med-2026-000123-devolution original_amount: "150.75" pix_manual: ispb: "12345678" branch: "0001" account: "1234567" account_type: CC document: "12345678909" amount: "80.13" asset: BRL description: MED devolution to the payer pixRefund: summary: "pixRefund: return the held amount as a devolution (pacs.004)" value: refund_ref: med-2026-000123-devolution original_amount: "150.75" pix_refund: return_reason_code: FR01 amount: "100.26" asset: BRL schema: $ref: "#/components/schemas/CreateSettleBody" required: true responses: "200": content: application/json: example: lock_id: 01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60 payment_type: PIX_MANUAL status: SETTLING original_amount: "150.75" requested_amount: "80.13" already_settled: "0" settle_amount: "80.13" surplus_amount: "20.13" initiated_at: "2026-10-27T14:05:12Z" schema: $ref: "#/components/schemas/CreateSettleResponse" 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: example: 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. code: PIX-0003 schema: $ref: "#/components/schemas/Detail" description: Missing or invalid body fields, neither or both of pix_refund and pix_manual, a body that is not valid JSON, a lock_id that is not a UUID, or a refund_ref bound to other locks (PIX-0002, PIX-0003, PIX-0010, PIX-0015). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. Route-guard refusals (PIX-0010) answer in the legacy {code,title,message} envelope too. "404": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0011 title: Not Found status: 404 detail: No entity was found for the given ID. Please make sure to use the correct ID. code: PIX-0011 schema: $ref: "#/components/schemas/Detail" description: No lock exists for lock_id (PIX-0011). "409": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0653 title: Conflict status: 409 detail: The balance lock's settlement is not final yet; retry once it is. code: PIX-0653 schema: $ref: "#/components/schemas/Detail" description: The lock is RELEASED, SETTLED or AWAITING_CREDIT, has an unlock in progress, a pixRefund over a hold a pixManual settle already committed, a pixManual settle over a hold made in a blocking account other than the one configured now (unlock the lock), or a concurrent settle won (PIX-0012); the lock is SETTLING (PIX-0653); the lock already returned its surplus (PIX-0656). "412": content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header is held by a request still running or whose receipt could not be stored, or was already used with a different request. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: "Refused under this X-Idempotency (PIX-0031): the first request under it is still running (with Retry-After: 1), its receipt could not be stored and the key is held for the hour, or the request differs from the first (method, URL, body or identity header). An earlier request under this key may already have executed. Legacy {code,title,message} envelope, NOT problem+json." "415": content: application/json: example: code: PIX-0016 title: Unsupported Media Type message: "The request body must be sent with Content-Type: application/json." schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: The non-empty request body is missing an accepted JSON Content-Type (PIX-0016), answered in the legacy {code,title,message} envelope over application/json, NOT problem+json. "422": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0654 title: Unprocessable Entity status: 422 detail: There is nothing left to settle for this block. code: PIX-0654 schema: $ref: "#/components/schemas/Detail" description: "`original_amount` exceeds the received transaction, or that transaction is not found (`PIX-0013`). Nothing is left to settle (`PIX-0654`). A ledger account is blocked (`PIX-0328`), or a `pix_refund` debit leg holds no ledger balance (`PIX-0329`). The ledger refused the debit because the account is closed or its status forbids sending (`PIX-0332`), or because more than one fee package matches it (`PIX-0331`): nothing was debited. The ledger answer does not show the settled amount moved to the rail, so the order was not sent and Pix Lerian attempted to revert the debit (`PIX-0330`). A `pix_manual` settlement has no blocking account configured (`PIX-0650`) or an account has no ledger alias (`PIX-0655`)." "500": content: application/json: example: code: PIX-0000 title: Internal Server Error message: The server encountered an unexpected error. Please try again later. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" 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-0652 title: Bad Gateway status: 502 detail: The server could not complete the request. Please try again later. code: PIX-0652 schema: $ref: "#/components/schemas/Detail" description: "A ledger call failed, including a ledger refusal after an automatic retry, so the debit can stand and a lock can stay `SETTLING` (`PIX-0652`). When the detail names `overrides.allowFeeSkip` on a `pix_manual` settlement, the ledger refused the transfer out of the blocking account: settle again with `pix_manual` once the setting is on, or release the lock." default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Settle a cautionary block tags: - Balance Locks x-mint: href: /en/reference/interfaces/pix-lerian/spi/settle-a-cautionary-block /balance-locks/{lock_id}/settle/confirm: post: description: |- Applies the outcome of the devolution that Settle a cautionary block started: the lock becomes `SETTLED` when the devolution was paid, goes back to `PENDING` when it was rejected, and stays as it is while the devolution is in flight. The call carries no result, because Pix Lerian reads it from the devolution. Repeat the call until the lock leaves `SETTLING`. A `pix_manual` surplus is returned once, when the lock settles. If that return fails, the lock stays `SETTLED` and the answer is `200` without `surplus_midaz_tx_id`; this does not prove that the surplus stayed blocked. Check the ledger, then use [Return a settlement surplus to the account holder](/en/reference/interfaces/pix-lerian/spi/return-a-settlement-surplus-to-the-account-holder). A lock whose surplus was already returned is refused with `409` (`PIX-0656`) and stays `SETTLING`. `X-Actor-Id`, `X-Override-Reason` and `X-Override-Ticket` are optional. Sending any of them records the confirmation in the audit trail. For a lock opened for a MED infraction (`origin_system` `med-infraction`), use [Confirm settle refund](/en/reference/interfaces/pix-lerian/dict/confirm-settle-refund) instead: DICT holds MED state that this route cannot see. operationId: confirmSettle 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. An identical resend within 1 hour returns the original response, status included, with X-Idempotency-Replayed: true. Reusing the key with a divergent method, URL or body is PIX-0031 @ 412." in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Balance lock UUID in: path name: lock_id required: true schema: description: Balance lock UUID examples: - 01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60 type: string - description: Who is acting. Declared by the caller; not verified against the access token in: header name: X-Actor-Id schema: description: Who is acting. Declared by the caller; not verified against the access token examples: - backoffice.ops@example.com type: string - description: Why the caller is acting in: header name: X-Override-Reason schema: description: Why the caller is acting examples: - manual devolution paid by Pix type: string - description: Ticket reference in: header name: X-Override-Ticket schema: description: Ticket reference examples: - MED-4821 type: string - description: Correlation id in: header name: X-Correlation-Id schema: description: Correlation id examples: - med-2026-000123 type: string - description: Request id in: header name: X-Request-Id schema: description: Request id examples: - 01a17e29-5302-7c0a-b5e1-94d2f6a83c17 type: string responses: "200": content: application/json: example: lock_id: 01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60 payment_type: PIX_MANUAL status: SETTLED pix_end_to_end_id: E87654321202610271405m3Hs7Yc5Pv1 settled_at: "2026-10-27T14:06:03Z" surplus_midaz_tx_id: 01a17dae-b16e-7f28-9a03-6b1c4d8e2f75 schema: $ref: "#/components/schemas/ConfirmSettleResponse" 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: example: type: https://errors.lerian.studio/v1/PIX-0015 title: Bad Request status: 400 detail: One or more path parameters are invalid. code: PIX-0015 schema: $ref: "#/components/schemas/Detail" description: A duplicated or padded attribution header (PIX-0001), an oversized attribution header (PIX-0003), or a lock_id that is not a UUID (PIX-0015). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. Route-guard refusals (PIX-0001) answer in the legacy {code,title,message} envelope too. "404": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0011 title: Not Found status: 404 detail: No entity was found for the given ID. Please make sure to use the correct ID. code: PIX-0011 schema: $ref: "#/components/schemas/Detail" description: No lock exists for lock_id (PIX-0011). "409": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0012 title: Conflict status: 409 detail: The entity already exists or conflicts with an existing resource. code: PIX-0012 schema: $ref: "#/components/schemas/Detail" description: The lock is PENDING or RELEASED, or a concurrent update won (PIX-0012); the payment was rejected but the lock or its settle group already returned the surplus (PIX-0656). "412": content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header is held by a request still running or whose receipt could not be stored, or was already used with a different request. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: "Refused under this X-Idempotency (PIX-0031): the first request under it is still running (with Retry-After: 1), its receipt could not be stored and the key is held for the hour, or the request differs from the first (method, URL, body or identity header). An earlier request under this key may already have executed. Legacy {code,title,message} envelope, NOT problem+json." "422": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0328 title: Unprocessable Entity status: 422 detail: The ledger account is blocked and cannot be used for the requested operation. code: PIX-0328 schema: $ref: "#/components/schemas/Detail" description: A rejected pixRefund whose re-hold, or a completed devolution whose cancel of a left-behind re-hold, finds a blocked ledger account (PIX-0328); a rejected pixRefund whose re-hold finds a closed account or one whose status forbids sending (PIX-0332); a rejected pixRefund whose re-hold finds an account without a ledger alias (PIX-0655); no blocking account is configured for the participant (PIX-0650). "500": content: application/json: example: code: PIX-0000 title: Internal Server Error message: The server encountered an unexpected error. Please try again later. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" 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). With attribution headers, the confirm may already have taken effect when the audit record fails. "502": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0652 title: Bad Gateway status: 502 detail: The server could not complete the request. Please try again later. code: PIX-0652 schema: $ref: "#/components/schemas/Detail" description: "A completed devolution whose ledger search for, or cancel of, a left-behind re-hold failed, the lock staying SETTLING: repeat the confirm (PIX-0652). A rejected pixRefund whose re-hold failed in the ledger, or was refused after an automatic retry so it may stand (PIX-0652); with a detail naming overrides.allowFeeSkip, the lock stays SETTLING: repeat the confirm once it is enabled on the ledger that holds the blocking account." default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Confirm a cautionary block settlement tags: - Balance Locks x-mint: href: /en/reference/interfaces/pix-lerian/spi/confirm-a-cautionary-block-settlement /balance-locks/{lock_id}/unlock: post: description: |- Gives the funds of the lock back to the account holder and moves the lock to `RELEASED`. Funds still on hold have their pending ledger hold cancelled. Funds that a rejected or failed `pix_manual` settlement already moved to the blocking account are transferred back to the account of the holder in one ledger transfer, reported as `release_midaz_tx_id`. A released lock cannot be settled. The lock must be `PENDING` or `AWAITING_CREDIT`. A `SETTLING` lock is refused with `409` (`PIX-0653`): confirm its settlement first. Any other status is refused with `409` (`PIX-0012`). An `AWAITING_CREDIT` lock holds nothing, so Pix Lerian releases it with no ledger call. A lock whose funds sit in the blocking account is refused with `409` (`PIX-0656`) when any surplus of its payment was already returned. A transfer that fails or whose outcome is unknown answers `502` (`PIX-0652`): retry the call. A retry is safe at any time and never transfers twice. A release that moved funds out of the blocking account is always recorded in the audit trail. For a lock opened for a MED infraction (`origin_system` `med-infraction`), use [Release a balance block on an infraction report](/en/reference/interfaces/pix-lerian/dict/release-a-balance-block-on-an-infraction-report) instead: DICT holds MED state that this route cannot see. operationId: unlockBalanceLock 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. An identical resend within 1 hour returns the original response, status included, with X-Idempotency-Replayed: true. Reusing the key with a divergent method, URL or body is PIX-0031 @ 412." in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Balance lock UUID in: path name: lock_id required: true schema: description: Balance lock UUID examples: - 01a17d06-7910-7b35-9f4e-1c8a2d6e3b57 type: string - description: Who is acting. Declared by the caller; not verified against the access token in: header name: X-Actor-Id schema: description: Who is acting. Declared by the caller; not verified against the access token examples: - backoffice.ops@example.com type: string - description: Why the caller is acting in: header name: X-Override-Reason schema: description: Why the caller is acting examples: - manual devolution paid by Pix type: string - description: Ticket reference in: header name: X-Override-Ticket schema: description: Ticket reference examples: - MED-4821 type: string - description: Correlation id in: header name: X-Correlation-Id schema: description: Correlation id examples: - med-2026-000123 type: string - description: Request id in: header name: X-Request-Id schema: description: Request id examples: - 01a17e29-5302-7c0a-b5e1-94d2f6a83c17 type: string responses: "200": content: application/json: examples: holdCancelled: summary: "Funds still on hold: the ledger hold is cancelled" value: lock_id: 01a17d06-7910-7b35-9f4e-1c8a2d6e3b57 status: RELEASED released_at: "2026-10-27T11:15:30Z" transferredBack: summary: "Funds in the blocking account: one ledger transfer back to the holder" value: lock_id: 01a17d06-7910-7b35-9f4e-1c8a2d6e3b57 status: RELEASED released_at: "2026-10-27T17:42:18Z" release_midaz_tx_id: 01a17e12-4c3b-7d61-8b2f-3e9a5c7d1f48 schema: $ref: "#/components/schemas/UnlockBalanceResponse" 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: example: type: https://errors.lerian.studio/v1/PIX-0015 title: Bad Request status: 400 detail: One or more path parameters are invalid. code: PIX-0015 schema: $ref: "#/components/schemas/Detail" description: A duplicated or padded attribution header (PIX-0001), an oversized attribution header (PIX-0003), or a lock_id that is not a UUID (PIX-0015). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. Route-guard refusals (PIX-0001) answer in the legacy {code,title,message} envelope too. "404": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0011 title: Not Found status: 404 detail: No entity was found for the given ID. Please make sure to use the correct ID. code: PIX-0011 schema: $ref: "#/components/schemas/Detail" description: No lock exists for lock_id (PIX-0011). "409": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0653 title: Conflict status: 409 detail: The balance lock's settlement is not final yet; retry once it is. code: PIX-0653 schema: $ref: "#/components/schemas/Detail" description: "The lock is SETTLED or was released by cancelling its hold, is AWAITING_CREDIT with a hold the transfer's credit route may be placing, a concurrent unlock's transfer was refused and left it as it was, or its hold changed after it was read: retry (PIX-0012); the lock is SETTLING (PIX-0653); its funds sit in the blocking account and a surplus was already returned for its payment (PIX-0656)." "412": content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header is held by a request still running or whose receipt could not be stored, or was already used with a different request. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: "Refused under this X-Idempotency (PIX-0031): the first request under it is still running (with Retry-After: 1), its receipt could not be stored and the key is held for the hour, or the request differs from the first (method, URL, body or identity header). An earlier request under this key may already have executed. Legacy {code,title,message} envelope, NOT problem+json." "422": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0328 title: Unprocessable Entity status: 422 detail: The ledger account is blocked and cannot be used for the requested operation. code: PIX-0328 schema: $ref: "#/components/schemas/Detail" description: A ledger account is blocked, so the ledger refused to cancel the hold or the transfer back (PIX-0328); the account is closed or its status forbids receiving, so the ledger refused the transfer back and nothing moved (PIX-0332); on a lock whose funds sit in the blocking account, an account has no ledger alias (PIX-0655). "500": content: application/json: example: code: PIX-0000 title: Internal Server Error message: The server encountered an unexpected error. Please try again later. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" 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). With attribution headers, the release may already have taken effect when the audit record fails. "502": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0652 title: Bad Gateway status: 502 detail: The server could not complete the request. Please try again later. code: PIX-0652 schema: $ref: "#/components/schemas/Detail" description: "The ledger search for the lock's left-behind re-holds failed, the ledger did not cancel such a re-hold or the hold, could not read the hold or refused the transfer back to the holder after an automatic retry, or that transfer failed or has an unknown outcome, so it may have moved: retry the unlock, which never transfers twice (PIX-0652). With a detail naming overrides.allowFeeSkip, the ledger that holds the blocking account does not enable it, so nothing moved and the lock stays PENDING: retry the unlock once it is enabled." default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Release a cautionary block to the account holder tags: - Balance Locks x-mint: href: /en/reference/interfaces/pix-lerian/spi/release-a-cautionary-block-to-the-account-holder /transfers/{id}/credit: post: description: |- Credits a received Pix that BACEN settled and whose ledger credit Pix Lerian parked. The transfer is `PROCESSING`, and the `inbound_transfer.credit_parked` event named it with its reason: the `id` of the event is `{id}`, and its `accountId` is `X-Account-Id`, which finds the transfer and does not authorize the call. On success the transfer is `COMPLETED`, and Pix Lerian sends `inbound_transfer.completed`. The request has no body. The call never credits twice, whoever calls it and however often. When the ledger already lists the credit, the call completes the transfer without posting a second credit (`200`). Otherwise it posts the credit only while the ledger still answers the idempotency key of every earlier attempt, or after the ledger refused every earlier attempt. In any other case it answers `409` (`PIX-0474`): the ledger cannot confirm the credit, the transfer stays parked, and the credit is reconciled by hand. Never credit by hand in the ledger outside that reconciliation. The reason of the event decides who calls it. `LEDGER_OUTCOME_UNKNOWN` and `SETTLE_INTERRUPTED`: call it right away, by a person or by automation. A credit whose outcome is unknown can be completed for 45 minutes after the park: call at once, and retry a `502` until then. `ACCOUNT_BLOCKED` and `LEDGER_REFUSED`: do not call it automatically. Fix the cause first (unblock the account, or fix the account, alias, balance, credentials or ledger configuration). The first call then parks the transfer again as `LEDGER_OUTCOME_UNKNOWN` and starts a one-way 45-minute clock. A ledger without `overrides.allowFeeSkip` refuses the fee skip that the credit requires (`502`, `PIX-0652`; the detail names the setting) and posts nothing. Call again within 45 minutes of the first refused call, once the setting is on: after that, the transfer falls to the `PIX-0474` reconciliation. The caller needs the transfers permission with the post action, the same permission that initiates and processes a transfer. When MED blocks wait for the credit, the call posts the credit and their holds together. operationId: creditParkedTransfer 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. An identical resend within 1 hour returns the original response, status included, with X-Idempotency-Replayed: true. Reusing the key with a divergent method, URL or body is PIX-0031 @ 412." in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: "Transfer UUID: the id of the inbound_transfer.credit_parked event" in: path name: id required: true schema: description: "Transfer UUID: the id of the inbound_transfer.credit_parked event" examples: - 01a18811-6b64-7a10-b2c3-d4e5f6071829 type: string - description: "The credited account UUID: the accountId of the inbound_transfer.credit_parked event. It finds the transfer; it does not authorize the call" in: header name: X-Account-Id required: true schema: description: "The credited account UUID: the accountId of the inbound_transfer.credit_parked event. It finds the transfer; it does not authorize the call" examples: - 019cadd4-5620-7c2d-8e3f-4a5b6c7d8e9f type: string - description: Who is acting. Declared by the caller; not verified against the access token in: header name: X-Actor-Id schema: description: Who is acting. Declared by the caller; not verified against the access token examples: - backoffice.ops@example.com type: string - description: Why the caller is acting in: header name: X-Override-Reason schema: description: Why the caller is acting examples: - manual devolution paid by Pix type: string - description: Ticket reference in: header name: X-Override-Ticket schema: description: Ticket reference examples: - MED-4821 type: string - description: Correlation id in: header name: X-Correlation-Id schema: description: Correlation id examples: - med-2026-000123 type: string - description: Request id in: header name: X-Request-Id schema: description: Request id examples: - 01a17e29-5302-7c0a-b5e1-94d2f6a83c17 type: string responses: "200": content: application/json: example: id: 01a18811-6b64-7a10-b2c3-d4e5f6071829 accountId: 019cadd4-5620-7c2d-8e3f-4a5b6c7d8e9f endToEndId: E87654321202610291430AbCdEf12345 status: COMPLETED type: INBOUND initiationType: DICT source: account: branch: "0001" number: "1112223" participant: "87654321" type: CACC owner: document: "11144477735" name: Maria Souza type: NATURAL_PERSON destination: account: branch: "0001" number: "9988776" participant: "12345678" type: CACC owner: document: "52998224725" name: Joao Pereira type: NATURAL_PERSON amount: "100.00" currency: BRL description: Pagamento de aluguel ledger: transactionId: 01a18826-1aff-7d11-a2b3-c4d5e6f70819 sourceOperationId: 01a18826-1aff-7d12-a2b3-c4d5e6f7081a destinationOperationId: 01a18826-1aff-7d13-a2b3-c4d5e6f7081b createdAt: "2026-10-29T14:30:05.412Z" updatedAt: "2026-10-29T14:52:41.087Z" alreadyRefundedAmount: "0.00" remainingRefundableAmount: "100.00" 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: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: "#/components/schemas/Detail" description: A missing (PIX-0001) or malformed (PIX-0017) X-Account-Id, a transfer id that is not a UUID (PIX-0015), or an attribution header over its length limit (PIX-0003). A duplicated or padded X-Account-Id or attribution header (PIX-0001). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. Route-guard refusals (PIX-0001) answer in the legacy {code,title,message} envelope too. "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 with this id credits the X-Account-Id account (PIX-0340). "409": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0474 title: Conflict status: 409 detail: The ledger cannot confirm this credit; reconcile it by hand. code: PIX-0474 schema: $ref: "#/components/schemas/Detail" description: '`PIX-0473`: not a parked inbound transfer. `PIX-0474`: the ledger cannot confirm the credit, so the transfer stays parked and the credit is reconciled by hand.' "412": content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header is held by a request still running or whose receipt could not be stored, or was already used with a different request. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: "Refused under this X-Idempotency (PIX-0031): the first request under it is still running (with Retry-After: 1), its receipt could not be stored and the key is held for the hour, or the request differs from the first (method, URL, body or identity header). An earlier request under this key may already have executed. Legacy {code,title,message} envelope, NOT problem+json." "422": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0328 title: Unprocessable Entity status: 422 detail: The ledger account is blocked and cannot be used for the requested operation. code: PIX-0328 schema: $ref: "#/components/schemas/Detail" description: "`PIX-0328`: the credited ledger account is blocked, and the transfer stays parked as `LEDGER_OUTCOME_UNKNOWN`: unblock it and retry within 45 minutes. `PIX-0475`: the ledger refused the credit for a cause that a retry does not clear (an account status that forbids receiving, a closed account, a usage limit, a missing alias, balance, asset, ledger or organization, or more than one ledger fee package matching the credit), and the transfer stays parked: fix the cause, then retry within 45 minutes. A closed account is final: no call credits it. When MED blocks wait for the credit, a refusal of the credit or of the hold of a block (`PIX-0013`, `PIX-0328`, `PIX-0329`, `PIX-0650`, `PIX-0655`) leaves the transfer parked: fix the cause, then call again." "500": content: application/json: example: code: PIX-0000 title: Internal Server Error message: The server encountered an unexpected error. Please try again later. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" 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, a concurrent call posting the payment's blocks, a listed credit whose MED batch hold the ledger does not list yet, or a ledger configuration that did not load for the only send of a MED batch, which parks the transfer refused again (PIX-0000). The transfer is parked or already COMPLETED: call again." "502": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0472 title: Bad Gateway status: 502 detail: The server could not complete the request. Please try again later. code: PIX-0472 schema: $ref: "#/components/schemas/Detail" description: "`PIX-0472`: the ledger was unreachable, refused the credentials, failed the search or the post, or refused the post on a balance that another write moved; the transfer stays parked: retry within the 45-minute window, after you fix the credentials when the ledger refused them. `PIX-0652`: the ledger refused the fee skip (the detail names `overrides.allowFeeSkip`), or failed while posting the hold of a MED block that waits for the credit: call again within 45 minutes of the first refused call, once the setting is on when the detail names it." default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Credit a received Pix whose ledger credit is parked tags: - Transfers x-mint: href: /en/reference/interfaces/pix-lerian/spi/credit-a-received-pix-whose-ledger-credit-is-parked /refunds/{id}/credit: post: description: |- Credits a received Pix refund (a devolução that your institution received) that BACEN settled and whose ledger credit to the account of the original sender Pix Lerian parked. The refund is `PROCESSING`, and the `refund.credit_parked` event named it with its reason: the `id` of the event is `{id}`, and its `accountId` is `X-Account-Id`, which finds the refund and does not authorize the call. On success the refund is `COMPLETED`, and Pix Lerian sends `refund.completed`. The request has no body. The call never credits twice, whoever calls it and however often. When the ledger already lists the credit, the call completes the refund without posting a second credit (`200`). Otherwise it posts the credit only while the ledger still answers the idempotency key of every earlier attempt, or after the ledger refused every earlier attempt. In any other case it answers `409` (`PIX-0474`): the ledger cannot confirm the credit, the refund stays parked, and the credit is reconciled by hand. Never credit by hand in the ledger outside that reconciliation. The reason of the event decides who calls it. `LEDGER_OUTCOME_UNKNOWN` and `SETTLE_INTERRUPTED`: call it right away, by a person or by automation. A credit whose outcome is unknown can be completed for 45 minutes after the park: call at once, and retry a `502` until then. `ACCOUNT_BLOCKED` and `LEDGER_REFUSED`: do not call it automatically. Fix the cause first (unblock the account, or fix the account, alias, balance, credentials or ledger configuration). The first call then parks the refund again as `LEDGER_OUTCOME_UNKNOWN` and starts a one-way 45-minute clock. A ledger without `overrides.allowFeeSkip` refuses the fee skip that the credit requires (`502`, `PIX-0652`; the detail names the setting) and posts nothing. Call again within 45 minutes of the first refused call, once the setting is on: after that, the refund falls to the `PIX-0474` reconciliation. The caller needs the refunds permission with the post action, the same permission that creates a refund. operationId: creditParkedRefund 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. An identical resend within 1 hour returns the original response, status included, with X-Idempotency-Replayed: true. Reusing the key with a divergent method, URL or body is PIX-0031 @ 412." in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: "Refund UUID: the id of the refund.credit_parked event" in: path name: id required: true schema: description: "Refund UUID: the id of the refund.credit_parked event" examples: - 019a3c41-7e2b-7d10-9c4a-5b6e7f805678 type: string - description: "The credited account UUID: the accountId of the refund.credit_parked event (the original payment's source account). It finds the refund; it does not authorize the call" in: header name: X-Account-Id required: true schema: description: "The credited account UUID: the accountId of the refund.credit_parked event (the original payment's source account). It finds the refund; it does not authorize the call" examples: - 019cadd4-5620-7c2d-8e3f-4a5b6c7d8e9f type: string - description: Who is acting. Declared by the caller; not verified against the access token in: header name: X-Actor-Id schema: description: Who is acting. Declared by the caller; not verified against the access token examples: - backoffice.ops@example.com type: string - description: Why the caller is acting in: header name: X-Override-Reason schema: description: Why the caller is acting examples: - manual devolution paid by Pix type: string - description: Ticket reference in: header name: X-Override-Ticket schema: description: Ticket reference examples: - MED-4821 type: string - description: Correlation id in: header name: X-Correlation-Id schema: description: Correlation id examples: - med-2026-000123 type: string - description: Request id in: header name: X-Request-Id schema: description: Request id examples: - 01a17e29-5302-7c0a-b5e1-94d2f6a83c17 type: string responses: "200": content: application/json: example: id: 019a3c41-7e2b-7d10-9c4a-5b6e7f805678 accountId: 019cadd4-5620-7c2d-8e3f-4a5b6c7d8e9f originalEndToEndId: E12345678202610281015AbCdEf12345 returnEndToEndId: D87654321202610291430FeDcBa54321 status: COMPLETED type: INBOUND amount: "40.00" reasonCode: MD06 description: Valor enviado em duplicidade ledger: transactionId: 019a3c52-1aff-7d11-a2b3-c4d5e6f70819 sourceOperationId: 019a3c52-1aff-7d12-a2b3-c4d5e6f7081a destinationOperationId: 019a3c52-1aff-7d13-a2b3-c4d5e6f7081b createdAt: "2026-10-29T14:30:05.412Z" updatedAt: "2026-10-29T14:52:41.087Z" 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: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: "#/components/schemas/Detail" description: A missing (PIX-0001) or malformed (PIX-0017) X-Account-Id, a refund id that is not a UUID (PIX-0015), or an attribution header over its length limit (PIX-0003). A duplicated or padded X-Account-Id or attribution header (PIX-0001). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. Route-guard refusals (PIX-0001) answer in the legacy {code,title,message} envelope too. "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 with this id credits the X-Account-Id account (PIX-0420). "409": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0474 title: Conflict status: 409 detail: The ledger cannot confirm this credit; reconcile it by hand. code: PIX-0474 schema: $ref: "#/components/schemas/Detail" description: '`PIX-0523`: not a parked inbound refund. `PIX-0474`: the ledger cannot confirm the credit, so the refund stays parked and the credit is reconciled by hand.' "412": content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The X-Idempotency header is held by a request still running or whose receipt could not be stored, or was already used with a different request. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" description: "Refused under this X-Idempotency (PIX-0031): the first request under it is still running (with Retry-After: 1), its receipt could not be stored and the key is held for the hour, or the request differs from the first (method, URL, body or identity header). An earlier request under this key may already have executed. Legacy {code,title,message} envelope, NOT problem+json." "422": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0328 title: Unprocessable Entity status: 422 detail: The ledger account is blocked and cannot be used for the requested operation. code: PIX-0328 schema: $ref: "#/components/schemas/Detail" description: "`PIX-0328`: the credited ledger account is blocked, and the refund stays parked as `LEDGER_OUTCOME_UNKNOWN`: unblock it and retry within 45 minutes. `PIX-0475`: the ledger refused the credit for a cause that a retry does not clear (an account status that forbids receiving, a closed account, a usage limit, a missing alias, balance, asset, ledger or organization, or more than one ledger fee package matching the credit), and the refund stays parked: fix the cause, then retry within 45 minutes. A closed account, or one without an alias, is final: no call credits it." "500": content: application/json: example: code: PIX-0000 title: Internal Server Error message: The server encountered an unexpected error. Please try again later. schema: $ref: "#/components/schemas/LegacyErrorEnvelope" 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). The refund is parked or already COMPLETED: call again." "502": content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0522 title: Bad Gateway status: 502 detail: The server could not complete the request. Please try again later. code: PIX-0522 schema: $ref: "#/components/schemas/Detail" description: "`PIX-0522`: the ledger was unreachable, refused the credentials, failed the search or the post, or refused the post on a balance that another write moved; the refund stays parked: retry within the 45-minute window, after you fix the credentials when the ledger refused them. `PIX-0652`: a ledger without `overrides.allowFeeSkip` refuses the fee skip that the credit requires and posts nothing: call again within 45 minutes of the first refused call, once the setting is on." default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error summary: Credit a received Pix refund whose ledger credit is parked tags: - Refunds x-mint: href: /en/reference/interfaces/pix-lerian/spi/credit-a-received-pix-refund-whose-ledger-credit-is-parked 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, sent in the pacs.004. U+0000 is refused (400 PIX-0010); U+FFFE, U+FFFF or U+0001-U+001F other than tab, line feed or carriage return is refused (400 PIX-0003). 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. Today is accepted only before 08:00 in America/Sao_Paulo (PIX-0758)." 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-character BACEN ISPB (digits or uppercase letters) of the receiving institution. examples: - '60746948' type: string type: description: "Account type. SLRY (salary account) is refused by request validation (400 PIX-0003): a salary account cannot receive a Pix, and the rail would refuse it only on the scheduled date." enum: - CACC - SVGS - TRAN examples: - CACC type: string required: - number - participant - type type: object 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 description: "Whether the ledger charged a fee on the create that moved the operation's money. When false, no other field is present. applied reports what the create did and the object is kept as its record. Where the operation carries ledger.revert (transfers only: REJECTED, or FAILED after the debit was reverted), the revert inverted the fee legs with the amount, so the fee was returned; on a transfer without ledger.revert, feeCharge says nothing about the fee's final position." calculationType: examples: - LEDGER type: string description: How the total fee was calculated. LEDGER when the ledger's fee package computed it. fees: items: $ref: '#/components/schemas/FeeEntryResponse' type: - array - 'null' description: Individual fee entries that make up the total, one per ledger fee leg. netAmount: examples: - "100.00" type: string description: "Amount that reached the destination: on an outbound operation what the ledger moved to the rail, on an inbound one what it credited to the receiving account (the operation's amount when the ledger reported no such leg; on an outbound operation a deductible fee package, a misconfiguration on a Pix ledger, makes it lower than the amount)." totalAmount: examples: - '1.50' type: string description: Sum of every fee entry the ledger charged on the operation. required: - applied type: object FeeEntryResponse: additionalProperties: false properties: amount: examples: - '1.50' type: string description: Amount of this fee entry. calculationType: examples: - LEDGER type: string description: How this entry was calculated. LEDGER when the ledger's fee package computed it. calculationValue: type: string description: Raw value the calculation was parameterised with. Absent when calculationType is LEDGER. creditAccount: examples: - "@fees-pix" type: string description: Ledger account credited with this fee entry. feeLabel: examples: - LEDGER_FEE type: string description: "Label of this fee entry. LEDGER_FEE on every entry the ledger reported: its answer names no fee, so creditAccount is what distinguishes one entry from another." required: - feeLabel - amount type: object InitiateTransferBody: additionalProperties: false properties: description: description: Free-form payment description. U+0000 is refused (400 PIX-0010); U+FFFE, U+FFFF or U+0001-U+001F other than tab, line feed or carriage return is refused (400 PIX-0003). 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 fields: additionalProperties: type: string description: Per-field detail, keyed by the field or header the refusal names type: object headers: additionalProperties: type: string description: Per-header detail, keyed by the request header the refusal names type: object required: - code - title - message type: object 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-character BACEN participant identifier (digits or uppercase letters). examples: - '32074986' type: string name: examples: - Ana Souza type: string personType: enum: - NATURAL_PERSON - LEGAL_PERSON examples: - NATURAL_PERSON type: string taxId: description: CPF or CNPJ, digits only. examples: - '39053344705' type: string required: - accountType - ispb - personType - taxId - name type: object 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 fixed QR amount; a dynamic charge the payer may change only suggests one) 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 feeCharge: $ref: "#/components/schemas/FeeChargeResponse" description: "Fee the ledger reported on the create that moved the refund's money. Absent when no fee answer was recorded for this refund (its ledger create never landed, an error was logged at the time, or the refund was created before fees were read back); {\"applied\": false} when the ledger reported that no fee was charged; the full object when it charged one. A refund carries no ledger.revert field and needs none here: a FAILED refund that carries feeCharge was reverted first -- every path that writes a refund FAILED after its ledger create landed reverts the debit before marking it (a revert that does not complete leaves the refund PROCESSING), and every other path fails before any create -- so the fee was returned with the amount; applied reports what the create did and the object records the create." 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 - CHARGE_AMOUNT_CHANGED - CHARGE_NOT_PAYABLE - OPERATIONAL_FAILURE_PRE_DISPATCH - OPERATIONAL_FAILURE_POST_DISPATCH type: string providerChannel: description: The CSM channel the attempt went out on. UNKNOWN is a real answer from a rail that cannot report one. enum: - PRIMARY - SECONDARY - UNKNOWN type: string startedAt: format: date-time type: string required: - id - attemptNumber - isLastAttempt - startedAt type: object 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. CHARGE_AMOUNT_CHANGED and CHARGE_NOT_PAYABLE: on the scheduled date the QR charge asked another amount, or the receiver refused reading it (the charge was removed, concluded or expired); nothing was debited. A failed check of the receiver's site or signature cancels nothing: like a receiver that does not answer, it pays the recorded amount." enum: - USER_REQUEST - OWNERSHIP_MISMATCH - KEY_NOT_FOUND - CHARGE_AMOUNT_CHANGED - CHARGE_NOT_PAYABLE - RECURRENCE_CANCELLED type: string createdAt: format: date-time type: string currency: description: Always BRL. examples: - BRL type: string description: description: The payer's memo, returned exactly as it was stored. Markup is not interpreted here and was not escaped on the way in; escaping belongs to whoever renders it. examples: - Aluguel de setembro type: string destination: $ref: '#/components/schemas/ParticipantView' description: The payee as photographed at creation. On a DICT schedule it is compared on the scheduled date against a fresh directory answer (REG-Art.9§6), which is why it is stored rather than re-resolved; a MANUAL or QR_CODE schedule is sent to it as photographed, with no second lookup. firstWindowOpensAt: description: When the first settlement window of the scheduled date opens (IN 513 art. 12 caput). Photographed at creation. format: date-time type: string id: description: Schedule identifier. examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string initiationType: description: How the destination was resolved. enum: - MANUAL - DICT - QR_CODE examples: - DICT type: string purpose: description: 'Always IPAY: REG-Art.11-P prohibits scheduling any other purpose.' enum: - IPAY examples: - IPAY type: string scheduledDate: description: Civil settlement date in AAAA-MM-DD, in America/Sao_Paulo. examples: - '2026-09-10' format: date type: string source: $ref: '#/components/schemas/ParticipantView' description: The payer as photographed at creation. status: description: 'Lifecycle status. DISPATCHED_OUTCOME_UNKNOWN is NOT terminal: the order is awaiting reconciliation and will resolve to SETTLED or FAILED. It does NOT assert that the order reached the rail -- it also covers an order that provably did not, whose reserved funds are still being released.' enum: - PENDING - EXECUTING - DISPATCHED_OUTCOME_UNKNOWN - AWAITING_RETRY - SETTLED - CANCELLED - FAILED examples: - PENDING type: string transferId: description: The transfer that settled this schedule, once it has. type: string updatedAt: format: date-time type: string required: - id - accountId - scheduledDate - amount - currency - initiationType - purpose - source - destination - status - firstWindowOpensAt - cancellationCutoff - createdAt - updatedAt - attempts type: object 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' description: "Fee the ledger reported on the transfer. Absent when the ledger's fee answer was not recorded for this transfer (an error logged at the time, or a transfer created before fees were read back); {\"applied\": false} when the ledger reported that no fee was charged; the full object when it charged one." 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. Today is accepted only before 08:00 in America/Sao_Paulo (PIX-0758)." examples: - "2027-08-10" format: date type: string indefinite: description: "An open-ended series. This IS a termination criterion the payer chose -- supply exactly one of the three. Sending none is refused with PIX-0761 rather than read as open-ended: silence is a series nobody can say when to stop paying." examples: - false type: boolean paymentCount: description: "Termination by number of payments. NO ceiling is imposed: REG-Art.37-A forbids limiting the quantity of a user's transactions." examples: - 12 format: int64 minimum: 1 type: integer periodicity: description: How often the series pays. QUARTERLY, SEMIANNUAL and ANNUALLY belong to Pix Automatico and are refused here by request validation (400 PIX-0003). enum: - WEEKLY - MONTHLY examples: - MONTHLY type: string required: - periodicity - firstPaymentDate type: object 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 CreateSettleResponse: additionalProperties: false properties: already_settled: examples: - "0.00" type: string initiated_at: examples: - "2026-10-27T14:05:12Z" format: date-time type: string lock_id: examples: - 01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60 type: string original_amount: examples: - "150.75" type: string payment_type: examples: - PIX_MANUAL type: string requested_amount: examples: - "80.13" type: string settle_amount: examples: - "80.13" type: string status: examples: - SETTLING type: string surplus_amount: description: pixManual surplus (the lock's effective amount minus settle_amount) that the settle confirmation returns to the customer once the lock is SETTLED; nothing is returned by this call. Always 0 for pixRefund. examples: - "20.13" type: string surplus_midaz_tx_id: description: "Not filled: the surplus is returned by the settle confirmation, whose response carries the transaction id. Kept in the schema for compatibility." examples: - 01a17dae-b16e-7f28-9a03-6b1c4d8e2f75 type: string required: - lock_id - payment_type - status - original_amount - requested_amount - already_settled - settle_amount - surplus_amount - initiated_at type: object CreateSettleBody: additionalProperties: false properties: original_amount: description: Original transaction face value (ceiling) examples: - "150.75" type: string pix_manual: $ref: "#/components/schemas/SettlePixManualInput" pix_refund: $ref: "#/components/schemas/SettlePixRefundInput" refund_ref: description: Idempotency key for this settle examples: - med-2026-000123-devolution type: string required: - refund_ref - original_amount type: object CreateBalanceLockBody: additionalProperties: false properties: amount: description: Requested hold amount examples: - "150.75" type: string asset: description: Asset code (only BRL supported) examples: - BRL type: string end_to_end_id: description: Related Pix transaction end-to-end id examples: - E12345678202610271032k7Qm2Xp9Ld4 type: string external_ref: description: Grouping reference (not unique) examples: - med-2026-000123 type: string origin_system: description: Calling system/flow discriminator examples: - med-infraction type: string request_ref: description: Idempotency key for this creation (unique per tenant) examples: - med-2026-000123-hold-1 type: string required: - request_ref - external_ref - origin_system - end_to_end_id - amount - asset type: object CreateBalanceLockResponse: additionalProperties: false properties: created_at: examples: - "2026-10-27T10:41:07Z" format: date-time type: string effective_amount: examples: - "100.26" type: string lock_id: examples: - 01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60 type: string midaz_tx_id: description: The ledger hold; empty while AWAITING_CREDIT examples: - 01a17cf3-133d-7a52-8e19-0c4b6d2f7a91 type: string requested_amount: examples: - "150.75" type: string status: description: PENDING, or AWAITING_CREDIT while the Pix's ledger credit is parked and nothing is held yet examples: - PENDING type: string required: - lock_id - midaz_tx_id - status - requested_amount - effective_amount - created_at type: object ListBalanceLocksOutput: additionalProperties: false properties: items: items: $ref: "#/components/schemas/BalanceLockListItem" type: - array - "null" next_cursor: type: - string - "null" required: - items - next_cursor type: object ReturnSurplusResponse: additionalProperties: false properties: lock_id: examples: - 01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60 type: string returned_at: examples: - "2026-10-27T15:02:41Z" format: date-time type: string surplus_amount: examples: - "0.00" type: string surplus_midaz_tx_id: description: "Midaz transaction that moved the surplus: created by this call, or already recorded on the lock or, for a group settle, on another lock of the same group (then surplus_amount is 0). Absent when no surplus transfer exists." examples: - 01a17dae-b16e-7f28-9a03-6b1c4d8e2f75 type: string required: - lock_id - surplus_amount - returned_at type: object SettleQuoteResponse: additionalProperties: false properties: already_settled: examples: - "100.26" type: string available_to_settle: examples: - "50.49" type: string original_amount: examples: - "150.75" type: string required: - original_amount - already_settled - available_to_settle type: object CreateGroupSettleResponse: additionalProperties: false properties: already_settled: examples: - "0.00" type: string initiated_at: examples: - "2026-10-27T14:05:12Z" format: date-time type: string lock_ids: items: type: string type: - array - "null" original_amount: examples: - "150.75" type: string payment_type: examples: - PIX_REFUND type: string refund_ref: examples: - med-2026-000123-group-devolution type: string settle_amount: examples: - "150.75" type: string status: examples: - SETTLING type: string surplus_amount: description: pixManual group surplus (soma_efetiva minus settle_amount) that the SUCCESS group confirm returns once every lock is SETTLED; nothing is returned by this call. Always 0 for pixRefund. examples: - "0.00" type: string required: - refund_ref - payment_type - status - original_amount - already_settled - settle_amount - surplus_amount - lock_ids - initiated_at type: object CreateGroupSettleBody: additionalProperties: false properties: lock_ids: description: Concrete block ids to settle together examples: - - 01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60 items: type: string type: - array - "null" original_amount: description: Contested transaction face value (ceiling) examples: - "150.75" type: string original_end_to_end_id: description: Contested transaction end-to-end id examples: - E12345678202610271032k7Qm2Xp9Ld4 type: string pix_manual: $ref: "#/components/schemas/GroupSettlePixManualBody" pix_refund: $ref: "#/components/schemas/GroupSettlePixRefundBody" refund_ref: description: Group key shared by the N blocks examples: - med-2026-000123-group-devolution type: string required: - refund_ref - lock_ids - original_amount - original_end_to_end_id type: object UnlockBalanceResponse: additionalProperties: false properties: lock_id: examples: - 01a17d06-7910-7b35-9f4e-1c8a2d6e3b57 type: string release_midaz_tx_id: description: Ledger transaction that moved the funds from the institution's blocking account back to the account holder, for a lock whose funds a rejected pixManual settle had already moved there. Absent when the release cancelled a pending hold. examples: - 01a17e12-4c3b-7d61-8b2f-3e9a5c7d1f48 type: string released_at: examples: - "2026-10-27T11:15:30Z" format: date-time type: string status: examples: - RELEASED type: string required: - lock_id - status - released_at type: object CloseBalanceLockResponse: additionalProperties: false properties: closed_at: examples: - "2026-10-27T16:20:00Z" format: date-time type: string closed_manually: examples: - true type: boolean lock_id: examples: - 01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60 type: string pix_end_to_end_id: examples: - D87654321202610271405r4Tn8Wq2Kx6 type: string status: examples: - SETTLED type: string required: - lock_id - status - pix_end_to_end_id - closed_manually - closed_at type: object CloseBalanceLockBody: additionalProperties: false properties: end_to_end_id: description: Externally-executed devolution/transfer end-to-end id examples: - D87654321202610271405r4Tn8Wq2Kx6 type: string notes: type: string payment_type: description: Required when closing from PENDING; preserved when SETTLING examples: - PIX_REFUND type: string settled_amount: description: Amount the manual devolution returned to the payer. Defaults to, and cannot exceed, the lock's effective_amount or, on a SETTLING lock, the amount its settle reserved; a SETTLING pixManual lock takes exactly that amount examples: - "100.26" type: string required: - end_to_end_id type: object ConfirmSettleResponse: additionalProperties: false properties: failure_reason: type: string lock_id: examples: - 01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60 type: string payment_type: examples: - PIX_MANUAL type: string pix_end_to_end_id: examples: - E87654321202610271405m3Hs7Yc5Pv1 type: string reset_at: examples: - "2026-10-27T14:06:03Z" format: date-time type: string settled_at: examples: - "2026-10-27T14:06:03Z" format: date-time type: string status: examples: - SETTLED type: string surplus_midaz_tx_id: description: "On SETTLED, the Midaz transaction that returned the pixManual surplus to the customer: made by this confirm once the lock is SETTLED, or already recorded (a replay, or a group member's). Absent when there is no surplus, or when the best-effort return failed -- recover it with POST /balance-locks/{lock_id}/return-surplus." examples: - 01a17dae-b16e-7f28-9a03-6b1c4d8e2f75 type: string required: - lock_id - status type: object ListBalanceLockAuditResponse: additionalProperties: false properties: entries: items: $ref: "#/components/schemas/BalanceLockAuditEntryResponse" type: - array - "null" required: - entries type: object ConfirmGroupSettleResponse: additionalProperties: false properties: already_settled: examples: - "0.00" type: string failure_reason: examples: - aggregated group devolution reported FAILED by caller type: string original_amount: examples: - "150.75" type: string payment_type: examples: - PIX_REFUND type: string pix_end_to_end_id: examples: - D87654321202610271405g7Bv3Nc9Jw2 type: string refund_ref: examples: - med-2026-000123-group-devolution type: string reset_at: examples: - "2026-10-27T14:06:03Z" format: date-time type: string settle_amount: examples: - "150.75" type: string settled_at: examples: - "2026-10-27T14:06:03Z" format: date-time type: string status: examples: - SETTLED type: string surplus_amount: examples: - "0.00" type: string surplus_midaz_tx_id: description: "On SETTLED, the Midaz transaction that returned the pixManual group surplus to the customer: made by this confirm once every lock is SETTLED, or already recorded on the group (a replay). Absent when there is no surplus, or when the best-effort return failed -- recover it with POST /balance-locks/{lock_id}/return-surplus on the lock that bears the surplus." examples: - 01a17dae-b16e-7f28-9a03-6b1c4d8e2f75 type: string required: - refund_ref - status type: object ConfirmGroupSettleBody: additionalProperties: false properties: end_to_end_id: description: Aggregated devolution end-to-end id (required when result=SUCCESS) examples: - D87654321202610271405g7Bv3Nc9Jw2 type: string refund_ref: description: Group key examples: - med-2026-000123-group-devolution type: string result: description: SUCCESS or FAILED; omit to poll current state examples: - SUCCESS type: string required: - refund_ref type: object BalanceLockListItem: additionalProperties: false properties: created_at: examples: - "2026-10-27T10:41:07Z" format: date-time type: string effective_amount: examples: - "100.26" type: string end_to_end_id: examples: - E12345678202610271032k7Qm2Xp9Ld4 type: string external_ref: examples: - med-2026-000123 type: string lock_id: examples: - 01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60 type: string origin_system: examples: - med-infraction type: string payment_type: type: - string - "null" pix_end_to_end_id: type: - string - "null" requested_amount: examples: - "150.75" type: string settled_amount: type: - string - "null" settling_at: format: date-time type: - string - "null" status: examples: - PENDING type: string surplus_midaz_tx_id: type: - string - "null" updated_at: examples: - "2026-10-27T10:41:07Z" format: date-time type: string required: - lock_id - origin_system - external_ref - end_to_end_id - status - requested_amount - effective_amount - created_at - updated_at type: object SettlePixRefundInput: additionalProperties: false properties: amount: examples: - "100.26" type: string asset: examples: - BRL type: string return_reason_code: examples: - FR01 type: string required: - return_reason_code - amount - asset type: object GroupSettlePixManualBody: additionalProperties: false properties: account: examples: - "1234567" type: string account_type: examples: - CC type: string asset: examples: - BRL type: string branch: examples: - "0001" type: string description: description: U+0000 is refused (400 PIX-0010); U+FFFE, U+FFFF or U+0001-U+001F other than tab, line feed or carriage return is refused (400 PIX-0003). examples: - MED devolution to the payer type: string document: examples: - "12345678909" type: string ispb: examples: - "12345678" type: string transaction_type: examples: - INSTANT_PAYMENT_REFUND type: string required: - ispb - branch - account - account_type - document - asset type: object BalanceLockAuditEntryResponse: additionalProperties: false properties: action: examples: - CLOSE type: string actor: examples: - backoffice.ops@example.com type: string correlation_id: type: string created_at: format: date-time type: string id: examples: - 01a17e29-5544-7b96-8d2a-3f0e71c9a4b8 type: string lock_id: type: string reason: examples: - manual devolution paid by Pix type: string refund_ref: type: string request_id: type: string ticket: examples: - MED-4821 type: string required: - id - action - actor - reason - request_id - created_at type: object SettlePixManualInput: additionalProperties: false properties: account: examples: - "1234567" type: string account_type: examples: - CC type: string amount: examples: - "80.13" type: string asset: examples: - BRL type: string branch: examples: - "0001" type: string description: description: U+0000 is refused (400 PIX-0010); U+FFFE, U+FFFF or U+0001-U+001F other than tab, line feed or carriage return is refused (400 PIX-0003). examples: - MED devolution to the payer type: string document: examples: - "12345678909" type: string ispb: examples: - "12345678" type: string required: - ispb - branch - account - account_type - document - amount - asset type: object GroupSettlePixRefundBody: additionalProperties: false properties: asset: examples: - BRL type: string return_reason_code: examples: - FR01 type: string required: - return_reason_code - asset type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http