curl --request POST \
  --url https://api.example.com/spi/v1/balance-locks/settle/confirm \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "refund_ref": "med-2026-000123-group-devolution",
  "result": "FAILED"
}
'

{
  "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"
}

{
  "code": "PIX-0030",
  "title": "Idempotency Key Required",
  "message": "The X-Idempotency header is required for this operation and must be within the accepted length."
}

{
  "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"
}

{
  "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"
}

{
  "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."
}

{
  "code": "PIX-0016",
  "title": "Unsupported Media Type",
  "message": "The request body must be sent with Content-Type: application/json."
}

{
  "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"
}

{
  "code": "PIX-0000",
  "title": "Internal Server Error",
  "message": "The server encountered an unexpected error. Please try again later."
}

{
  "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"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

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.

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 instead: DICT holds MED state that this route cannot see.

POST

balance-locks

settle

confirm

curl --request POST \
  --url https://api.example.com/spi/v1/balance-locks/settle/confirm \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "refund_ref": "med-2026-000123-group-devolution",
  "result": "FAILED"
}
'

{
  "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"
}

{
  "code": "PIX-0030",
  "title": "Idempotency Key Required",
  "message": "The X-Idempotency header is required for this operation and must be within the accepted length."
}

{
  "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"
}

{
  "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"
}

{
  "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."
}

{
  "code": "PIX-0016",
  "title": "Unsupported Media Type",
  "message": "The request body must be sent with Content-Type: application/json."
}

{
  "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"
}

{
  "code": "PIX-0000",
  "title": "Internal Server Error",
  "message": "The server encountered an unexpected error. Please try again later."
}

{
  "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"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Autorizaciones

Authorization

string

header

requerido

JWT bearer token issued by the identity provider.

Encabezados

X-Idempotency

string

requerido

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.

Required string length: 1 - 64

X-Actor-Id

string

Who is acting. Declared by the caller; not verified against the access token

Ejemplo:

"backoffice.ops@example.com"

X-Override-Reason

string

Why the caller is acting

Ejemplo:

"manual devolution paid by Pix"

X-Override-Ticket

string

Ticket reference

Ejemplo:

"MED-4821"

X-Correlation-Id

string

Correlation id

Ejemplo:

"med-2026-000123"

X-Request-Id

string

Request id

Ejemplo:

"01a17e29-5302-7c0a-b5e1-94d2f6a83c17"

Cuerpo

application/json

refund_ref

string

requerido

Group key

Ejemplo:

"med-2026-000123-group-devolution"

end_to_end_id

string

Aggregated devolution end-to-end id (required when result=SUCCESS)

Ejemplo:

"D87654321202610271405g7Bv3Nc9Jw2"

result

string

SUCCESS or FAILED; omit to poll current state

Ejemplo:

"SUCCESS"

Respuesta

refund_ref

string

requerido

Ejemplo:

"med-2026-000123-group-devolution"

status

string

requerido

Ejemplo:

"SETTLED"

already_settled

string

Ejemplo:

"0.00"

failure_reason

string

Ejemplo:

"aggregated group devolution reported FAILED by caller"

original_amount

string

Ejemplo:

"150.75"

payment_type

string

Ejemplo:

"PIX_REFUND"

pix_end_to_end_id

string

Ejemplo:

"D87654321202610271405g7Bv3Nc9Jw2"

reset_at

string<date-time>

Ejemplo:

"2026-10-27T14:06:03Z"

settle_amount

string

Ejemplo:

"150.75"

settled_at

string<date-time>

Ejemplo:

"2026-10-27T14:06:03Z"

surplus_amount

string

Ejemplo:

"0.00"

surplus_midaz_tx_id

string

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.

Ejemplo:

"01a17dae-b16e-7f28-9a03-6b1c4d8e2f75"

DICT y claves Pix

Cobros y códigos BR

Pagos y devoluciones

API de Pix Automático

Manejo de errores

Confirm a group settlement

Autorizaciones

Encabezados

Cuerpo

Respuesta