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

Authorizations

Authorization

string

header

required

JWT bearer token issued by the identity provider.

Headers

X-Idempotency

string

required

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

Path Parameters

lock_id

string

required

Balance lock UUID

Example:

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

Body

application/json

original_amount

string

required

Original transaction face value (ceiling)

Example:

"150.75"

refund_ref

string

required

Idempotency key for this settle

Example:

"med-2026-000123-devolution"

pix_manual

object

Show child attributes

pix_refund

object

Show child attributes

Response

already_settled

string

required

Example:

"0.00"

initiated_at

string<date-time>

required

Example:

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

lock_id

string

required

Example:

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

original_amount

string

required

Example:

"150.75"

payment_type

string

required

Example:

"PIX_MANUAL"

requested_amount

string

required

Example:

"80.13"

settle_amount

string

required

Example:

"80.13"

status

string

required

Example:

"SETTLING"

surplus_amount

string

required

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.

Example:

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

Example:

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

DICT and Pix keys

Collections and BR Codes

Payments and refunds

Pix Automático API

Error handling

Settle a cautionary block

Authorizations

Headers

Path Parameters

Body

Response