> ## 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 an authorization at the payer's request > Revokes the mandate at the payer's request. The revocation is IMMEDIATE and CASCADES over every debit scheduled under it, retries after the due date included — except those due for settlement on the day the revocation happens, which are preserved by rule (Guia v1.2 §3.7.1). The termination and the scheduled-debit cascade commit together or not at all, so a mandate cannot be revoked while cancellable debits remain active. A non-zero preservedScheduledPayments is CORRECT behaviour, not a partial failure. Those debits will still settle today, and the payer is shown the count so they know it. The body's reason is a free-text note for the payer's own audit trail. It is NOT the value sent to the counterparty: the receiving PSP is told motivoCancelamento = SLDB, the pain.011 code for a cancellation the paying user asked for, which the response echoes as counterpartyReason. A revocation over a mandate that has upcoming debits reports non-zero values on either counter, so a caller must read them rather than assume zero. ## OpenAPI ````yaml /pt/openapi/v3-current/pix-lerian-pixauto.yaml post /payer/authorizations/{authorization_id}/cancel 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.2.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/authorizations/{authorization_id}/cancel: post: tags: - Payer Authorizations summary: Cancel an authorization at the payer's request description: >- Revokes the mandate at the payer's request. The revocation is IMMEDIATE and CASCADES over every debit scheduled under it, retries after the due date included — except those due for settlement on the day the revocation happens, which are preserved by rule (Guia v1.2 §3.7.1). The termination and the scheduled-debit cascade commit together or not at all, so a mandate cannot be revoked while cancellable debits remain active. A non-zero preservedScheduledPayments is CORRECT behaviour, not a partial failure. Those debits will still settle today, and the payer is shown the count so they know it. The body's reason is a free-text note for the payer's own audit trail. It is NOT the value sent to the counterparty: the receiving PSP is told motivoCancelamento = SLDB, the pain.011 code for a cancellation the paying user asked for, which the response echoes as counterpartyReason. A revocation over a mandate that has upcoming debits reports non-zero values on either counter, so a caller must read them rather than assume zero. operationId: cancelPayerAuthorization 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. 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. example: payer-decision-20260827-001 in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: >- Internal identifier of the mandate being revoked. A request or mandate 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 resource exists elsewhere and cannot confirm it. in: path name: authorization_id required: true schema: description: >- Internal identifier of the mandate being revoked. A request or mandate 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 resource exists elsewhere and cannot confirm it. examples: - 01a044a8-f3bd-7488-a0dc-e8d4be4802be type: string requestBody: content: application/json: examples: payer-request: summary: Cancel at the payer's request value: reason: Payer requested revocation in the mobile app schema: $ref: '#/components/schemas/AuthorizationCancellationBody' description: >- Optional. Carries the payer's own free-text note, which is never forwarded to the counterparty. responses: '202': content: application/json: example: authorizationId: 01a044a8-f3bd-7488-a0dc-e8d4be4802be cancelledScheduledPayments: 0 counterpartyReason: SLDB preservedScheduledPayments: 0 status: CANCELLED schema: $ref: '#/components/schemas/AuthorizationCancellationResponse' description: >- Authorization revoked and cascade applied. Both counters are facts about the same commit. '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-0010, 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 authorization with that identifier is reachable by the caller (PIX-0804). '409': content: application/json: schema: $ref: '#/components/schemas/Error' description: The authorization is already terminated (PIX-0805). '412': content: application/json: schema: $ref: '#/components/schemas/Error' 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 or body). An earlier request under this key may already have executed. 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: AuthorizationCancellationBody: additionalProperties: false properties: reason: description: >- Free-text note for the PAYER's own audit trail. It is NOT the value sent to the counterparty: the receiving PSP is told a fixed code this end chooses, which the response echoes as counterpartyReason. examples: - Payer requested revocation in the mobile app maxLength: 200 type: string type: object AuthorizationCancellationResponse: additionalProperties: false properties: authorizationId: examples: - 01a044a8-f3bd-7488-a0dc-e8d4be4802be type: string cancelledScheduledPayments: examples: - 0 format: int64 type: integer counterpartyReason: examples: - SLDB type: string preservedScheduledPayments: examples: - 0 format: int64 type: integer status: examples: - CANCELLED type: string required: - authorizationId - status - counterpartyReason - cancelledScheduledPayments - preservedScheduledPayments 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.