Release a cautionary block to the account holder

curl --request POST \
  --url https://api.example.com/spi/v1/balance-locks/{lock_id}/unlock \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Idempotency: <x-idempotency>'

package main

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

func main() {

	url := "https://api.example.com/spi/v1/balance-locks/{lock_id}/unlock"

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

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	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: 'POST',
  headers: {'X-Idempotency': '<x-idempotency>', Authorization: 'Bearer <token>'}
};

fetch('https://api.example.com/spi/v1/balance-locks/{lock_id}/unlock', 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/{lock_id}/unlock"

headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>"
}

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

print(response.text)

{
  "lock_id": "01a17d06-7910-7b35-9f4e-1c8a2d6e3b57",
  "status": "RELEASED",
  "released_at": "2026-10-27T11:15:30Z"
}

Release a cautionary block to the account holder

Gives the funds of the lock back to the account holder and moves the lock to RELEASED. Funds still on hold have their pending ledger hold cancelled. Funds that a rejected or failed pix_manual settlement already moved to the blocking account are transferred back to the account of the holder in one ledger transfer, reported as release_midaz_tx_id. A released lock cannot be settled.

The lock must be PENDING or AWAITING_CREDIT. A SETTLING lock is refused with 409 (PIX-0653): confirm its settlement first. Any other status is refused with 409 (PIX-0012). An AWAITING_CREDIT lock holds nothing, so Pix Lerian releases it with no ledger call. A lock whose funds sit in the blocking account is refused with 409 (PIX-0656) when any surplus of its payment was already returned. A transfer that fails or whose outcome is unknown answers 502 (PIX-0652): retry the call. A retry is safe at any time and never transfers twice. A release that moved funds out of the blocking account is always recorded in the audit trail. For a lock opened for a MED infraction (origin_system med-infraction), use Release a balance block on an infraction report instead: DICT holds MED state that this route cannot see.

POST

balance-locks

{lock_id}

unlock

Release a cautionary block to the account holder

curl --request POST \
  --url https://api.example.com/spi/v1/balance-locks/{lock_id}/unlock \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Idempotency: <x-idempotency>'

package main

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

func main() {

	url := "https://api.example.com/spi/v1/balance-locks/{lock_id}/unlock"

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

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	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: 'POST',
  headers: {'X-Idempotency': '<x-idempotency>', Authorization: 'Bearer <token>'}
};

fetch('https://api.example.com/spi/v1/balance-locks/{lock_id}/unlock', 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/{lock_id}/unlock"

headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>"
}

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

print(response.text)

{
  "lock_id": "01a17d06-7910-7b35-9f4e-1c8a2d6e3b57",
  "status": "RELEASED",
  "released_at": "2026-10-27T11:15:30Z"
}

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

X-Actor-Id

string

Who is acting. Declared by the caller; not verified against the access token

Example:

"backoffice.ops@example.com"

X-Override-Reason

string

Why the caller is acting

Example:

"manual devolution paid by Pix"

X-Override-Ticket

string

Ticket reference

Example:

"MED-4821"

X-Correlation-Id

string

Correlation id

Example:

"med-2026-000123"

X-Request-Id

string

Request id

Example:

"01a17e29-5302-7c0a-b5e1-94d2f6a83c17"

Path Parameters

lock_id

string

required

Balance lock UUID

Example:

"01a17d06-7910-7b35-9f4e-1c8a2d6e3b57"

Response

lock_id

string

required

Example:

"01a17d06-7910-7b35-9f4e-1c8a2d6e3b57"

released_at

string<date-time>

required

Example:

"2026-10-27T11:15:30Z"

status

string

required

Example:

"RELEASED"

release_midaz_tx_id

string

Ledger transaction that moved the funds from the institution's blocking account back to the account holder, for a lock whose funds a rejected pixManual settle had already moved there. Absent when the release cancelled a pending hold.

Example:

"01a17e12-4c3b-7d61-8b2f-3e9a5c7d1f48"

DICT and Pix keys

Collections and BR Codes

Payments and refunds

Pix Automático API

Error handling

Release a cautionary block to the account holder

Authorizations

Headers

Path Parameters

Response