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