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

Autorizações

Authorization

string

header

obrigatório

JWT bearer token issued by the identity provider.

Cabeçalhos

X-Idempotency

string

obrigatório

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 caminho

lock_id

string

obrigatório

Balance lock UUID

Exemplo:

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

Corpo

application/json

original_amount

string

obrigatório

Original transaction face value (ceiling)

Exemplo:

"150.75"

refund_ref

string

obrigatório

Idempotency key for this settle

Exemplo:

"med-2026-000123-devolution"

pix_manual

object

Show child attributes

pix_refund

object

Show child attributes

Resposta

already_settled

string

obrigatório

Exemplo:

"0.00"

initiated_at

string<date-time>

obrigatório

Exemplo:

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

lock_id

string

obrigatório

Exemplo:

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

original_amount

string

obrigatório

Exemplo:

"150.75"

payment_type

string

obrigatório

Exemplo:

"PIX_MANUAL"

requested_amount

string

obrigatório

Exemplo:

"80.13"

settle_amount

string

obrigatório

Exemplo:

"80.13"

status

string

obrigatório

Exemplo:

"SETTLING"

surplus_amount

string

obrigatório

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.

Exemplo:

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

Exemplo:

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

DICT e chaves Pix

Cobranças e BR Codes

Pagamentos e devoluções

API de Pix Automático

Tratamento de erros

Settle a cautionary block

Autorizações

Cabeçalhos

Parâmetros de caminho

Corpo

Resposta