Release the settlement claim on a stuck scheduled debit

curl --request POST \
  --url https://api.example.com/pixauto/v1/payer/scheduled-payments/{scheduled_payment_id}/unblock \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Account-Id: <x-account-id>' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "actorId": "ops-maria",
  "overrideReason": "settlement stuck since the morning window",
  "overrideTicket": "OPS-4711"
}
'

package main

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

func main() {

	url := "https://api.example.com/pixauto/v1/payer/scheduled-payments/{scheduled_payment_id}/unblock"

	payload := strings.NewReader("{\n  \"actorId\": \"ops-maria\",\n  \"overrideReason\": \"settlement stuck since the morning window\",\n  \"overrideTicket\": \"OPS-4711\"\n}")

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

	req.Header.Add("X-Account-Id", "<x-account-id>")
	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-Account-Id': '<x-account-id>',
    'X-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    actorId: 'ops-maria',
    overrideReason: 'settlement stuck since the morning window',
    overrideTicket: 'OPS-4711'
  })
};

fetch('https://api.example.com/pixauto/v1/payer/scheduled-payments/{scheduled_payment_id}/unblock', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/pixauto/v1/payer/scheduled-payments/{scheduled_payment_id}/unblock"

payload = {
    "actorId": "ops-maria",
    "overrideReason": "settlement stuck since the morning window",
    "overrideTicket": "OPS-4711"
}
headers = {
    "X-Account-Id": "<x-account-id>",
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "evidence": "NOT_ON_RAIL",
  "releasedOperationId": "settlement-dispatch-2026-09-10-org-a",
  "scheduledPaymentId": "0198f3a2-1c4e-7c8b-9d1e-2f3a4b5c6d40",
  "status": "SCHEDULED",
  "unblockedAt": "2026-09-10T14:00:00Z"
}

{
  "code": "PIX-0142",
  "message": "claim_id is required",
  "title": "Invalid Claim Request",
  "fields": {},
  "headers": {},
  "paths": {},
  "query_params": {},
  "raw": {
    "message": "upstream provider returned 503",
    "status": 123
  }
}

{
  "code": "PIX-0010",
  "message": "The request could not be processed due to a client-side error.",
  "title": "Client Error"
}

{
  "code": "PIX-0010",
  "message": "The request could not be processed due to a client-side error.",
  "title": "Client Error"
}

{
  "code": "PIX-0142",
  "message": "claim_id is required",
  "title": "Invalid Claim Request",
  "fields": {},
  "headers": {},
  "paths": {},
  "query_params": {},
  "raw": {
    "message": "upstream provider returned 503",
    "status": 123
  }
}

{
  "code": "PIX-0142",
  "message": "claim_id is required",
  "title": "Invalid Claim Request",
  "fields": {},
  "headers": {},
  "paths": {},
  "query_params": {},
  "raw": {
    "message": "upstream provider returned 503",
    "status": 123
  }
}

{
  "code": "PIX-0142",
  "message": "claim_id is required",
  "title": "Invalid Claim Request",
  "fields": {},
  "headers": {},
  "paths": {},
  "query_params": {},
  "raw": {
    "message": "upstream provider returned 503",
    "status": 123
  }
}

{
  "code": "PIX-0016",
  "message": "The request body must be sent with Content-Type: application/json.",
  "title": "Unsupported Media Type"
}

{
  "code": "PIX-0000",
  "message": "The server encountered an unexpected error. Please try again later.",
  "title": "Internal Server Error"
}

{
  "code": "PIX-0142",
  "message": "claim_id is required",
  "title": "Invalid Claim Request",
  "fields": {},
  "headers": {},
  "paths": {},
  "query_params": {},
  "raw": {
    "message": "upstream provider returned 503",
    "status": 123
  }
}

Release the settlement claim on a stuck scheduled debit

Releases the settlement claim on ONE scheduled debit whose settlement attempt went out and never got an outcome, so the debit becomes eligible for a further attempt.

THE SPI DECIDES, NOT THE CALLER. The request has no field to state what happened. Pix Lerian releases the debit only when nothing was sent, or when the SPI has no record of the attempt or rejected it and the ledger entry was reverted. Any other answer refuses the release with PIX-0827, including when the SPI cannot be asked.

The attempt must be at least 2 minutes old. The response names which of the three cases applied.

NOTHING IS CANCELLED. The charge, the schedule and the authorization stay as they are, and the receiving PSP is told nothing. To stop a charge, use POST /v1/payer/scheduled-payments//cancel instead.

The caller needs the scheduled-payment-recovery permission with the post action. The permission that allows the cancel operation does not grant it.

POST

payer

scheduled-payments

{scheduled_payment_id}

unblock

Release the settlement claim on a stuck scheduled debit

curl --request POST \
  --url https://api.example.com/pixauto/v1/payer/scheduled-payments/{scheduled_payment_id}/unblock \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Account-Id: <x-account-id>' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "actorId": "ops-maria",
  "overrideReason": "settlement stuck since the morning window",
  "overrideTicket": "OPS-4711"
}
'

