List cautionary blocks

curl --request GET \
  --url https://api.example.com/spi/v1/balance-locks \
  --header 'Authorization: Bearer <token>'

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/spi/v1/balance-locks"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.example.com/spi/v1/balance-locks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "items": [
    {
      "lock_id": "01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60",
      "origin_system": "med-infraction",
      "external_ref": "med-2026-000123",
      "end_to_end_id": "E12345678202610271032k7Qm2Xp9Ld4",
      "status": "PENDING",
      "requested_amount": "150.75",
      "effective_amount": "100.26",
      "settled_amount": null,
      "payment_type": null,
      "pix_end_to_end_id": null,
      "settling_at": null,
      "surplus_midaz_tx_id": null,
      "created_at": "2026-10-27T10:41:07Z",
      "updated_at": "2026-10-27T10:41:07Z"
    },
    {
      "lock_id": "01a17cf5-983a-7d13-a4c8-2e9f51b06d37",
      "origin_system": "med-infraction",
      "external_ref": "med-2026-000123",
      "end_to_end_id": "E12345678202610271032k7Qm2Xp9Ld4",
      "status": "PENDING",
      "requested_amount": "50.49",
      "effective_amount": "50.49",
      "settled_amount": null,
      "payment_type": null,
      "pix_end_to_end_id": null,
      "settling_at": null,
      "surplus_midaz_tx_id": null,
      "created_at": "2026-10-27T10:43:52Z",
      "updated_at": "2026-10-27T10:43:52Z"
    }
  ],
  "next_cursor": null
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0003",
  "title": "Bad Request",
  "status": 400,
  "detail": "Your request contains one or more fields with an invalid data type.",
  "code": "PIX-0003"
}

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

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

List cautionary blocks

Lists the cautionary blocks of your institution, oldest update first. Filter by origin_system, status (repeatable), updated_before and external_ref. The list uses cursor pagination: pass next_cursor as cursor to read the next page; next_cursor is null on the last page. limit defaults to 20 and is at most 100. A non-integer limit is refused with 400 (PIX-0020).

The status of a lock tells which operation applies. A PENDING lock can be settled, released or closed. A SETTLING lock waits for the confirmation of its settlement, and one whose devolution failed can also be closed. An AWAITING_CREDIT lock waits for the parked credit of its Pix and can only be released.

GET

balance-locks

curl --request GET \
  --url https://api.example.com/spi/v1/balance-locks \
  --header 'Authorization: Bearer <token>'

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/spi/v1/balance-locks"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.example.com/spi/v1/balance-locks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "items": [
    {
      "lock_id": "01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60",
      "origin_system": "med-infraction",
      "external_ref": "med-2026-000123",
      "end_to_end_id": "E12345678202610271032k7Qm2Xp9Ld4",
      "status": "PENDING",
      "requested_amount": "150.75",
      "effective_amount": "100.26",
      "settled_amount": null,
      "payment_type": null,
      "pix_end_to_end_id": null,
      "settling_at": null,
      "surplus_midaz_tx_id": null,
      "created_at": "2026-10-27T10:41:07Z",
      "updated_at": "2026-10-27T10:41:07Z"
    },
    {
      "lock_id": "01a17cf5-983a-7d13-a4c8-2e9f51b06d37",
      "origin_system": "med-infraction",
      "external_ref": "med-2026-000123",
      "end_to_end_id": "E12345678202610271032k7Qm2Xp9Ld4",
      "status": "PENDING",
      "requested_amount": "50.49",
      "effective_amount": "50.49",
      "settled_amount": null,
      "payment_type": null,
      "pix_end_to_end_id": null,
      "settling_at": null,
      "surplus_midaz_tx_id": null,
      "created_at": "2026-10-27T10:43:52Z",
      "updated_at": "2026-10-27T10:43:52Z"
    }
  ],
  "next_cursor": null
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0003",
  "title": "Bad Request",
  "status": 400,
  "detail": "Your request contains one or more fields with an invalid data type.",
  "code": "PIX-0003"
}

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

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

Parámetros de consulta

origin_system

string

Scope of the calling consumer (e.g. med-infraction). Omit to list across every origin_system.

status

string[] | null

Filter by status (repeatable): PENDING, SETTLING, RELEASED, SETTLED, AWAITING_CREDIT

Ejemplo:

["PENDING"]

updated_before

string

Only balance locks with updated_at before this RFC 3339 timestamp

external_ref

string

Restrict to a single grouping operation

limit

string

Page size (1-100, default 20)

Ejemplo:

"20"

cursor

string

Opaque cursor returned by the previous page

Respuesta

items

object[] | null

requerido

Show child attributes

next_cursor

string | null

requerido

DICT y claves Pix

Cobros y códigos BR

Pagos y devoluciones

API de Pix Automático

Manejo de errores

List cautionary blocks

Autorizaciones

Parámetros de consulta

Respuesta