> ## 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. # Release a cautionary block to the account holder > 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. ## OpenAPI ````yaml /en/openapi/v3-current/pix-lerian-spi.yaml post /balance-locks/{lock_id}/unlock 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}/unlock: post: tags: - Balance Locks summary: Release a cautionary block to the account holder 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 components: schemas: 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 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 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.