curl --request POST \
  --url https://api.example.com/spi/v1/balance-locks/{lock_id}/close \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Actor-Id: <x-actor-id>' \
  --header 'X-Idempotency: <x-idempotency>' \
  --header 'X-Override-Reason: <x-override-reason>' \
  --data '
{
  "end_to_end_id": "D87654321202610271405r4Tn8Wq2Kx6",
  "notes": "devolution failed on the rail, payer repaid by a manual Pix, ticket MED-4821"
}
'

{
  "lock_id": "01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60",
  "status": "SETTLED",
  "pix_end_to_end_id": "D87654321202610271405r4Tn8Wq2Kx6",
  "closed_manually": true,
  "closed_at": "2026-10-27T16:20:00Z"
}

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

Close a cautionary block after a manual return

Marks a PENDING or SETTLING lock SETTLED, with closed_manually true, for a devolution that your institution paid by Pix through Pix Lerian outside the automatic settlement. Pix Lerian sends no Pix. settled_amount records what was paid and counts in what was already returned of the received transaction, so a later settle of another lock is capped to what is left.

X-Actor-Id and X-Override-Reason are required. payment_type is required when you close a PENDING lock. end_to_end_id must name a completed Pix of your institution paid to the payer of the received transaction: a devolution of the received Pix itself or, on a pix_manual lock, a Pix to the payer’s account. Any other Pix, or one that is in flight, rejected or failed, is refused with 422 (PIX-0013). A lock still AWAITING_CREDIT is refused with 409 (PIX-0012). When nothing was paid to the payer, or the payer was repaid through another channel, release the lock instead. Never settle a lock that was already repaid: the devolution would be paid twice.

A failed ledger search or cancel answers 502 (PIX-0652): repeat the call. Pix Lerian records every close in the audit trail. A pix_manual lock closed with a surplus returns it with Return a settlement surplus to the account holder. For a lock opened for a MED infraction (origin_system med-infraction), use Blocks close refund instead: DICT holds MED state that this route cannot see.

POST

balance-locks

{lock_id}

curl --request POST \
  --url https://api.example.com/spi/v1/balance-locks/{lock_id}/close \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Actor-Id: <x-actor-id>' \
  --header 'X-Idempotency: <x-idempotency>' \
  --header 'X-Override-Reason: <x-override-reason>' \
  --data '
{
  "end_to_end_id": "D87654321202610271405r4Tn8Wq2Kx6",
  "notes": "devolution failed on the rail, payer repaid by a manual Pix, ticket MED-4821"
}
'

{
  "lock_id": "01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60",
  "status": "SETTLED",
  "pix_end_to_end_id": "D87654321202610271405r4Tn8Wq2Kx6",
  "closed_manually": true,
  "closed_at": "2026-10-27T16:20:00Z"
}

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

X-Actor-Id

string

required

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

Example:

"backoffice.ops@example.com"

X-Override-Reason

string

required

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:

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

Body

application/json

end_to_end_id

string

required

Externally-executed devolution/transfer end-to-end id

Example:

"D87654321202610271405r4Tn8Wq2Kx6"

notes

string

payment_type

string

Required when closing from PENDING; preserved when SETTLING

Example:

"PIX_REFUND"

settled_amount

string

Amount the manual devolution returned to the payer. Defaults to, and cannot exceed, the lock's effective_amount or, on a SETTLING lock, the amount its settle reserved; a SETTLING pixManual lock takes exactly that amount

Example:

"100.26"

Response

closed_at

string<date-time>

required

Example:

"2026-10-27T16:20:00Z"

closed_manually

boolean

required

Example:

true

lock_id

string

required

Example:

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

pix_end_to_end_id

string

required

Example:

"D87654321202610271405r4Tn8Wq2Kx6"

status

string

required

Example:

"SETTLED"

DICT and Pix keys

Collections and BR Codes

Payments and refunds

Pix Automático API

Error handling

Close a cautionary block after a manual return

Authorizations

Headers

Path Parameters

Body

Response