curl --request POST \
  --url https://api.example.com/spi/v1/balance-locks/{lock_id}/settle \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "refund_ref": "med-2026-000123-devolution",
  "original_amount": "150.75",
  "pix_manual": {
    "ispb": "12345678",
    "branch": "0001",
    "account": "1234567",
    "account_type": "CC",
    "document": "12345678909",
    "amount": "80.13",
    "asset": "BRL",
    "description": "MED devolution to the payer"
  }
}
'

{
  "lock_id": "01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60",
  "payment_type": "PIX_MANUAL",
  "status": "SETTLING",
  "original_amount": "150.75",
  "requested_amount": "80.13",
  "already_settled": "0",
  "settle_amount": "80.13",
  "surplus_amount": "20.13",
  "initiated_at": "2026-10-27T14:05:12Z"
}

{
  "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-0654",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "There is nothing left to settle for this block.",
  "code": "PIX-0654"
}

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

Settle a cautionary block

Starts the return of the funds of one lock to the payer and moves the lock to SETTLING. With pix_refund, Pix Lerian cancels the ledger hold and sends a return (pacs.004) of the original transaction. With pix_manual, it commits the hold to the blocking account and pays one Pix (pacs.008) from there to the bank account that you give. To return every lock of the transaction in one devolution, use Settle every cautionary block of a Pix.

The lock must be PENDING (AWAITING_CREDIT is refused with 409, PIX-0012). original_amount is the amount of the received transaction: a higher amount, or a transaction that is not found, is refused with 422 (PIX-0013). The amount settled is the smallest of the requested amount, what is left to settle and the effective_amount of the lock. The call is idempotent by refund_ref: a refund_ref already bound to other locks is refused with 400 (PIX-0003). A lock whose surplus was already returned is refused with 409 (PIX-0656). A dispatch that fails without proof that the devolution was not sent (a timeout, a 5xx) answers success, and the lock stays SETTLING until the outcome is confirmed. A pix_manual surplus is returned when the settlement is confirmed, not by this call.

When the outcome is known, call Confirm a cautionary block settlement. For a lock opened for a MED infraction (origin_system med-infraction), use Settle refund instead: DICT holds MED state that this route cannot see.

POST

balance-locks

{lock_id}

settle

curl --request POST \
  --url https://api.example.com/spi/v1/balance-locks/{lock_id}/settle \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "refund_ref": "med-2026-000123-devolution",
  "original_amount": "150.75",
  "pix_manual": {
    "ispb": "12345678",
    "branch": "0001",
    "account": "1234567",
    "account_type": "CC",
    "document": "12345678909",
    "amount": "80.13",
    "asset": "BRL",
    "description": "MED devolution to the payer"
  }
}
'

{
  "lock_id": "01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60",
  "payment_type": "PIX_MANUAL",
  "status": "SETTLING",
  "original_amount": "150.75",
  "requested_amount": "80.13",
  "already_settled": "0",
  "settle_amount": "80.13",
  "surplus_amount": "20.13",
  "initiated_at": "2026-10-27T14:05:12Z"
}

{
  "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-0654",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "There is nothing left to settle for this block.",
  "code": "PIX-0654"
}

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

Parámetros de ruta

lock_id

string

requerido

Balance lock UUID

Ejemplo:

"01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60"

Cuerpo

application/json

original_amount

string

requerido

Original transaction face value (ceiling)

Ejemplo:

"150.75"

refund_ref

string

requerido

Idempotency key for this settle

Ejemplo:

"med-2026-000123-devolution"

pix_manual

object

Show child attributes

pix_refund

object

Show child attributes

Respuesta

already_settled

string

requerido

Ejemplo:

"0.00"

initiated_at

string<date-time>

requerido

Ejemplo:

"2026-10-27T14:05:12Z"

lock_id

string

requerido

Ejemplo:

"01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60"

original_amount

string

requerido

Ejemplo:

"150.75"

payment_type

string

requerido

Ejemplo:

"PIX_MANUAL"

requested_amount

string

requerido

Ejemplo:

"80.13"

settle_amount

string

requerido

Ejemplo:

"80.13"

status

string

requerido

Ejemplo:

"SETTLING"

surplus_amount

string

requerido

pixManual surplus (the lock's effective amount minus settle_amount) that the settle confirmation returns to the customer once the lock is SETTLED; nothing is returned by this call. Always 0 for pixRefund.

Ejemplo:

"20.13"

surplus_midaz_tx_id

string

Not filled: the surplus is returned by the settle confirmation, whose response carries the transaction id. Kept in the schema for compatibility.

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

Settle a cautionary block

Autorizaciones

Encabezados

Parámetros de ruta

Cuerpo

Respuesta