> ## 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. # Confirm a group settlement > Applies the outcome of a group devolution to every lock of the group: `SUCCESS` settles them, and `FAILED` returns them to `PENDING`. Send `SUCCESS` with the `end_to_end_id` of the devolution: the D-prefixed return ID of a `pix_refund` group, or the E-prefixed payment ID of a `pix_manual` group. Any other ID is refused with `409` (`PIX-0012`) and nothing changes. Omit `result` to read the current state of the group without changing it. A retryable `409` (`PIX-0653`) means that the debit of the devolution, or its outcome on the rail, is not confirmed yet: nothing changes, so repeat the call later. A group whose surplus was already returned is refused with `409` (`PIX-0656`) and stays `SETTLING`. A `pix_manual` surplus is returned once, when every lock is `SETTLED`. If that return fails, the group stays `SETTLED` and the answer is `200` without `surplus_midaz_tx_id`; this does not prove that the surplus stayed blocked, because a ledger timeout can have moved it. Check the ledger, then use [Return a settlement surplus to the account holder](/pt/reference/interfaces/pix-lerian/spi/return-a-settlement-surplus-to-the-account-holder). `X-Actor-Id`, `X-Override-Reason` and `X-Override-Ticket` are optional. Sending any of them records the confirmation in the audit trail. For a lock opened for a MED infraction (`origin_system` `med-infraction`), use [Confirm settle refund](/pt/reference/interfaces/pix-lerian/dict/confirm-settle-refund) instead: DICT holds MED state that this route cannot see. ## OpenAPI ````yaml /pt/openapi/v3-current/pix-lerian-spi.yaml post /balance-locks/settle/confirm 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/confirm: post: tags: - Balance Locks summary: Confirm a group settlement description: >- Applies the outcome of a group devolution to every lock of the group: `SUCCESS` settles them, and `FAILED` returns them to `PENDING`. Send `SUCCESS` with the `end_to_end_id` of the devolution: the D-prefixed return ID of a `pix_refund` group, or the E-prefixed payment ID of a `pix_manual` group. Any other ID is refused with `409` (`PIX-0012`) and nothing changes. Omit `result` to read the current state of the group without changing it. A retryable `409` (`PIX-0653`) means that the debit of the devolution, or its outcome on the rail, is not confirmed yet: nothing changes, so repeat the call later. A group whose surplus was already returned is refused with `409` (`PIX-0656`) and stays `SETTLING`. A `pix_manual` surplus is returned once, when every lock is `SETTLED`. If that return fails, the group stays `SETTLED` and the answer is `200` without `surplus_midaz_tx_id`; this does not prove that the surplus stayed blocked, because a ledger timeout can have moved it. Check the ledger, then use [Return a settlement surplus to the account holder](/pt/reference/interfaces/pix-lerian/spi/return-a-settlement-surplus-to-the-account-holder). `X-Actor-Id`, `X-Override-Reason` and `X-Override-Ticket` are optional. Sending any of them records the confirmation in the audit trail. For a lock opened for a MED infraction (`origin_system` `med-infraction`), use [Confirm settle refund](/pt/reference/interfaces/pix-lerian/dict/confirm-settle-refund) instead: DICT holds MED state that this route cannot see. operationId: confirmGroupSettle 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: >- 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 requestBody: content: application/json: examples: failed: summary: >- FAILED: the rail rejected the devolution, every lock goes back to PENDING value: refund_ref: med-2026-000123-group-devolution result: FAILED poll: summary: 'No result: read the group''s current state' value: refund_ref: med-2026-000123-group-devolution success: summary: 'SUCCESS: the rail paid the devolution' value: refund_ref: med-2026-000123-group-devolution result: SUCCESS end_to_end_id: D87654321202610271405g7Bv3Nc9Jw2 schema: $ref: '#/components/schemas/ConfirmGroupSettleBody' required: true responses: '200': content: application/json: example: refund_ref: med-2026-000123-group-devolution payment_type: PIX_REFUND status: SETTLED pix_end_to_end_id: D87654321202610271405g7Bv3Nc9Jw2 original_amount: '150.75' already_settled: '0' settle_amount: '150.75' surplus_amount: '0' settled_at: '2026-10-27T14:06:03Z' schema: $ref: '#/components/schemas/ConfirmGroupSettleResponse' 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 refund_ref (PIX-0002), a result other than SUCCESS or FAILED, SUCCESS without end_to_end_id, an invalid end_to_end_id or an oversized attribution header (PIX-0003), or a body that is not valid JSON (PIX-0010). 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 carries this refund_ref, including a group a FAILED confirm already reset (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 group is not SETTLING, FAILED was reported over a devolution the rail already paid, SUCCESS named an end_to_end_id other than the group's devolution, SUCCESS over a lock whose transfer back to the holder a close the holder paid has in progress, or a concurrent update won (PIX-0012); FAILED while the devolution is still in flight, or either result while the group's debit is unconfirmed, retryable (PIX-0653); FAILED over a group that 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-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: >- FAILED on a pixRefund group whose re-hold, or SUCCESS whose cancel of a left-behind re-hold, finds a blocked ledger account (PIX-0328), a closed one or one whose status forbids sending, which refused the hold (PIX-0332), an account without a ledger alias (PIX-0655), or no blocking account configured for the participant (PIX-0650). '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 confirm 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: >- SUCCESS whose ledger search for, or cancel of, a block's left-behind re-hold failed: every block stays SETTLING, repeat it (PIX-0652). FAILED on a pixRefund group whose re-hold failed in the ledger, or was refused after an automatic retry so it may stand: the blocks not yet reset stay SETTLING, repeat it (PIX-0652). With a detail naming overrides.allowFeeSkip, repeat it once the setting is enabled on the ledger that holds the blocking account. default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error components: schemas: ConfirmGroupSettleBody: additionalProperties: false properties: end_to_end_id: description: Aggregated devolution end-to-end id (required when result=SUCCESS) examples: - D87654321202610271405g7Bv3Nc9Jw2 type: string refund_ref: description: Group key examples: - med-2026-000123-group-devolution type: string result: description: SUCCESS or FAILED; omit to poll current state examples: - SUCCESS type: string required: - refund_ref type: object ConfirmGroupSettleResponse: additionalProperties: false properties: already_settled: examples: - '0.00' type: string failure_reason: examples: - aggregated group devolution reported FAILED by caller type: string original_amount: examples: - '150.75' type: string payment_type: examples: - PIX_REFUND type: string pix_end_to_end_id: examples: - D87654321202610271405g7Bv3Nc9Jw2 type: string refund_ref: examples: - med-2026-000123-group-devolution type: string reset_at: examples: - '2026-10-27T14:06:03Z' format: date-time type: string settle_amount: examples: - '150.75' type: string settled_at: examples: - '2026-10-27T14:06:03Z' format: date-time type: string status: examples: - SETTLED type: string surplus_amount: examples: - '0.00' type: string surplus_midaz_tx_id: description: >- On SETTLED, the Midaz transaction that returned the pixManual group surplus to the customer: made by this confirm once every lock is SETTLED, or already recorded on the group (a replay). Absent when there is no surplus, or when the best-effort return failed -- recover it with POST /balance-locks/{lock_id}/return-surplus on the lock that bears the surplus. examples: - 01a17dae-b16e-7f28-9a03-6b1c4d8e2f75 type: string required: - refund_ref - status 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.