Conclude PIX Key Claim
Complete the final step of an ownership claim as the claimer. This endpoint is required **only for ownership claims** after the donor has confirmed the transfer. It is **not used for portability claims**, which complete automatically after donor confirmation.
curl --request POST \
--url 'https://api.somossimpay.com.br/v3/dict/claim/{pix_key_claim_id}/conclude' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'hmac: <HMAC_SIGNATURE>' \
--header 'Content-Type: application/json' \
--data '{
"verification_request_id": "550e8400-e29b-41d4-a716-446655440000",
"token": "123456"
}'{
"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."
}Endpoint
POST /v3/dict/claim/{pix_key_claim_id}/concludeHeaders
| 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 conclude | abc123def456ghi789 |
Body Details
{
"verification_request_id": "550e8400-e29b-41d4-a716-446655440000",
"token": "123456"
}| Field | Type | Description | Required or Optional |
|---|---|---|---|
| verification_request_id | String | Verification request ID (required for EMAIL and CELL_PHONE key types). Must be obtained from the verification endpoint with purpose CLAIM_CONCLUSION | required for EMAIL and CELL_PHONE |
| token | String | Verification token. For EMAIL/CELL_PHONE: OTP code (required). For CPF/CNPJ: not required (HMAC authentication is used instead) | required for EMAIL and CELL_PHONE |
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."
}| 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 COMPLETED after successful conclusion |
| resolution_deadline | String | Original deadline for resolution (ISO 8601 format) |
| conclusion_deadline | String | Deadline that was set for conclusion (ISO 8601 format) |
| last_modification_datetime | String | Timestamp of the last modification in DICT (ISO 8601 format) |
| key_creation_datetime | String | Date/time when the key was originally created in DICT (ISO 8601 format) |
| possession_start_datetime | String | Date/time when possession of the key started for the new owner (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 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:
| Key Type | Verification Required | Details |
|---|---|---|
| CELL_PHONE | Yes - OTP | Must request verification with purpose CLAIM_CONCLUSION first, then provide verification_request_id and OTP token |
| Yes - OTP | Must request verification with purpose CLAIM_CONCLUSION first, then provide verification_request_id and OTP token | |
| CPF | No | Authentication via HMAC signature only |
| CNPJ | No | Authentication via HMAC signature only |
Effect of Conclusion:
- Updates claim status to
COMPLETED - Creates a new
PixKeyAccountBankrecord 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):
- Day 0: Claimer includes claim (status: OPEN)
- Day 0-7: Waiting for donor to review (status: WAITING_RESOLUTION)
- Day 3: Donor confirms (status: CONFIRMED)
- Day 3-5: Claimer must conclude within 2 days (use this endpoint)
- 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