> ## 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 a cautionary block > 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](/es/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](/es/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](/es/reference/interfaces/pix-lerian/dict/settle-refund) instead: DICT holds MED state that this route cannot see. ## OpenAPI ````yaml /es/openapi/v3-current/pix-lerian-spi.yaml post /balance-locks/{lock_id}/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/{lock_id}/settle: post: tags: - Balance Locks summary: Settle a cautionary block 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](/es/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](/es/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](/es/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 components: schemas: 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 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 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 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 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 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.