Endpoint

POST /v3/dict/claim/{pix_key_claim_id}/cancel

Headers

Path Parameters

Body Details

{
  "cancellation_reason": "USER_REQUESTED"
}

Request Examples

Cancel claim with user requested reason:

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:

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:

{
  "pix_key_claim_id": "abc123def456ghi789",
  "cancellation_reason": "USER_REQUESTED"
}

Response Details

{
  "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."
}

Error Responses

| 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:

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