package main

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

func main() {

	url := "https://api.example.com/pixauto/v1/payer/scheduled-payments/{scheduled_payment_id}/unblock"

	payload := strings.NewReader("{\n  \"actorId\": \"ops-maria\",\n  \"overrideReason\": \"settlement stuck since the morning window\",\n  \"overrideTicket\": \"OPS-4711\"\n}")

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

	req.Header.Add("X-Account-Id", "<x-account-id>")
	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-Account-Id': '<x-account-id>',
    'X-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    actorId: 'ops-maria',
    overrideReason: 'settlement stuck since the morning window',
    overrideTicket: 'OPS-4711'
  })
};

fetch('https://api.example.com/pixauto/v1/payer/scheduled-payments/{scheduled_payment_id}/unblock', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/pixauto/v1/payer/scheduled-payments/{scheduled_payment_id}/unblock"

payload = {
    "actorId": "ops-maria",
    "overrideReason": "settlement stuck since the morning window",
    "overrideTicket": "OPS-4711"
}
headers = {
    "X-Account-Id": "<x-account-id>",
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "evidence": "NOT_ON_RAIL",
  "releasedOperationId": "settlement-dispatch-2026-09-10-org-a",
  "scheduledPaymentId": "0198f3a2-1c4e-7c8b-9d1e-2f3a4b5c6d40",
  "status": "SCHEDULED",
  "unblockedAt": "2026-09-10T14:00:00Z"
}

{
  "code": "PIX-0142",
  "message": "claim_id is required",
  "title": "Invalid Claim Request",
  "fields": {},
  "headers": {},
  "paths": {},
  "query_params": {},
  "raw": {
    "message": "upstream provider returned 503",
    "status": 123
  }
}

{
  "code": "PIX-0010",
  "message": "The request could not be processed due to a client-side error.",
  "title": "Client Error"
}

{
  "code": "PIX-0010",
  "message": "The request could not be processed due to a client-side error.",
  "title": "Client Error"
}

{
  "code": "PIX-0142",
  "message": "claim_id is required",
  "title": "Invalid Claim Request",
  "fields": {},
  "headers": {},
  "paths": {},
  "query_params": {},
  "raw": {
    "message": "upstream provider returned 503",
    "status": 123
  }
}

{
  "code": "PIX-0142",
  "message": "claim_id is required",
  "title": "Invalid Claim Request",
  "fields": {},
  "headers": {},
  "paths": {},
  "query_params": {},
  "raw": {
    "message": "upstream provider returned 503",
    "status": 123
  }
}

{
  "code": "PIX-0142",
  "message": "claim_id is required",
  "title": "Invalid Claim Request",
  "fields": {},
  "headers": {},
  "paths": {},
  "query_params": {},
  "raw": {
    "message": "upstream provider returned 503",
    "status": 123
  }
}

{
  "code": "PIX-0016",
  "message": "The request body must be sent with Content-Type: application/json.",
  "title": "Unsupported Media Type"
}

{
  "code": "PIX-0000",
  "message": "The server encountered an unexpected error. Please try again later.",
  "title": "Internal Server Error"
}

{
  "code": "PIX-0142",
  "message": "claim_id is required",
  "title": "Invalid Claim Request",
  "fields": {},
  "headers": {},
  "paths": {},
  "query_params": {},
  "raw": {
    "message": "upstream provider returned 503",
    "status": 123
  }
}

Autorizaciones

Authorization

string

header

requerido

JWT bearer token issued by the identity provider.

Encabezados

X-Account-Id

string<uuid>

requerido

Non-zero UUID of the payer account selected by the calling PSP. The PSP must authorize its end user for that account before calling this API. A resource outside the selected account returns 404; a read with no records returns an empty page. See the API overview for the complete trust boundary.

Pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$

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. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412. X-Account-Id is part of the compared request too, so replaying one account's key under another account is divergent rather than a replay.

Required string length: 1 - 64

Parámetros de ruta

scheduled_payment_id

string<uuid>

requerido

Internal identifier of the scheduled debit whose settlement claim is to be released. A debit that exists under a DIFFERENT account than X-Account-Id names is answered 404, not 403: the lookup carries the account as a predicate, so this end never learns that a debit exists elsewhere.

Ejemplo:

"0198f3a2-1c4e-7c8b-9d1e-2f3a4b5c6d40"

Cuerpo

application/json

Optional. Carries the operator attribution. Pix Lerian does not use it to decide the release.

actorId

string

Identifier of the human operator requesting the release. It does not influence the decision and the response does not return it.

Maximum string length: 120

Ejemplo:

"ops-maria"

overrideReason

string

Why the operator is intervening. It does not influence the decision, which rests on what the SPI answers, and the response does not return it.

Maximum string length: 200

Ejemplo:

"settlement stuck since the morning window"

overrideTicket

string

Ticket the intervention is recorded under in your own system. It does not influence the decision and the response does not return it.

Maximum string length: 60

Ejemplo:

"OPS-4711"

Respuesta

Claim released. The debit is eligible again; nothing was cancelled and the receiving PSP was told nothing.

evidence

enum<string>

requerido

Which proof permitted the unblock. NOTHING_SENT: no settlement attempt was ever filed under the claim, so nothing was sent. NOT_ON_RAIL: an attempt was filed, and the SPI has no transfer for its identifier. RAIL_REJECTED: the SPI rejected the order and the ledger entry was reverted.

Opciones disponibles:

NOTHING_SENT,

NOT_ON_RAIL,

RAIL_REJECTED

Ejemplo:

"NOT_ON_RAIL"

releasedOperationId

string

requerido

Execution operation that was holding the debit.

Ejemplo:

"settlement-dispatch-2026-09-10-org-a"

scheduledPaymentId

string<uuid>

requerido

Internal identifier of the scheduled debit whose claim was released.

Ejemplo:

"0198f3a2-1c4e-7c8b-9d1e-2f3a4b5c6d40"

status

string

requerido

Lifecycle status the debit holds after the unblock. It returns to SCHEDULED, which is what makes it eligible for a further settlement attempt.

Ejemplo:

"SCHEDULED"

unblockedAt

string<date-time>

requerido

Instant Pix Lerian released the claim, in UTC. It is Pix Lerian's own clock reading, not a value from the request.

Ejemplo:

"2026-09-10T14:00:00Z"

DICT y claves Pix

Cobros y códigos BR

Pagos y devoluciones

API de Pix Automático

Manejo de errores

Release the settlement claim on a stuck scheduled debit

Autorizaciones

Encabezados

Parámetros de ruta

Cuerpo

Respuesta