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

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

Body

application/json

amount

string

required

Requested hold amount

Example:

"150.75"

asset

string

required

Asset code (only BRL supported)

Example:

"BRL"

end_to_end_id

string

required

Related Pix transaction end-to-end id

Example:

"E12345678202610271032k7Qm2Xp9Ld4"

external_ref

string

required

Grouping reference (not unique)

Example:

"med-2026-000123"

origin_system

string

required

Calling system/flow discriminator

Example:

"med-infraction"

request_ref

string

required

Idempotency key for this creation (unique per tenant)

Example:

"med-2026-000123-hold-1"

Response

The hold, created now or replayed by request_ref.

created_at

string<date-time>

required

Example:

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

effective_amount

string

required

Example:

"100.26"

lock_id

string

required

Example:

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

midaz_tx_id

string

required

The ledger hold; empty while AWAITING_CREDIT

Example:

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

requested_amount

string

required

Example:

"150.75"

status

string

required

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

Example:

"PENDING"

DICT and Pix keys

Collections and BR Codes

Payments and refunds

Pix Automático API

Error handling

Create a cautionary block

Authorizations

Headers

Body

Response