--- updatedAt: 2026-06-11T16:01:52.000Z --- Fetch the complete documentation index at: https://simpay-prod.readme.io/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version. # Cancel PIX Key Claim Cancel an ongoing PIX key claim. Both the claimer (requesting party) and donor (current key holder) can cancel a claim while it is in OPEN or WAITING_RESOLUTION status. ## Endpoint ``` POST /v3/dict/claim/{pix_key_claim_id}/cancel ``` ## Headers | Parameter | Type | Description | Example | | :---------------- | :----- | :---------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Authorization** | String | Bearer + Access\_token | Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEzMzAwOTMxLCJpYXQiOjE3MTMyOTczMzEsImp0aSI6Ijc2ZWI4ZTE5ZjM4YjQ4NmZiODdmNzNjNTdkMWVmNDJhIiwidXNlcl9pZCI6MjQ2fQ.5zekMa7CUj9p-MvNHns5ke4ZPhYV3Y1CLOsYL7hDUUo | | **hmac** | String | HMAC signature for request authentication | hmac: 57373705c83bc5efe41001790c54642e670088c0c87d56bc8f990f2260c7740b99f4081ff231b87f82118c1e77a959e1f40eacf690a8fa61a827a9ba01d546f6 | ## Path Parameters | Parameter | Type | Description | Example | | :---------------------- | :----- | :------------------------------------- | :----------------- | | **pix\_key\_claim\_id** | String | The internal ID of the claim to cancel | abc123def456ghi789 | ## Body Details ```json Body JSON (Raw) { "cancellation_reason": "USER_REQUESTED" } ``` | Field | Type | Description | Required or Optional | | :----------------------- | :----- | :---------------------------------------------------------------------------------------------------- | :------------------- | | **cancellation\_reason** | String | Reason for cancellation. Valid values: `USER_REQUESTED` (user requested) or `FRAUD` (suspected fraud) | required | ## Request Examples **Cancel claim with user requested reason:** ```http POST /v3/dict/claim/abc123def456ghi789/cancel Authorization: Bearer access_token_here hmac: computed_hmac_signature Content-Type: application/json { "cancellation_reason": "USER_REQUESTED" } ``` **Cancel claim for fraud:** ```http POST /v3/dict/claim/abc123def456ghi789/cancel Authorization: Bearer access_token_here hmac: computed_hmac_signature Content-Type: application/json { "cancellation_reason": "FRAUD" } ``` **HMAC Payload:** The HMAC signature must be computed over the JSON payload: ```json { "pix_key_claim_id": "abc123def456ghi789", "cancellation_reason": "USER_REQUESTED" } ``` ## Response Details ```json Response { "worked": true, "pix_key_claim_id": "abc123def456ghi789", "claim_id": "123e4567-e89b-12d3-a456-426655440000", "status": "CANCELLED", "cancellation_reason": "USER_REQUESTED", "cancelled_by_role": "CLAIMER", "last_modification_datetime": "2024-12-24T14:30:00.000Z", "message": "Claim cancelled successfully in the DICT." } ``` | Field | Type | Description | | :------------------------------- | :------ | :------------------------------------------------------------------------ | | **worked** | Boolean | Always `true` for successful requests. | | **pix\_key\_claim\_id** | String | Internal database ID for this claim record | | **claim\_id** | String | DICT claim identifier (UUID format) | | **status** | String | Updated claim status. Should be `CANCELLED` after successful cancellation | | **cancellation\_reason** | String | Reason for cancellation: `USER_REQUESTED` or `FRAUD` | | **cancelled\_by\_role** | String | Role of the party who cancelled: `CLAIMER` or `DONOR` | | **last\_modification\_datetime** | String | Timestamp of the last modification in DICT (ISO 8601 format) | | **message** | String | Informative message about the operation result | ## Error Responses | HTTP Code | Error Message | Description | | :-------- | :---------------- | :--------------------------------------------------------------- | | 400 | Company not found | The company associated with the authenticated user was not found | \| 400 | Claim can only be cancelled in status OPEN or WAITING\_RESOLUTION | Claim is not in a cancellable status. Only OPEN or WAITING\_RESOLUTION claims can be cancelled | \| 400 | Claim has no DICT claim\_id | The claim does not have a DICT identifier yet and cannot be cancelled | \| 400 | Cancellation reason not allowed | The provided cancellation reason is not valid for the user's role in this claim | \| 401 | Unauthorized | Invalid or missing authentication token, or invalid HMAC signature | \| 404 | Pix key claim not found | The claim ID was not found, or does not belong to the authenticated company, or user lacks permission | \| 422 | Validation error | Request validation failed. Check that all required fields are present and in the correct format. | ## Business Rules **Who Can Cancel:** * **Claimer**: Can cancel claims where they are the requesting party * **Donor**: Can cancel claims where they are the current key holder * You must have access to the account associated with the claim **When to Cancel:** * Claim must be in **OPEN** or **WAITING\_RESOLUTION** status * Claims that are already CONFIRMED, COMPLETED, or CANCELLED cannot be cancelled * Once a claim moves to CONFIRMED status, only the claimer can act (conclude for ownership) **Cancellation Reasons:** Two cancellation reasons are supported, and their usage depends on the claim context: | Reason | Code | Claimer Can Use? | Donor Can Use? | Description | | ------------------- | ---- | ---------------- | -------------- | ---------------------------------------------------- | | **USER\_REQUESTED** | 0 | ✅ Yes | ✅ Yes | User requested the cancellation (most common reason) | | **FRAUD** | 4 | ✅ Yes | ✅ Yes | Suspected fraud or unauthorized claim | **Authentication Requirements:** * Must provide valid `hmac` header * HMAC must be computed over the JSON containing both `pix_key_claim_id` and `cancellation_reason` **Effect of Cancellation:** * Updates claim status to `CANCELLED` * Records cancellation reason in the claim * Records which role (CLAIMER or DONOR) cancelled * Records the authenticated user's ID for audit purposes * For portability claims with donor cancellation, the key remains with the donor * For ownership claims with donor cancellation, the key ownership stays with the donor **Important Notes:** * Cancellation is **final and cannot be undone** * After cancellation, a new claim can be created for the same key (subject to business rules) * The cancellation is immediately communicated to DICT * Both parties are notified of the cancellation * Cancelled claims remain in the database for audit purposes * The system validates that the cancellation reason is appropriate for the user's role and claim type **Common Use Cases:** * **User requested**: User changed their mind, no longer wants the key transfer * **Fraud**: Suspected fraudulent claim attempt, unauthorized request, or security concerns # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "version": "3.0.0", "title": "Banking & PIX API", "description": "Complete API documentation for the banking and PIX payment platform." }, "servers": [ { "url": "https://api.somossimpay.com.br/" } ], "security": [], "tags": [ { "name": "DICT-API", "description": "DICT-API endpoints" } ], "paths": { "/v3/dict/claim/{pix_key_claim_id}/cancel": { "post": { "operationId": "post_dict_claim_pix_key_claim_id_cancel", "summary": "Cancel PIX Key Claim", "description": "Cancel an ongoing PIX key claim. Both the claimer (requesting party) and donor (current key holder) can cancel a claim while it is in OPEN or WAITING_RESOLUTION status.", "tags": [ "DICT-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "pix_key_claim_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The pix_key_claim_id identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "x-readme": { "explorer-enabled": false, "proxy-enabled": true, "samples-languages": [ "curl", "python", "javascript", "java", "go" ] } } ```