> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # 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/{scheduled_payment_id}/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. ## OpenAPI ````yaml /pt/openapi/v3-current/pix-lerian-pixauto.yaml post /payer/scheduled-payments/{scheduled_payment_id}/unblock openapi: 3.1.0 info: contact: name: Lerian Studio url: https://lerian.studio description: >- Pix Automático payer-facing API — deciding an authorization request raised by the receiving end, managing the payer-configurable parameters of a granted mandate, and revoking it (Guia de Implementação do Pix Automático v1.2 §3 and §6). ## Trust boundary This API is **machine-to-machine**. The caller is the client PSP's backend, authenticated with an application token; the token names that application and never one of its customers. The account therefore has to arrive in the request, and it does so in one of two shapes: most routes take it in the **`X-Account-Id`** header, the same header SPI, DICT and COB use for the same job, and the route that CREATES the resource the account belongs to takes `payerAccountId` in the body — `POST /v1/payer/authorization-requests/from-qr`, which opens a pending request for a mandate that does not exist yet. On that route, the account is part of what is being created rather than a scope on an existing resource, and a header beside the body field would be a second source for one value. Either way the value is the caller's **declaration** of which of its own customers it is acting for. **It is not proof that the end user controls that account, and this API cannot make it one.** Authenticating the payer and authorising its own customers against one another is the calling PSP's responsibility. What this end enforces is consistency: an absent header is 400 (PIX-0001) and a malformed account is 400 (PIX-0017 on the header, PIX-0003 in the body), and a resource that exists under a different account than the one named is **404**, not 403: the account is a predicate on the lookup, so this end never learns the resource exists elsewhere and cannot confirm it. Within one lookup, absence and a resource outside the selection get the same answer. license: name: Lerian Studio General License title: Pix Lerian — Pix Automático version: 1.1.0 servers: - url: https://api.example.com/pixauto/v1 description: >- Replace the example host with the URL provided during environment onboarding. security: - BearerAuth: [] tags: - description: >- Authorization requests raised by the receiving end and answered by the payer. A request is answered once. name: Payer Authorization Requests - description: Granted mandates. An authorization is managed for as long as it lives. name: Payer Authorizations - description: >- The payer's forward view of upcoming debits, the cancellation of one of them, and the release of a debit whose settlement attempt never got an outcome. Cancelling a debit leaves the authorization ACTIVE — it stops one charge, not the mandate. The operations are meant to be used together: the listing is the only place a client receives the scheduled_payment_id the others address. name: Payer Scheduled Payments paths: /payer/scheduled-payments/{scheduled_payment_id}/unblock: post: tags: - Payer Scheduled Payments summary: Release the settlement claim on a stuck scheduled debit description: >- 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/{scheduled_payment_id}/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. operationId: unblockPayerScheduledPayment parameters: - description: >- 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. example: 0198f3a2-1c4e-7c8b-9d1e-2f3a4b5c6d7e in: header name: X-Account-Id required: true schema: format: uuid not: const: 00000000-0000-0000-0000-000000000000 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}$ type: string - description: >- 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. example: payer-decision-20260827-001 in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: >- 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. in: path name: scheduled_payment_id required: true schema: description: >- 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. examples: - 0198f3a2-1c4e-7c8b-9d1e-2f3a4b5c6d40 format: uuid type: string requestBody: content: application/json: examples: operator-intervention: summary: Release a debit whose order never reached the SPI value: actorId: ops-maria overrideReason: settlement stuck since the morning window overrideTicket: OPS-4711 schema: $ref: '#/components/schemas/ScheduledPaymentUnblockBody' description: >- Optional. Carries the operator attribution. Pix Lerian does not use it to decide the release. responses: '200': content: application/json: example: 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' schema: $ref: '#/components/schemas/ScheduledPaymentUnblockResponse' description: >- Claim released. The debit is eligible again; nothing was cancelled and the receiving PSP was told nothing. '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: >- Malformed request, missing required input, invalid field value or invalid idempotency key (PIX-0001, PIX-0002, PIX-0003, PIX-0015, PIX-0017, PIX-0030, plus operation-specific PIX codes). X-Idempotency absent or longer than 64 bytes (PIX-0030). '401': content: application/json: example: code: PIX-0010 message: The request could not be processed due to a client-side error. title: Client Error schema: $ref: '#/components/schemas/Error' description: >- The credentials were refused before the handler ran: absent, invalid or expired. Branch on the 401 status, not the body code, which depends on the refusing layer: the authorization middleware answers the generic client-error code PIX-0010; in multi-tenant deployments the tenant layer may answer a missing, malformed or tenantless token with its own {code,title,message} body, under codes such as MISSING_TOKEN, INVALID_TENANT or UNAUTHORIZED. '403': content: application/json: example: code: PIX-0010 message: The request could not be processed due to a client-side error. title: Client Error schema: $ref: '#/components/schemas/Error' description: >- The caller was refused before the handler ran. Branch on the 403 status, not the body code, which depends on the refusing layer: the authorization middleware answers the generic client-error code PIX-0010 when the caller is not entitled to this resource and action; in multi-tenant deployments the tenant layer may answer with its own {code,title,message} body, such as code 0131 (Service Suspended or Access Denied) when the tenant's access to this service is suspended, purged or denied. '404': content: application/json: schema: $ref: '#/components/schemas/Error' description: >- No scheduled debit with that identifier is reachable by the caller (PIX-0824). '409': content: application/json: schema: $ref: '#/components/schemas/Error' description: >- The release is refused (PIX-0827). An entry in `errors` with location `detail` names the reason. '412': content: application/json: schema: $ref: '#/components/schemas/Error' description: >- X-Idempotency replayed with a divergent request — a different method, URL (including the path parameter) or body (PIX-0031). 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. '415': content: application/json: example: code: PIX-0016 message: >- The request body must be sent with Content-Type: application/json. title: Unsupported Media Type schema: $ref: '#/components/schemas/Error' description: >- The request body carries a media type this operation does not admit (PIX-0016). '500': content: application/json: example: code: PIX-0000 message: >- The server encountered an unexpected error. Please try again later. title: Internal Server Error schema: $ref: '#/components/schemas/Error' description: >- Unexpected internal failure (PIX-0000). Details never travel in the envelope. default: content: application/json: schema: $ref: '#/components/schemas/Error' description: >- Any other error returned by the handler uses the same PIX error envelope. The HTTP status and code identify the concrete failure. In multi-tenant deployments the tenant layer can also refuse before the handler runs -- for example 404 TENANT_NOT_FOUND or 503 SERVICE_UNAVAILABLE -- with its own {code,title,message} body; branch on the HTTP status. components: schemas: ScheduledPaymentUnblockBody: additionalProperties: false properties: actorId: description: >- Identifier of the human operator requesting the release. It does not influence the decision and the response does not return it. examples: - ops-maria maxLength: 120 type: string overrideReason: description: >- 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. examples: - settlement stuck since the morning window maxLength: 200 type: string overrideTicket: description: >- Ticket the intervention is recorded under in your own system. It does not influence the decision and the response does not return it. examples: - OPS-4711 maxLength: 60 type: string type: object ScheduledPaymentUnblockResponse: additionalProperties: false properties: evidence: description: >- 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. enum: - NOTHING_SENT - NOT_ON_RAIL - RAIL_REJECTED examples: - NOT_ON_RAIL type: string releasedOperationId: description: Execution operation that was holding the debit. examples: - settlement-dispatch-2026-09-10-org-a type: string scheduledPaymentId: description: Internal identifier of the scheduled debit whose claim was released. examples: - 0198f3a2-1c4e-7c8b-9d1e-2f3a4b5c6d40 format: uuid type: string status: description: >- Lifecycle status the debit holds after the unblock. It returns to SCHEDULED, which is what makes it eligible for a further settlement attempt. examples: - SCHEDULED type: string unblockedAt: description: >- Instant Pix Lerian released the claim, in UTC. It is Pix Lerian's own clock reading, not a value from the request. examples: - '2026-09-10T14:00:00Z' format: date-time type: string required: - scheduledPaymentId - status - releasedOperationId - evidence - unblockedAt type: object Error: additionalProperties: false properties: code: examples: - PIX-0142 type: string fields: additionalProperties: type: string type: object headers: additionalProperties: type: string type: object message: examples: - claim_id is required type: string paths: additionalProperties: type: string type: object query_params: additionalProperties: type: string type: object raw: $ref: '#/components/schemas/RawError' title: examples: - Invalid Claim Request type: string required: - code - title - message type: object RawError: additionalProperties: false properties: message: examples: - upstream provider returned 503 type: string status: format: int64 type: integer required: - status - message type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.