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. A debit whose order never left, or never landed, goes back to the queue of its own settlement date. A dispatch sends only a debit dated today in America/Sao_Paulo, and only until 21:00. The back office of your institution calls this route.

THE SPI DECIDES, NOT THE CALLER. The request has no field to state what happened. Pix Lerian releases the debit only on one of two proofs, and the response names which one applied. 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. Any other answer refuses the release with PIX-0827, including when the SPI cannot be asked. An order that the SPI rejected is refused too: the settlement reconciliation ends that charge.

The attempt must be at least 15 minutes old. From 21:00 of the settlement date nothing sends the order again, so a NOT_ON_RAIL release from then on also sends the payer the definitive notice of the day close (settlement_failed or settlement_retry_permitted, by the retry policy of the recurrence).

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

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

200

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

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. 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. 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 records the actor and the ticket as sent, and the reason only by its length. It does not use any of them to decide the release.

actorId · string

Identifier of the human operator requesting the release, as you declare it. Pix Lerian records it in the audit trail next to the identity of the token. 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. Pix Lerian records only its length, not its text. 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, as you declare it. Pix Lerian records it in the audit trail. It does not influence the decision and the response does not return it.

Maximum string length: 60

Ejemplo:

"OPS-4711"

Respuesta

200

application/json

Claim released. Nothing was cancelled and the receiving PSP was told nothing. A dispatch of the date of the debit sends it if one runs before 21:00.

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.

Opciones disponibles: NOTHING_SENT, NOT_ON_RAIL

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 right after the unblock: SCHEDULED. Whether a further settlement attempt follows depends on whether a dispatch of its date runs before 21:00.

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"