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