curl --request POST \
  --url https://api.example.com/spi/v1/balance-locks/settle \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "refund_ref": "med-2026-000123-group-devolution",
  "lock_ids": [
    "01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60",
    "01a17cf5-983a-7d13-a4c8-2e9f51b06d37"
  ],
  "original_amount": "150.75",
  "original_end_to_end_id": "E12345678202610271032k7Qm2Xp9Ld4",
  "pix_manual": {
    "ispb": "12345678",
    "branch": "0001",
    "account": "1234567",
    "account_type": "CC",
    "document": "12345678909",
    "asset": "BRL",
    "description": "MED devolution to the payer"
  }
}
'

{
  "refund_ref": "med-2026-000123-group-devolution",
  "payment_type": "PIX_REFUND",
  "status": "SETTLING",
  "original_amount": "150.75",
  "already_settled": "0",
  "settle_amount": "150.75",
  "surplus_amount": "0",
  "lock_ids": [
    "01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60",
    "01a17cf5-983a-7d13-a4c8-2e9f51b06d37"
  ],
  "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-0012",
  "title": "Conflict",
  "status": 409,
  "detail": "The entity already exists or conflicts with an existing resource.",
  "code": "PIX-0012"
}

{
  "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 every cautionary block of a Pix

Returns to the payer, in one devolution, the funds that the locks of one received Pix hold, and moves every lock to SETTLING. With pix_refund, Pix Lerian sends one return (pacs.004) of the original transaction. With pix_manual, it pays one Pix (pacs.008) from the blocking account to the bank account that you give. Pix Lerian derives settle_amount from the locks and the ceiling: you do not send it.

Every lock in lock_ids must be PENDING (a lock still AWAITING_CREDIT is refused with 409, PIX-0012), belong to your institution and share the same end_to_end_id and external_ref. original_amount must not exceed the received transaction: Quote the amount left to settle tells what is left. 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.

The group settles all or nothing: a group with a lock whose surplus was already returned is refused with 409 (PIX-0656) before any lock is reserved. The call is idempotent by refund_ref, and a retry must send the same lock_ids: a refund_ref already bound to a lock outside lock_ids is refused with 400 (PIX-0003). A dispatch that fails without proof that the devolution was not sent (a timeout, a 5xx) answers success, and every 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 rail reports the outcome of the devolution, send it with Confirm a group settlement.

POST

balance-locks

settle

curl --request POST \
  --url https://api.example.com/spi/v1/balance-locks/settle \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "refund_ref": "med-2026-000123-group-devolution",
  "lock_ids": [
    "01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60",
    "01a17cf5-983a-7d13-a4c8-2e9f51b06d37"
  ],
  "original_amount": "150.75",
  "original_end_to_end_id": "E12345678202610271032k7Qm2Xp9Ld4",
  "pix_manual": {
    "ispb": "12345678",
    "branch": "0001",
    "account": "1234567",
    "account_type": "CC",
    "document": "12345678909",
    "asset": "BRL",
    "description": "MED devolution to the payer"
  }
}
'

{
  "refund_ref": "med-2026-000123-group-devolution",
  "payment_type": "PIX_REFUND",
  "status": "SETTLING",
  "original_amount": "150.75",
  "already_settled": "0",
  "settle_amount": "150.75",
  "surplus_amount": "0",
  "lock_ids": [
    "01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60",
    "01a17cf5-983a-7d13-a4c8-2e9f51b06d37"
  ],
  "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-0012",
  "title": "Conflict",
  "status": 409,
  "detail": "The entity already exists or conflicts with an existing resource.",
  "code": "PIX-0012"
}

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

Cuerpo

application/json

lock_ids

string[] | null

requerido

Concrete block ids to settle together

Ejemplo:

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

original_amount

string

requerido

Contested transaction face value (ceiling)

Ejemplo:

"150.75"

original_end_to_end_id

string

requerido

Contested transaction end-to-end id

Ejemplo:

"E12345678202610271032k7Qm2Xp9Ld4"

refund_ref

string

requerido

Group key shared by the N blocks

Ejemplo:

"med-2026-000123-group-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_ids

string[] | null

requerido

original_amount

string

requerido

Ejemplo:

"150.75"

payment_type

string

requerido

Ejemplo:

"PIX_REFUND"

refund_ref

string

requerido

Ejemplo:

"med-2026-000123-group-devolution"

settle_amount

string

requerido

Ejemplo:

"150.75"

status

string

requerido

Ejemplo:

"SETTLING"

surplus_amount

string

requerido

pixManual group surplus (soma_efetiva minus settle_amount) that the SUCCESS group confirm returns once every lock is SETTLED; nothing is returned by this call. Always 0 for pixRefund.

Ejemplo:

"0.00"

DICT y claves Pix

Cobros y códigos BR

Pagos y devoluciones

API de Pix Automático

Manejo de errores

Settle every cautionary block of a Pix

Autorizaciones

Encabezados

Cuerpo

Respuesta