> ## 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. # Cancel a scheduled Pix payment > Cancels a schedule at the payer's request, accepted right up to the cancellation cut-off recorded on it and refused AT that instant. The deadline compared against is the one photographed when the schedule was created, not whatever the configuration derives today: the deadline the payer was told is the deadline they get. Because the cut-off is strictly before the first settlement window, cancelling and executing can never both be in time. Nothing is released -- nothing was held. ## OpenAPI ````yaml /pt/openapi/v3-current/pix-lerian-spi.yaml post /scheduled-payments/{schedule_id}/cancel openapi: 3.1.0 info: contact: name: Lerian Studio url: https://lerian.studio description: Public API for outbound Pix transfers, refunds, and scheduled payments. license: name: Lerian Studio General License title: Pix Lerian — Payments version: 1.2.0 servers: - url: https://api.example.com/spi/v1 description: >- Replace the example host with the URL provided during environment onboarding. security: - BearerAuth: [] tags: - description: Create, list, and retrieve Pix refunds. name: Refunds - name: Scheduled Payments description: Register, list, retrieve, and cancel scheduled Pix payments. - description: Initiate, process, list, and retrieve outbound Pix transfers. name: Transfers - description: >- Register, list, retrieve, and cancel recurring series of scheduled Pix payments. name: Scheduled Payment Recurrences - description: >- Hold the funds of a received Pix in a cautionary block (MED 2.0), return them to the payer, or give them back to the account holder. name: Balance Locks paths: /scheduled-payments/{schedule_id}/cancel: post: tags: - Scheduled Payments summary: Cancel a scheduled Pix payment description: >- Cancels a schedule at the payer's request, accepted right up to the cancellation cut-off recorded on it and refused AT that instant. The deadline compared against is the one photographed when the schedule was created, not whatever the configuration derives today: the deadline the payer was told is the deadline they get. Because the cut-off is strictly before the first settlement window, cancelling and executing can never both be in time. Nothing is released -- nothing was held. operationId: cancelScheduledPayment parameters: - description: >- 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. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Schedule identifier. in: path name: schedule_id required: true schema: description: Schedule identifier. examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ScheduledPaymentView' description: OK '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: >- The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Two shapes share this status, one per media type. application/problem+json: schedule_id is not a UUID (PIX-0015). The response names the parameter; the schedule is never looked up. application/json is the legacy {code,title,message} envelope, from the idempotency gate: X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- No schedule with that identifier exists for this organization (PIX-0770). '409': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- The schedule cannot be cancelled from the state it is in. PIX-0771: it has already settled, been cancelled or failed -- re-read it, a terminal status does not transition. PIX-0773: it is executing, which under the cut-off precedence should be unreachable, so its occurrence is worth investigating rather than retrying. '412': content: application/json: example: 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. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- Refused under this X-Idempotency (PIX-0031): the first request under it is still running (with Retry-After: 1), its receipt could not be stored and the key is held for the hour, or the request differs from the first (method, URL, body or identity header). An earlier request under this key may already have executed. Legacy {code,title,message} envelope, NOT problem+json. '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- The cancellation cut-off recorded on this schedule has passed (PIX-0772). Not resolvable by retry: the deadline is the snapshot taken at creation, and at the exact instant it is already refused. '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Internal Server Error default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error components: schemas: ScheduledPaymentView: additionalProperties: false properties: accountId: description: Payer account. examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string amount: description: Amount to settle, in BRL. examples: - '150.00' type: string attempts: description: >- Every attempt of the scheduled day, oldest first. Empty before that date, and never null. items: $ref: '#/components/schemas/ScheduleAttemptView' type: - array - 'null' cancellationCutoff: description: >- The first instant a cancellation is REFUSED. Cancellation is accepted right up to it and refused AT it, and it is strictly before the first window so the two can never overlap. format: date-time type: string cancelledReason: description: >- Present exactly when status is CANCELLED. A cancellation the payer asked for and one the domain performed are deliberately distinguishable. CHARGE_AMOUNT_CHANGED and CHARGE_NOT_PAYABLE: on the scheduled date the QR charge asked another amount, or the receiver refused reading it (the charge was removed, concluded or expired); nothing was debited. A failed check of the receiver's site or signature cancels nothing: like a receiver that does not answer, it pays the recorded amount. enum: - USER_REQUEST - OWNERSHIP_MISMATCH - KEY_NOT_FOUND - CHARGE_AMOUNT_CHANGED - CHARGE_NOT_PAYABLE - RECURRENCE_CANCELLED type: string createdAt: format: date-time type: string currency: description: Always BRL. examples: - BRL type: string description: description: >- The payer's memo, returned exactly as it was stored. Markup is not interpreted here and was not escaped on the way in; escaping belongs to whoever renders it. examples: - Aluguel de setembro type: string destination: $ref: '#/components/schemas/ParticipantView' description: >- The payee as photographed at creation. On a DICT schedule it is compared on the scheduled date against a fresh directory answer (REG-Art.9§6), which is why it is stored rather than re-resolved; a MANUAL or QR_CODE schedule is sent to it as photographed, with no second lookup. firstWindowOpensAt: description: >- When the first settlement window of the scheduled date opens (IN 513 art. 12 caput). Photographed at creation. format: date-time type: string id: description: Schedule identifier. examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string initiationType: description: How the destination was resolved. enum: - MANUAL - DICT - QR_CODE examples: - DICT type: string purpose: description: 'Always IPAY: REG-Art.11-P prohibits scheduling any other purpose.' enum: - IPAY examples: - IPAY type: string scheduledDate: description: Civil settlement date in AAAA-MM-DD, in America/Sao_Paulo. examples: - '2026-09-10' format: date type: string source: $ref: '#/components/schemas/ParticipantView' description: The payer as photographed at creation. status: description: >- Lifecycle status. DISPATCHED_OUTCOME_UNKNOWN is NOT terminal: the order is awaiting reconciliation and will resolve to SETTLED or FAILED. It does NOT assert that the order reached the rail -- it also covers an order that provably did not, whose reserved funds are still being released. enum: - PENDING - EXECUTING - DISPATCHED_OUTCOME_UNKNOWN - AWAITING_RETRY - SETTLED - CANCELLED - FAILED examples: - PENDING type: string transferId: description: The transfer that settled this schedule, once it has. type: string updatedAt: format: date-time type: string required: - id - accountId - scheduledDate - amount - currency - initiationType - purpose - source - destination - status - firstWindowOpensAt - cancellationCutoff - createdAt - updatedAt - attempts type: object LegacyErrorEnvelope: additionalProperties: false properties: code: description: PIX-XXXX error code type: string message: description: Human-readable error message type: string title: description: Short error title type: string fields: additionalProperties: type: string description: Per-field detail, keyed by the field or header the refusal names type: object headers: additionalProperties: type: string description: Per-header detail, keyed by the request header the refusal names type: object required: - code - title - message type: object Detail: additionalProperties: true properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object ScheduleAttemptView: additionalProperties: false properties: attemptNumber: examples: - 1 format: int64 type: integer endToEndId: description: >- The identifier the attempt dispatched under. Reconciliation of an unknown outcome happens by this value, and it is never minted twice. type: string finishedAt: description: Present exactly when outcome is. format: date-time type: string id: type: string isLastAttempt: description: >- Whether the day's window schedule allowed a further attempt after this one. type: boolean outcome: description: >- How the attempt ended. The two OPERATIONAL_FAILURE members are distinct because only the pre-dispatch one is safe to retry. enum: - SETTLED - INSUFFICIENT_FUNDS - INSUFFICIENT_LIMIT - OWNERSHIP_MISMATCH - KEY_NOT_FOUND - CHARGE_AMOUNT_CHANGED - CHARGE_NOT_PAYABLE - OPERATIONAL_FAILURE_PRE_DISPATCH - OPERATIONAL_FAILURE_POST_DISPATCH type: string providerChannel: description: >- The CSM channel the attempt went out on. UNKNOWN is a real answer from a rail that cannot report one. enum: - PRIMARY - SECONDARY - UNKNOWN type: string startedAt: format: date-time type: string required: - id - attemptNumber - isLastAttempt - startedAt type: object ParticipantView: additionalProperties: false properties: accountNumber: examples: - '123456' type: string accountType: enum: - CACC - SVGS - TRAN - SLRY examples: - CACC type: string branch: examples: - '0001' type: string ispb: description: >- 8-character BACEN participant identifier (digits or uppercase letters). examples: - '32074986' type: string name: examples: - Ana Souza type: string personType: enum: - NATURAL_PERSON - LEGAL_PERSON examples: - NATURAL_PERSON type: string taxId: description: CPF or CNPJ, digits only. examples: - '39053344705' type: string required: - accountType - ispb - personType - taxId - name type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string 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.