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

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

X-Actor-Id

string

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

Ejemplo:

"backoffice.ops@example.com"

X-Override-Reason

string

Why the caller is acting

Ejemplo:

"manual devolution paid by Pix"

X-Override-Ticket

string

Ticket reference

Ejemplo:

"MED-4821"

X-Correlation-Id

string

Correlation id

Ejemplo:

"med-2026-000123"

X-Request-Id

string

Request id

Ejemplo:

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

Parámetros de ruta

lock_id

string

requerido

Balance lock UUID

Ejemplo:

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

Respuesta

lock_id

string

requerido

Ejemplo:

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

released_at

string<date-time>

requerido

Ejemplo:

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

status

string

requerido

Ejemplo:

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

Ejemplo:

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

DICT y claves Pix

Cobros y códigos BR

Pagos y devoluciones

API de Pix Automático

Manejo de errores

Release a cautionary block to the account holder

Autorizaciones

Encabezados

Parámetros de ruta

Respuesta