Create a cautionary block

curl --request POST \
  --url https://api.example.com/spi/v1/balance-locks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "request_ref": "med-2026-000123-hold-1",
  "external_ref": "med-2026-000123",
  "origin_system": "med-infraction",
  "end_to_end_id": "E12345678202610271032k7Qm2Xp9Ld4",
  "amount": "150.75",
  "asset": "BRL"
}
'

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"request_ref\": \"med-2026-000123-hold-1\",\n  \"external_ref\": \"med-2026-000123\",\n  \"origin_system\": \"med-infraction\",\n  \"end_to_end_id\": \"E12345678202610271032k7Qm2Xp9Ld4\",\n  \"amount\": \"150.75\",\n  \"asset\": \"BRL\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    request_ref: 'med-2026-000123-hold-1',
    external_ref: 'med-2026-000123',
    origin_system: 'med-infraction',
    end_to_end_id: 'E12345678202610271032k7Qm2Xp9Ld4',
    amount: '150.75',
    asset: 'BRL'
  })
};

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

import requests

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

payload = {
    "request_ref": "med-2026-000123-hold-1",
    "external_ref": "med-2026-000123",
    "origin_system": "med-infraction",
    "end_to_end_id": "E12345678202610271032k7Qm2Xp9Ld4",
    "amount": "150.75",
    "asset": "BRL"
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "lock_id": "01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60",
  "midaz_tx_id": "01a17cf3-133d-7a52-8e19-0c4b6d2f7a91",
  "status": "PENDING",
  "requested_amount": "150.75",
  "effective_amount": "100.26",
  "created_at": "2026-10-27T10:41:07Z"
}

{
  "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-0013",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "The operation could not be processed due to a business rule violation.",
  "code": "PIX-0013"
}

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

Create a cautionary block

Places a cautionary block (MED 2.0) on the funds of a Pix that your institution received. Pix Lerian creates a pending ledger transaction that moves the funds from the available balance of the credited account to the blocking account. The amount held is the smaller of the requested amount and the available balance: effective_amount is what was held, and it can be lower than requested_amount.

The blocking account of your institution must be configured. An inbound Pix transfer with this end_to_end_id must be completed, with available balance on the credited account, or have its ledger credit parked. For a Pix whose credit is parked, the lock holds at once (PENDING) when the ledger already lists that credit. Otherwise the lock is stored as AWAITING_CREDIT: nothing is held yet, and the credit of the Pix holds the funds before it completes the transfer.

request_ref identifies the creation. A replay with the same payload returns the existing lock with 201; the same request_ref with another payload is refused with 409 (PIX-0012). Another hold on the same transaction needs another request_ref. A retry after a failed create (502) reuses the amount that the failed attempt computed, so a hold that the attempt placed becomes this lock. A retry whose earlier hold no longer stands is refused with 422 (PIX-0013).

Next, return the funds to the payer with Settle a cautionary block or Settle every cautionary block of a Pix, or give them back to the account holder with Release a cautionary block.

POST

balance-locks

Create a cautionary block

curl --request POST \
  --url https://api.example.com/spi/v1/balance-locks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "request_ref": "med-2026-000123-hold-1",
  "external_ref": "med-2026-000123",
  "origin_system": "med-infraction",
  "end_to_end_id": "E12345678202610271032k7Qm2Xp9Ld4",
  "amount": "150.75",
  "asset": "BRL"
}
'

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"request_ref\": \"med-2026-000123-hold-1\",\n  \"external_ref\": \"med-2026-000123\",\n  \"origin_system\": \"med-infraction\",\n  \"end_to_end_id\": \"E12345678202610271032k7Qm2Xp9Ld4\",\n  \"amount\": \"150.75\",\n  \"asset\": \"BRL\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    request_ref: 'med-2026-000123-hold-1',
    external_ref: 'med-2026-000123',
    origin_system: 'med-infraction',
    end_to_end_id: 'E12345678202610271032k7Qm2Xp9Ld4',
    amount: '150.75',
    asset: 'BRL'
  })
};

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

import requests

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

payload = {
    "request_ref": "med-2026-000123-hold-1",
    "external_ref": "med-2026-000123",
    "origin_system": "med-infraction",
    "end_to_end_id": "E12345678202610271032k7Qm2Xp9Ld4",
    "amount": "150.75",
    "asset": "BRL"
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "lock_id": "01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60",
  "midaz_tx_id": "01a17cf3-133d-7a52-8e19-0c4b6d2f7a91",
  "status": "PENDING",
  "requested_amount": "150.75",
  "effective_amount": "100.26",
  "created_at": "2026-10-27T10:41:07Z"
}

{
  "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-0013",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "The operation could not be processed due to a business rule violation.",
  "code": "PIX-0013"
}

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

amount

string

requerido

Requested hold amount

Ejemplo:

"150.75"

asset

string

requerido

Asset code (only BRL supported)

Ejemplo:

"BRL"

end_to_end_id

string

requerido

Related Pix transaction end-to-end id

Ejemplo:

"E12345678202610271032k7Qm2Xp9Ld4"

external_ref

string

requerido

Grouping reference (not unique)

Ejemplo:

"med-2026-000123"

origin_system

string

requerido

Calling system/flow discriminator

Ejemplo:

"med-infraction"

request_ref

string

requerido

Idempotency key for this creation (unique per tenant)

Ejemplo:

"med-2026-000123-hold-1"

Respuesta

The hold, created now or replayed by request_ref.

created_at

string<date-time>

requerido

Ejemplo:

"2026-10-27T10:41:07Z"

effective_amount

string

requerido

Ejemplo:

"100.26"

lock_id

string

requerido

Ejemplo:

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

midaz_tx_id

string

requerido

The ledger hold; empty while AWAITING_CREDIT

Ejemplo:

"01a17cf3-133d-7a52-8e19-0c4b6d2f7a91"

requested_amount

string

requerido

Ejemplo:

"150.75"

status

string

requerido

PENDING, or AWAITING_CREDIT while the Pix's ledger credit is parked and nothing is held yet

Ejemplo:

"PENDING"

DICT y claves Pix

Cobros y códigos BR

Pagos y devoluciones

API de Pix Automático

Manejo de errores

Create a cautionary block

Autorizaciones

Encabezados

Cuerpo

Respuesta