> ## Documentation Index > Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Cancel a Pix key claim > Cancels a claim for one of your Pix keys: you keep the key, and it keeps receiving Pix. Answer only a `waiting` claim, before its `resolutionPeriodEnd`. The claim comes back with the status the Pix directory answered — usually `canceled`. Send no body. If the bank throttles the request, you get a `429`: wait and retry. Only an organization admin can cancel a claim. ## OpenAPI ````yaml /api-reference/banking.openapi.json post /realms/{realmId}/organizations/{organizationId}/pix-dict-claim/{id}/cancel openapi: 3.0.3 info: title: Banking version: 1.0.0 description: >- Portão 3 banking API. Every endpoint requires a bearer token in the Authorization header (Authorization: Bearer ) unless its page states otherwise; see the Authentication guide. That requirement is not repeated per endpoint. Generated by tools/openapi from code (routes + security) and the hand-written spec (request/response bodies). Banking attaches a zod validationSchema at the route; request bodies are resolved from it (object + array roots). Responses have no presenter layer, so they stay tier=unknown. Confidence tiers: generated:typed=300 copied:manual=0 unknown=20. servers: - url: https://api.banking.v2.portao3.com.br/ description: production - url: https://api.banking.dev.3pers.com.br/ description: development security: [] tags: - name: Accounts - name: Account Limits - name: Wallets - name: Transaction Limits - name: Transfers - name: Cards - name: Card Limits - name: Cards 3DS - name: Pix Payments - name: Pix Keys - name: PIX Charges - name: PIX Automatic - name: PIX Initiation (Open Finance) - name: PIX Infractions (MED) - name: Boleto Payments - name: Boleto Charges - name: TED Payments - name: Transactions - name: Transaction Reversals - name: Spend Review - name: Cashback - name: Currency Codes paths: /realms/{realmId}/organizations/{organizationId}/pix-dict-claim/{id}/cancel: post: tags: - Pix Keys summary: Cancel a Pix key claim description: >- Cancels a claim for one of your Pix keys: you keep the key, and it keeps receiving Pix. Answer only a `waiting` claim, before its `resolutionPeriodEnd`. The claim comes back with the status the Pix directory answered — usually `canceled`. Send no body. If the bank throttles the request, you get a `429`: wait and retry. operationId: postRealmsByRealmIdOrganizationsByOrganizationIdPixDictClaimByIdCancel parameters: - name: realmId in: path required: true description: |- ID of your realm. Format: `UUID` schema: type: string format: uuid example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b - name: organizationId in: path required: true description: |- ID of the organization. Format: `UUID` schema: type: string format: uuid example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 - name: id in: path required: true description: |- ID of the claim — its `id` field, not its `_id`. Format: `UUID` schema: type: string format: uuid example: 3b9e7c1a-5d2f-4e8b-9a61-0c4f2d7e8b13 - name: x-environment in: header required: false description: >- Environment of the claim: `LIVE` (production) or `TEST` (sandbox). When you omit it, `TEST` is used; any other value is rejected. schema: type: string enum: - LIVE - TEST example: LIVE responses: '200': description: Successful response content: application/json: schema: type: object properties: _id: type: string description: >- Internal ID of the record. To confirm or cancel the claim, use `id`. example: 672a0c4fb4d3e80012c9a6b2 id: type: string description: >- ID of the claim in the Pix directory — use it as `id` to confirm or cancel the claim. example: 3b9e7c1a-5d2f-4e8b-9a61-0c4f2d7e8b13 realmId: type: string description: ID of the realm. example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b organizationId: type: string description: ID of the organization. example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 accountId: type: string description: ID of the organization's account. example: 66f2a1c7b4d3e80012c9a0b4 walletId: type: string description: ID of the wallet that holds the claimed key. example: 66f2a3d1b4d3e80012c9a0d2 environment: type: string enum: - LIVE - TEST description: 'Environment of the claim: `LIVE` or `TEST`.' example: LIVE key: type: string description: The claimed key, as registered. example: '12345678000190' keyType: type: string description: >- Kind of the claimed key: `CNPJ`, `CPF`, `EMAIL` or `PHONE`. example: CNPJ type: type: string description: >- `portability` (the key's owner moves it to another institution) or `ownership` (someone else says the key is theirs). example: portability status: type: string description: >- Status of the claim, as last notified: - `waiting` — waiting for your answer: confirm or cancel it before `resolutionPeriodEnd`. - `processing_confirm` — your confirmation is being processed. - `confirmed` — the claim was confirmed: the key is released to the claimer. It is marked `REMOVED` in your wallet when the Pix directory notifies the confirmation, which can come after the confirmation's response. - `completed` — the claimer's institution finished moving the key. - `canceled` — the claim was cancelled: the key stays in your wallet. Other values the Pix directory defines may appear. A `waiting` claim past `resolutionPeriodEnd` may have been settled without a notification reaching us. example: waiting claimer: type: object properties: document: type: string description: >- CPF or CNPJ of the claimer, formatted with punctuation (`123.456.789-09`, `12.345.678/0001-90`). example: 98.765.432/0001-10 name: type: string description: Name of the claimer. example: Aurora Comércio Ltda type: type: string description: '`business` (a company) or `individual` (a person).' example: business required: - document - name - type description: Who claims the key. claimerAccount: type: object properties: accountNumber: type: number description: Number of the account. example: 7654321 accountType: type: string description: >- Type of the account: `CACC` (checking), `TRAN` (payment), `SVGS` (savings) or `SLRY` (salary). example: CACC bankIspb: type: string nullable: true description: >- ISPB code of the claimer's institution, written without its leading zeros (`360305` for `00360305`). `null` or absent when the claim didn't carry it. example: '60746948' branch: type: string description: Branch of the account, without leading zeros. example: '1' openingDate: type: string description: When the account was opened (ISO 8601). example: '2021-03-15T00:00:00Z' required: - accountNumber - accountType - branch - openingDate description: >- The account the claimer wants the key to point to, at the other institution. donorBankIspb: type: number description: >- ISPB code of the institution that holds the key today — Portão 3's banking partner. example: 12345678 external: type: object properties: accountId: type: string description: >- ID of the account that holds the key, at Portão 3's banking partner. example: 4f6b0e1d-2b3a-4c5d-8e9f-0a1b2c3d4e5f required: - accountId description: >- The claimed key's account identifiers at Portão 3's banking partner. insertedAt: type: string description: >- When the claim was opened in the Pix directory (UTC, without a time zone suffix). example: '2026-11-03T23:25:04' resolutionPeriodEnd: type: string description: Deadline to confirm or cancel the claim (ISO 8601, UTC). example: '2026-11-10T23:25:04Z' completionPeriodEnd: type: string nullable: true description: >- Deadline for the claim to be completed (ISO 8601, UTC), when the claim already carried one as it reached us — not updated afterwards. `null` or absent on most claims. example: null cancelReason: type: string nullable: true description: >- Reason the claim was cancelled, when the claim carried one as it reached us — not updated afterwards. `null` or absent: no claim received so far carried one. example: null canceledBy: type: string nullable: true description: >- Who cancelled the claim, when the claim carried it as it reached us — not updated afterwards. `null` or absent: no claim received so far carried it. example: null confirmReason: type: string nullable: true description: >- Reason the claim was confirmed, when the claim carried one as it reached us — not updated afterwards. `null` or absent: no claim received so far carried one. example: null errorReason: type: string nullable: true description: >- Error reported for the claim, when the claim carried one as it reached us — not updated afterwards. `null` or absent: no claim received so far carried one. example: null createdAt: type: string description: When we received the claim (ISO 8601). example: '2026-11-03T23:25:06.013Z' updatedAt: type: string description: >- When the record was last updated, as text in English with the time zone spelled out — not ISO 8601. example: >- Tue Nov 03 2026 23:25:06 GMT+0000 (Coordinated Universal Time) __v: type: number description: Internal version of the record. example: 0 required: - _id - id - realmId - organizationId - accountId - walletId - environment - key - keyType - type - status - claimer - claimerAccount - donorBankIspb - external - insertedAt - resolutionPeriodEnd - createdAt - updatedAt - __v description: >- A claim another institution opened, on behalf of one of its customers, for a Pix key registered in one of your wallets. With a `portability` claim the key's owner wants to move it to their account at the other institution; with an `ownership` claim someone else says the key (an e-mail address or a phone number) is theirs. '403': description: '`FORBIDDEN_WALLET` — You aren''t an admin of the organization.' content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - FORBIDDEN_WALLET description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BANKING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: FORBIDDEN_WALLET origin: BANKING message: >- You do not have permission to perform this action on this wallet '404': description: >- `PIX_DICT_CLAIM_NOT_FOUND` — The organization has no claim with this `id` in this environment waiting for an answer — it doesn't exist, or it was already confirmed or cancelled. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - PIX_DICT_CLAIM_NOT_FOUND description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BANKING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: PIX_DICT_CLAIM_NOT_FOUND origin: BANKING message: Pix key claim not found '422': description: >- `BAD_REQUEST` — A path parameter is invalid; `fields` lists each one. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - BAD_REQUEST description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BANKING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. fields: type: array description: >- One entry per invalid request field (validation errors only). items: type: object properties: field: type: string description: >- Path of the invalid field, e.g. `label` or `values[0].value`. example: label message: type: string description: Why the field was rejected. example: label is required code: type: string description: >- `_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`. example: LABEL_REQUIRED values: type: array items: type: string description: >- The accepted values, when the field is an enumeration. required: - field - message - code required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BAD_REQUEST origin: BANKING message: >- Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields. fields: - field: id message: Invalid UUID code: ID_UUID '500': description: >- `BANKING_PROVIDER_UNAVAILABLE` — The bank answered with a server error. The claim may have been cancelled anyway: list the claims before retrying — its status changes when the Pix directory notifies the outcome. `BANKING_PROVIDER_INTEGRATION_ERROR` — The bank answered with an error this API doesn't recognize. The claim may have been cancelled anyway: list the claims before retrying — its status changes when the Pix directory notifies the outcome. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - BANKING_PROVIDER_UNAVAILABLE - BANKING_PROVIDER_INTEGRATION_ERROR description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BANKING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BANKING_PROVIDER_UNAVAILABLE origin: BANKING message: Banking provider temporarily unavailable, please retry '502': description: >- `BANKING_PROVIDER_UNAVAILABLE` — The bank's gateway failed. The claim may have been cancelled anyway: list the claims before retrying — its status changes when the Pix directory notifies the outcome. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - BANKING_PROVIDER_UNAVAILABLE description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BANKING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BANKING_PROVIDER_UNAVAILABLE origin: BANKING message: Banking provider temporarily unavailable, please retry '503': description: >- `BANKING_PROVIDER_UNAVAILABLE` — The bank was unavailable. The claim may have been cancelled anyway: list the claims before retrying — its status changes when the Pix directory notifies the outcome. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - BANKING_PROVIDER_UNAVAILABLE description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BANKING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BANKING_PROVIDER_UNAVAILABLE origin: BANKING message: Banking provider temporarily unavailable, please retry '504': description: >- `BANKING_PROVIDER_UNAVAILABLE` — The bank didn't answer in time (its gateway's own timeout says "Banking provider temporarily unavailable, please retry"). The claim may have been cancelled anyway: list the claims before retrying — its status changes when the Pix directory notifies the outcome. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - BANKING_PROVIDER_UNAVAILABLE description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BANKING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BANKING_PROVIDER_UNAVAILABLE origin: BANKING message: Banking provider did not respond in time, please retry ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.