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.

POST /payer/authorizations/{authorization_id}/cancel

Cancel an authorization at the payer's request

cURL

curl --request POST \
  --url https://api.example.com/pixauto/v1/payer/authorizations/{authorization_id}/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Account-Id: <x-account-id>' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "reason": "Payer requested revocation in the mobile app"
}
'

202

{
  "authorizationId": "01a044a8-f3bd-7488-a0dc-e8d4be4802be",
  "cancelledScheduledPayments": 0,
  "counterpartyReason": "SLDB",
  "preservedScheduledPayments": 0,
  "status": "CANCELLED"
}

Autorizações

Authorization · string · header · obrigatório

JWT bearer token issued by the identity provider.

Cabeçalhos

X-Account-Id · string<uuid> · obrigatório

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 · obrigatório

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 caminho

authorization_id · string · obrigatório

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.

Exemplo:

"01a044a8-f3bd-7488-a0dc-e8d4be4802be"

Corpo

application/json

Optional. Carries the payer's own free-text note, which is never forwarded to the counterparty.

reason · string

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.

Maximum string length: 200

Exemplo:

"Payer requested revocation in the mobile app"

Resposta

202

application/json

Authorization revoked and cascade applied. Both counters are facts about the same commit.

authorizationId · string · obrigatório

Exemplo:

"01a044a8-f3bd-7488-a0dc-e8d4be4802be"

cancelledScheduledPayments · integer<int64> · obrigatório

Exemplo:

0

counterpartyReason · string · obrigatório

Exemplo:

"SLDB"

preservedScheduledPayments · integer<int64> · obrigatório

Exemplo:

0

status · string · obrigatório

Exemplo:

"CANCELLED"