---
updatedAt: 2026-04-23T18:12:51.000Z
agentTools:
  siteIndex: https://developers.pismo.io/llms.txt
  projectIndex: https://developers.pismo.io/pismo-docs/llms.txt
---

# Cancel key claim

Cancel a key's DICT claim. 

The table below defines, depending on the reason and type, who can cancel. 

For more information, refer to <a href="https://developers.pismo.io/pismo-docs/docs/pix-instant-payments#pix-key-transfer-key-claim" >Pix key transfer (key claim)</a>

* `OWNERSHIP` - Transfer key ownership between users in the same or another bank. 

* `PORTABILITY` - Transfer key ownership for the same user to another bank.


<table border="1">
<tr>
<th> </th>
<th colspan="2"> OWNERSHIP </th>
<th colspan="3"> PORTABILITY </th>
</tr>
<tr>
<th> Reason </th>
<th> Donor </th>
<th> Claimer </th>
<th> Donor </th>
<th colspan="2"> Claimer </th>
</tr>
<tr>
<th colspan=4>&nbsp</td>
<th>WAITING_RESOLUTION</th>
<th>CONFIRMED</th>
<tr bgcolor="#FFFAFA">
<td>USER_REQUESTED</td>
<td></td>
<td align="center">√</td>
<td align="center">√</td>
<td align="center">√</td>
<td aligm="center">&nbsp;</td>
</tr>
<tr>
<td>ACCOUNT_CLOSURE</td>
<td align="center">√</td>
<td align="center">√</td>
<td align="center"></td>
<td align="center">√</td>
</tr>
<tr bgcolor="#FFFAFA">
<td>FRAUD</td>
<td align="center">√</td>
<td align="center">√</td>
<td align="center">√</td>
<td align="center">√</td>
<td align="center">√</td>
</tr>
<tr>
<td>DEFAULT_OPERATION</td>
<td align="center"></td>
<td align="center">√</td>
<td align="center">√</td>
<td align="center"></td>
</tr>
<tr bgcolor="#FFFAFA">
<td>RECONCILIATION</td>
<td align="center"></td>
<td align="center"></td>
<td align="center"></td>
<td align="center">√</td>
 <td align="center">√</td>
</tr>
</table>

On PSP timeout, a `202 Accepted` response is returned and the process continues asynchronously, eventually emitting an event if it succeeds.

This endpoint generates a <a href="https://developers.pismo.io/events/docs/pix-dict-claim-status-change-1" >Pix key claim status changed</a> event.


# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Instant payments - Pix management",
    "description": "API responsible for providing Pix operations (related to DICT) via integrating with external providers",
    "contact": {
      "name": "API Support",
      "url": "https://developers.pismo.io/support/"
    },
    "license": {
      "name": "Copyright Pismo"
    },
    "version": "0.0.1"
  },
  "servers": [
    {
      "url": "https://sandbox.pismolabs.io/pix-dict",
      "description": "Sandbox API server for testing."
    }
  ],
  "tags": [
    {
      "name": "Claims",
      "description": "Manage key ownership and key portability endpoints"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "parameters": {
      "AuthHeader": {
        "in": "header",
        "name": "Authorization",
        "required": true,
        "description": "Account token - token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a <b>401 Unauthorized</b> message.",
        "schema": {
          "type": "string",
          "example": "Bearer eyJhbGci...IUzUx"
        }
      },
      "IdempotencyKeyHeader": {
        "name": "Idempotency-Key",
        "in": "header",
        "description": "A unique UUID identifier to ensure the operation remains idempotent, allowing for operation repitition without causing unintended effects or duplication. An idempotent operation is one that can be applied multiple times, yet the outcome remains the same. it ensures that network errors, retries, or failures can occur without introducing inconsistencies.\n",
        "required": true,
        "schema": {
          "type": "string"
        },
        "example": "550e8400-e29b-41d4-a716-446655440000"
      }
    },
    "headers": {
      "XCidResponseHeader": {
        "description": "Request tracking identifier.",
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "AccountNumber": {
        "type": "string",
        "description": "Account number.",
        "maxLength": 20,
        "example": "98765432"
      },
      "AccountType": {
        "type": "string",
        "enum": [
          "CACC",
          "SLRY",
          "SVGS",
          "TRAN"
        ],
        "maxLength": 4,
        "description": "Account type:  \n  `CACC` - Checking account\n  `SVGS` - Savings account\n  `TRAN` - Transactional account (Brazil only). Also known as \"conta corrente\" in Portuguese, this is a bank account type designed for everyday financial transactions and is the most common type individuals and businesses use for day-to-day banking. \n  `SLRY` - Salary account. Employer deposits a fixed amount every month.\n",
        "example": "TRAN"
      },
      "BacenResponseTime": {
        "type": "string",
        "description": "Banco Central do Brasil (Central Bank of Brazil) response datetime. A RFC 3339 date-time value. For example -  `2023-04-12T23:20:50.52Z`.",
        "format": "date-time",
        "example": "2020-08-13T13:49:03Z"
      },
      "Branch": {
        "type": "string",
        "description": "Bank-assigned branch ID or ISPB (Identifcador do Sistema de Pagamento Brazil) number - the Brazilian Payment System identifier, an 8-digit value.",
        "example": "011"
      },
      "claim.CancelClaimRequest": {
        "type": "object",
        "required": [
          "claim_id",
          "reason"
        ],
        "properties": {
          "claim_id": {
            "$ref": "#/components/schemas/ClaimID"
          },
          "reason": {
            "$ref": "#/components/schemas/Reason"
          }
        }
      },
      "claim.CancelClaimResponse": {
        "type": "object",
        "required": [
          "cancel_reason",
          "confirm_reason"
        ],
        "properties": {
          "cancel_reason": {
            "$ref": "#/components/schemas/Reason"
          },
          "confirm_reason": {
            "$ref": "#/components/schemas/Reason"
          },
          "bacen_response_time": {
            "$ref": "#/components/schemas/BacenResponseTime"
          },
          "claim_id": {
            "$ref": "#/components/schemas/ClaimID"
          },
          "claimer": {
            "$ref": "#/components/schemas/claim.ClaimerData"
          },
          "claimer_account": {
            "$ref": "#/components/schemas/claim.ClaimerAccountData"
          },
          "completion_period_end_datetime": {
            "$ref": "#/components/schemas/CompletionPeriodEndDatetime"
          },
          "correlation_id": {
            "$ref": "#/components/schemas/CorrelationID"
          },
          "donor_participant": {
            "$ref": "#/components/schemas/DonorParticipant"
          },
          "key": {
            "$ref": "#/components/schemas/Key"
          },
          "key_type": {
            "$ref": "#/components/schemas/KeyType"
          },
          "last_modified_datetime": {
            "$ref": "#/components/schemas/LastModifiedDatetime"
          },
          "resolution_period_end_datetime": {
            "$ref": "#/components/schemas/ResolutionPeriodEndDatetime"
          },
          "status": {
            "$ref": "#/components/schemas/ClaimStatus"
          },
          "type": {
            "$ref": "#/components/schemas/ClaimType"
          }
        }
      },
      "claim.ClaimerAccountData": {
        "type": "object",
        "required": [
          "account_number",
          "account_type",
          "opening_datetime"
        ],
        "properties": {
          "account_number": {
            "$ref": "#/components/schemas/AccountNumber"
          },
          "account_type": {
            "$ref": "#/components/schemas/AccountType"
          },
          "opening_datetime": {
            "$ref": "#/components/schemas/OpeningDatetime"
          },
          "branch": {
            "$ref": "#/components/schemas/Branch"
          },
          "participant": {
            "$ref": "#/components/schemas/Participant"
          }
        }
      },
      "claim.ClaimerData": {
        "type": "object",
        "required": [
          "document_number",
          "name",
          "type"
        ],
        "properties": {
          "document_number": {
            "$ref": "#/components/schemas/DocumentNumber"
          },
          "name": {
            "$ref": "#/components/schemas/PersonName"
          },
          "type": {
            "$ref": "#/components/schemas/PersonType"
          },
          "trade_name": {
            "$ref": "#/components/schemas/TradeName"
          }
        }
      },
      "ClaimID": {
        "type": "string",
        "description": "Claim ID for key transfer. The Create key claim or Create DICT key claim endpoint returns this field.",
        "example": "123e4567-e89b-12d3-a456-426655440000"
      },
      "ClaimStatus": {
        "type": "string",
        "description": "Claim status",
        "example": "OPEN",
        "enum": [
          "OPEN",
          "WAITING_RESOLUTION",
          "CONFIRMED",
          "CANCELLED",
          "COMPLETED"
        ]
      },
      "ClaimType": {
        "type": "string",
        "description": "Key claim type:\n\n* `OWNERSHIP` - Transfers key ownership between individuals in the same or another bank.\n* `PORTABILITY`- Transfers key ownership for the same individual to another bank.\n",
        "example": "OWNERSHIP",
        "enum": [
          "OWNERSHIP",
          "PORTABILITY"
        ]
      },
      "CompletionPeriodEndDatetime": {
        "type": "string",
        "format": "date-time",
        "description": "Completion period end for claim. Present for claim type `OWNERSHIP`. ISO 8601 format.",
        "example": "2020-01-24T10:00:00Z"
      },
      "CorrelationID": {
        "type": "string",
        "format": "uuid",
        "description": "The correlation identifier is used to link related API requests and events. The Pismo engineering team can use this to track everything related to a call. If one is not passed, it is automatically generated and returned to the client in a response header.\n",
        "example": "ea8bc045-9ff7-439f-a318-2e6f974707a5"
      },
      "DocumentNumber": {
        "type": "string",
        "description": "A government document number, such as a Social Security number (US) or Cadastro de Pessoas Físicas number (Brazil). Must be numeric with 11-14 digits.\n",
        "minLength": 11,
        "maxLength": 14,
        "example": "123412341234"
      },
      "DonorParticipant": {
        "type": "string",
        "description": "Donor participant's ISPB (Identifcador do Sistema de Pagamento Brazil) number - the Brazilian Payment System identifier, an 8-digit value.",
        "maxLength": 8,
        "example": "99999011"
      },
      "Key": {
        "type": "string",
        "description": "Value, based on a key's type, used to encrypt Pix key.",
        "maxLength": 77,
        "example": "al_fresco@bourdain.com"
      },
      "KeyType": {
        "type": "string",
        "description": "User information that can be used to create a Pix key:\n* `CPF` - Cadastro de Pessoas Fisicas (Indiviual Taxpayer Registry) number. Similar to a Social Security number in the US. \n* `CNPJ` - Cadastro Nacional de Pessoa Juridica (National Registry of Legal Entities) number. Unique ID for legal entities, such as companies and organizations, in Brazil\n* `EMAIL` - Email \n* `PHONE` - Phone number\n* `EVP` - Endereco de pagamento virtual (virtual payment address). A randomly-generated UUID number.\n",
        "enum": [
          "CPF",
          "CNPJ",
          "PHONE",
          "EMAIL",
          "EVP"
        ],
        "example": "EMAIL"
      },
      "LastModifiedDatetime": {
        "type": "string",
        "format": "date-time",
        "description": "Last modified datetime. A RFC 3339 date-time value. For example -  `2023-04-12T23:20:50.52Z`.",
        "example": "2020-08-13T13:49:03Z"
      },
      "message.DetailMessage": {
        "type": "object",
        "properties": {
          "external": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/message.ExternalMessage"
            }
          },
          "parameters": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/message.ParameterMessage"
            }
          },
          "payload": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/message.PayloadMessage"
            }
          }
        }
      },
      "message.ExternalMessage": {
        "required": [
          "code",
          "message"
        ],
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Error code",
            "example": "PBE315"
          },
          "message": {
            "type": "string",
            "description": "Error message",
            "example": "Generic error"
          }
        }
      },
      "message.Message": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Error code",
            "example": "EPDA0001"
          },
          "details": {
            "$ref": "#/components/schemas/message.DetailMessage"
          },
          "message": {
            "type": "string",
            "description": "Error message",
            "example": "User not found"
          }
        }
      },
      "message.ParameterMessage": {
        "type": "object",
        "required": [
          "field",
          "message"
        ],
        "properties": {
          "field": {
            "type": "string",
            "description": "Parameter in error",
            "example": "query parameter"
          },
          "message": {
            "type": "string",
            "description": "Error message",
            "example": "Generic error"
          }
        }
      },
      "message.PayloadMessage": {
        "type": "object",
        "required": [
          "field",
          "message"
        ],
        "properties": {
          "field": {
            "type": "string",
            "description": "Field in error",
            "example": "Entity.field"
          },
          "message": {
            "type": "string",
            "description": "Error messsage",
            "example": "Generic error"
          }
        }
      },
      "OpeningDatetime": {
        "type": "string",
        "description": "Opening date time. A RFC 3339 date-time value. For example -  `2023-04-12T23:20:50.52Z`.",
        "format": "date-time",
        "example": "2020-08-13T13:49:03Z"
      },
      "Participant": {
        "type": "string",
        "description": "Participant's ISPB (Identifcador do Sistema de Pagamento Brazil) number - the Brazilian Payment System identifier, an 8-digit value.",
        "maxLength": 8,
        "example": "00115678"
      },
      "PersonName": {
        "type": "string",
        "description": "Person's name",
        "maxLength": 100,
        "example": "Jerry Atrick"
      },
      "PersonType": {
        "type": "string",
        "description": "Person type:  \n* `LEGAL_PERSON` - An actual person with legal rights\n* `NATURAL_PERSON` - An entity, such as an organization or company.\n",
        "enum": [
          "LEGAL_PERSON",
          "NATURAL_PERSON"
        ],
        "example": "NATURAL_PERSON"
      },
      "Reason": {
        "type": "string",
        "description": "Reason for request",
        "example": "USER_REQUESTED",
        "enum": [
          "USER_REQUESTED",
          "ACCOUNT_CLOSURE",
          "BRANCH_TRANSFER",
          "RECONCILIATION",
          "FRAUD",
          "DEFAULT_OPERATION",
          "RFB_VALIDATION"
        ]
      },
      "ResolutionPeriodEndDatetime": {
        "type": "string",
        "format": "date-time",
        "description": "Resolution period end for claim. ISO 8601 format.",
        "example": "2020-01-17T10:00:00Z"
      },
      "TradeName": {
        "type": "string",
        "description": "Name under which the business operates. Not necessarily the same as the legal name.",
        "maxLength": 100,
        "example": "Acme Widgets"
      }
    },
    "responses": {
      "202ClaimAccepted": {
        "description": "Accepted",
        "headers": {
          "x-cid": {
            "$ref": "#/components/headers/XCidResponseHeader"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/message.Message"
            },
            "examples": {
              "Creation request accepted and will processed async": {
                "value": {
                  "code": "EPDA0180",
                  "message": "Claim creation will continue asynchronously"
                }
              },
              "Confirm request accepted and will processed async": {
                "value": {
                  "code": "EPDA0162",
                  "message": "Claim confirmation will continue asynchronously"
                }
              },
              "Cancel request accepted and will processed async": {
                "value": {
                  "code": "EPDA0160",
                  "message": "Claim cancel will continue asynchronously"
                }
              },
              "Complete request accepted and will processed async": {
                "value": {
                  "code": "EPDA0161",
                  "message": "Claim complete will continue asynchronously"
                }
              }
            }
          }
        }
      },
      "400BadRequest": {
        "description": "Bad Request",
        "headers": {
          "x-cid": {
            "$ref": "#/components/headers/XCidResponseHeader"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/message.Message"
            }
          }
        }
      },
      "403Forbidden": {
        "description": "Forbidden",
        "headers": {
          "x-cid": {
            "$ref": "#/components/headers/XCidResponseHeader"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/message.Message"
            },
            "examples": {
              "EPDA0009": {
                "summary": "Missing required header 'x-tenant'",
                "value": {
                  "code": "EPDA0009",
                  "message": "Missing required header 'x-tenant'"
                }
              },
              "EPDA0010": {
                "summary": "Missing required header 'x-account-id'",
                "value": {
                  "code": "EPDA0010",
                  "message": "Missing required header 'x-account-id'"
                }
              },
              "EPDA0152": {
                "summary": "Missing required param 'id'",
                "value": {
                  "code": "EPDA0152",
                  "message": "Missing required param 'id'"
                }
              }
            }
          }
        }
      },
      "404NotFound": {
        "description": "Not Found",
        "headers": {
          "x-cid": {
            "$ref": "#/components/headers/XCidResponseHeader"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/message.Message"
            }
          }
        }
      },
      "500InternalServerError": {
        "description": "Internal server errpr",
        "headers": {
          "x-cid": {
            "$ref": "#/components/headers/XCidResponseHeader"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/message.Message"
            }
          }
        }
      },
      "502BadGateway": {
        "description": "Bad Gateway",
        "headers": {
          "x-cid": {
            "$ref": "#/components/headers/XCidResponseHeader"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/message.Message"
            },
            "examples": {
              "Provider authentication service error": {
                "value": {
                  "code": "EPDG0020",
                  "message": "Provider authentication service is unable to complete the request"
                }
              }
            }
          }
        }
      },
      "504GatewayTimeout1": {
        "description": "Gateway Timeout",
        "headers": {
          "x-cid": {
            "$ref": "#/components/headers/XCidResponseHeader"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/message.Message"
            },
            "examples": {
              "Service timeout": {
                "value": {
                  "code": "EPDA0000",
                  "message": "Timeout while executing the request"
                }
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true,
    "samples-enabled": true
  },
  "paths": {
    "/v2/pix/claims/cancel": {
      "post": {
        "summary": "Cancel key claim",
        "description": "Cancel a key's DICT claim. \n\nThe table below defines, depending on the reason and type, who can cancel. \n\nFor more information, refer to <a href=\"https://developers.pismo.io/pismo-docs/docs/pix-instant-payments#pix-key-transfer-key-claim\" >Pix key transfer (key claim)</a>\n\n* `OWNERSHIP` - Transfer key ownership between users in the same or another bank. \n\n* `PORTABILITY` - Transfer key ownership for the same user to another bank.\n\n\n<table border=\"1\">\n<tr>\n<th> </th>\n<th colspan=\"2\"> OWNERSHIP </th>\n<th colspan=\"3\"> PORTABILITY </th>\n</tr>\n<tr>\n<th> Reason </th>\n<th> Donor </th>\n<th> Claimer </th>\n<th> Donor </th>\n<th colspan=\"2\"> Claimer </th>\n</tr>\n<tr>\n<th colspan=4>&nbsp</td>\n<th>WAITING_RESOLUTION</th>\n<th>CONFIRMED</th>\n<tr bgcolor=\"#FFFAFA\">\n<td>USER_REQUESTED</td>\n<td></td>\n<td align=\"center\">√</td>\n<td align=\"center\">√</td>\n<td align=\"center\">√</td>\n<td aligm=\"center\">&nbsp;</td>\n</tr>\n<tr>\n<td>ACCOUNT_CLOSURE</td>\n<td align=\"center\">√</td>\n<td align=\"center\">√</td>\n<td align=\"center\"></td>\n<td align=\"center\">√</td>\n</tr>\n<tr bgcolor=\"#FFFAFA\">\n<td>FRAUD</td>\n<td align=\"center\">√</td>\n<td align=\"center\">√</td>\n<td align=\"center\">√</td>\n<td align=\"center\">√</td>\n<td align=\"center\">√</td>\n</tr>\n<tr>\n<td>DEFAULT_OPERATION</td>\n<td align=\"center\"></td>\n<td align=\"center\">√</td>\n<td align=\"center\">√</td>\n<td align=\"center\"></td>\n</tr>\n<tr bgcolor=\"#FFFAFA\">\n<td>RECONCILIATION</td>\n<td align=\"center\"></td>\n<td align=\"center\"></td>\n<td align=\"center\"></td>\n<td align=\"center\">√</td>\n <td align=\"center\">√</td>\n</tr>\n</table>\n\nOn PSP timeout, a `202 Accepted` response is returned and the process continues asynchronously, eventually emitting an event if it succeeds.\n\nThis endpoint generates a <a href=\"https://developers.pismo.io/events/docs/pix-dict-claim-status-change-1\" >Pix key claim status changed</a> event.\n",
        "operationId": "post-cancel-dict-claim",
        "tags": [
          "Claims"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "description": "Register DICT key request body",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/claim.CancelClaimRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Claim cancelled",
            "headers": {
              "x-cid": {
                "$ref": "#/components/headers/XCidResponseHeader"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/claim.CancelClaimResponse"
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/202ClaimAccepted"
          },
          "400": {
            "$ref": "#/components/responses/400BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/403Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/404NotFound"
          },
          "500": {
            "$ref": "#/components/responses/500InternalServerError"
          },
          "502": {
            "$ref": "#/components/responses/502BadGateway"
          },
          "504": {
            "$ref": "#/components/responses/504GatewayTimeout1"
          }
        }
      }
    }
  }
}
```