> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Settle every cautionary block of a Pix > 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](/es/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](/es/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](/es/reference/interfaces/pix-lerian/spi/confirm-a-group-settlement). ## OpenAPI ````yaml /es/openapi/v3-current/pix-lerian-spi.yaml post /balance-locks/settle openapi: 3.1.0 info: contact: name: Lerian Studio url: https://lerian.studio description: Public API for outbound Pix transfers, refunds, and scheduled payments. license: name: Lerian Studio General License title: Pix Lerian — Payments version: 1.2.0 servers: - url: https://api.example.com/spi/v1 description: >- Replace the example host with the URL provided during environment onboarding. security: - BearerAuth: [] tags: - description: Create, list, and retrieve Pix refunds. name: Refunds - name: Scheduled Payments description: Register, list, retrieve, and cancel scheduled Pix payments. - description: Initiate, process, list, and retrieve outbound Pix transfers. name: Transfers - description: >- Register, list, retrieve, and cancel recurring series of scheduled Pix payments. name: Scheduled Payment Recurrences - description: >- Hold the funds of a received Pix in a cautionary block (MED 2.0), return them to the payer, or give them back to the account holder. name: Balance Locks paths: /balance-locks/settle: post: tags: - Balance Locks summary: Settle every cautionary block of a Pix 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](/es/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](/es/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](/es/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 components: schemas: 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 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 LegacyErrorEnvelope: additionalProperties: false properties: code: description: PIX-XXXX error code type: string message: description: Human-readable error message type: string title: description: Short error title type: string fields: additionalProperties: type: string description: Per-field detail, keyed by the field or header the refusal names type: object headers: additionalProperties: type: string description: Per-header detail, keyed by the request header the refusal names type: object required: - code - title - message type: object Detail: additionalProperties: true properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object 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 GroupSettlePixRefundBody: additionalProperties: false properties: asset: examples: - BRL type: string return_reason_code: examples: - FR01 type: string required: - return_reason_code - asset type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.