Return a settlement surplus to the account holder

curl --request POST \
  --url https://api.example.com/spi/v1/balance-locks/{lock_id}/return-surplus \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Actor-Id: <x-actor-id>' \
  --header 'X-Idempotency: <x-idempotency>' \
  --header 'X-Override-Reason: <x-override-reason>'

package main

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

func main() {

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

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

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("X-Actor-Id", "<x-actor-id>")
	req.Header.Add("X-Override-Reason", "<x-override-reason>")
	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>',
    'X-Actor-Id': '<x-actor-id>',
    'X-Override-Reason': '<x-override-reason>',
    Authorization: 'Bearer <token>'
  }
};

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

headers = {
    "X-Idempotency": "<x-idempotency>",
    "X-Actor-Id": "<x-actor-id>",
    "X-Override-Reason": "<x-override-reason>",
    "Authorization": "Bearer <token>"
}

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

print(response.text)

{
  "lock_id": "01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60",
  "surplus_amount": "0",
  "surplus_midaz_tx_id": "01a17dae-b16e-7f28-9a03-6b1c4d8e2f75",
  "returned_at": "2026-10-27T15:02:41Z"
}

{
  "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-0011",
  "title": "Not Found",
  "status": 404,
  "detail": "No entity was found for the given ID. Please make sure to use the correct ID.",
  "code": "PIX-0011"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0653",
  "title": "Conflict",
  "status": 409,
  "detail": "The balance lock's settlement is not final yet; retry once it is.",
  "code": "PIX-0653"
}

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

{
  "type": "https://errors.lerian.studio/v1/PIX-0655",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "An account required for this operation has no resolvable alias in the ledger.",
  "code": "PIX-0655"
}

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

Return a settlement surplus to the account holder

Moves a pix_manual surplus from the blocking account back to the account holder. Use it when a pix_manual settlement paid the payer less than the lock held and the surplus did not go back to the holder: the lock was closed manually, or the surplus return of a settlement confirmation answered without surplus_midaz_tx_id. That answer does not prove that the surplus stayed blocked, because a ledger timeout can have moved it. Before you call, search the ledger for a transaction whose metadata carries the lock_id and an origin of balance-lock-surplus, balance-lock-group-surplus or balance-lock-surplus-recovery. Call only when none exists.

The lock must be SETTLED: a SETTLING lock with a surplus is refused with 409 (PIX-0653), so confirm the settlement first. X-Actor-Id and X-Override-Reason are required. The call is idempotent: a lock with no surplus, or whose surplus was already returned, answers 200 with surplus_amount 0. After a 5xx that returns no surplus_midaz_tx_id, the surplus can have moved: check the ledger before you retry. For a group settlement, call it once for each lock_id. Pix Lerian records every call in the audit trail.

POST

balance-locks

{lock_id}

return-surplus

Return a settlement surplus to the account holder

curl --request POST \
  --url https://api.example.com/spi/v1/balance-locks/{lock_id}/return-surplus \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Actor-Id: <x-actor-id>' \
  --header 'X-Idempotency: <x-idempotency>' \
  --header 'X-Override-Reason: <x-override-reason>'

package main

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

func main() {

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

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

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("X-Actor-Id", "<x-actor-id>")
	req.Header.Add("X-Override-Reason", "<x-override-reason>")
	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>',
    'X-Actor-Id': '<x-actor-id>',
    'X-Override-Reason': '<x-override-reason>',
    Authorization: 'Bearer <token>'
  }
};

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

headers = {
    "X-Idempotency": "<x-idempotency>",
    "X-Actor-Id": "<x-actor-id>",
    "X-Override-Reason": "<x-override-reason>",
    "Authorization": "Bearer <token>"
}

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

print(response.text)

{
  "lock_id": "01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60",
  "surplus_amount": "0",
  "surplus_midaz_tx_id": "01a17dae-b16e-7f28-9a03-6b1c4d8e2f75",
  "returned_at": "2026-10-27T15:02:41Z"
}

{
  "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-0011",
  "title": "Not Found",
  "status": 404,
  "detail": "No entity was found for the given ID. Please make sure to use the correct ID.",
  "code": "PIX-0011"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0653",
  "title": "Conflict",
  "status": 409,
  "detail": "The balance lock's settlement is not final yet; retry once it is.",
  "code": "PIX-0653"
}

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

{
  "type": "https://errors.lerian.studio/v1/PIX-0655",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "An account required for this operation has no resolvable alias in the ledger.",
  "code": "PIX-0655"
}

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

X-Actor-Id

string

requerido

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

Ejemplo:

"backoffice.ops@example.com"

X-Override-Reason

string

requerido

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:

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

Respuesta

lock_id

string

requerido

Ejemplo:

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

returned_at

string<date-time>

requerido

Ejemplo:

"2026-10-27T15:02:41Z"

surplus_amount

string

requerido

Ejemplo:

"0.00"

surplus_midaz_tx_id

string

Midaz transaction that moved the surplus: created by this call, or already recorded on the lock or, for a group settle, on another lock of the same group (then surplus_amount is 0). Absent when no surplus transfer exists.

Ejemplo:

"01a17dae-b16e-7f28-9a03-6b1c4d8e2f75"

DICT y claves Pix

Cobros y códigos BR

Pagos y devoluciones

API de Pix Automático

Manejo de errores

Return a settlement surplus to the account holder

Autorizaciones

Encabezados

Parámetros de ruta

Respuesta