Endpoint

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

Headers

Path Parameters

Body Details

{
  "verification_request_id": "550e8400-e29b-41d4-a716-446655440000",
  "token": "123456"
}

Request Examples

Conclude claim with phone verification:

POST /v3/dict/claim/abc123def456ghi789/conclude
Authorization: Bearer access_token_here
hmac: computed_hmac_signature
Content-Type: application/json

{
  "verification_request_id": "550e8400-e29b-41d4-a716-446655440000",
  "token": "123456"
}

Conclude claim with CPF key (no body needed):

POST /v3/dict/claim/abc123def456ghi789/conclude
Authorization: Bearer access_token_here
hmac: computed_hmac_signature
Content-Type: application/json

{}

Conclude claim with CNPJ key (no body needed):

POST /v3/dict/claim/abc123def456ghi789/conclude
Authorization: Bearer access_token_here
hmac: computed_hmac_signature
Content-Type: application/json

{}

Response Details

{
  "worked": true,
  "pix_key_claim_id": "abc123def456ghi789",
  "claim_id": "123e4567-e89b-12d3-a456-426655440000",
  "status": "COMPLETED",
  "resolution_deadline": "2024-12-31T23:59:59.999Z",
  "conclusion_deadline": "2025-01-02T23:59:59.999Z",
  "last_modification_datetime": "2024-12-26T16:45:00.000Z",
  "key_creation_datetime": "2023-06-15T08:30:00.000Z",
  "possession_start_datetime": "2024-12-26T16:45:00.000Z",
  "message": "Claim completed successfully in the DICT."
}

Error Responses

| 400 | Claim must be in status CONFIRMED to be concluded | Claim is not in the correct status. It must first be confirmed by the donor |
| 400 | Claim has no DICT claim_id | The claim does not have a DICT identifier yet and cannot be concluded |
| 400 | Only claimer role records can be concluded | This endpoint can only be used by the claimer (requesting party), not the donor |
| 400 | Only OWNERSHIP claims can be concluded | Portability claims complete automatically and do not use this endpoint |
| 400 | Verification required | Verification request ID and token are required for EMAIL and CELL_PHONE keys |

| 401 | Unauthorized | Invalid or missing authentication token, or invalid HMAC signature/OTP token |
| 404 | Pix key claim not found | The claim ID was not found, or does not belong to the authenticated company, or user lacks permission |
| 404 | Verification request not found | The verification request ID was not found, expired, or purpose mismatch |
| 422 | Validation error | Request validation failed. Check that all required fields are present and in the correct format. |

Business Rules

Who Can Conclude:

• Only the claimer (requesting party) can conclude a claim
• You must have access to the account associated with the claim
• Claimer must be authenticated and authorized

When to Conclude:

• Claim must be in CONFIRMED status (donor has confirmed the transfer)
• Claim type must be OWNERSHIP (not PORTABILITY)
• Conclusion must happen within the deadline (typically 2 days after confirmation)

Which Claims Require Conclusion:

• Ownership claims: ALWAYS require conclusion by the claimer
• Portability claims: Complete automatically after donor confirmation (no conclusion needed)

Verification Requirements:
Different key types require different verification methods at conclusion:

Effect of Conclusion:

• Updates claim status to COMPLETED
• Creates a new PixKeyAccountBank record linking the key to the claimer's account
• Activates the key for the claimer (is_active = True)
• Records key creation and possession start timestamps
• Sends cache update message to update company's PIX key cache
• Records the authenticated user's ID for audit purposes

Important Notes:

• This is the final step for ownership claims
• Once concluded, the claim cannot be undone or modified
• The key is immediately available for use by the new owner
• The original owner (donor) no longer has access to the key
• The conclusion must happen within the deadline or the claim may expire
• For portability claims, do NOT use this endpoint - they complete automatically

Timeline Example (Ownership Claim):

1. Day 0: Claimer includes claim (status: OPEN)
2. Day 0-7: Waiting for donor to review (status: WAITING_RESOLUTION)
3. Day 3: Donor confirms (status: CONFIRMED)
4. Day 3-5: Claimer must conclude within 2 days (use this endpoint)
5. Day 4: Claimer concludes (status: COMPLETED) ✓

Common Errors:

• Attempting to conclude a portability claim (not allowed)
• Attempting to conclude before donor confirmation
• Missing OTP verification for phone/email keys
• Expired verification request
• Conclusion deadline exceeded