--- updatedAt: 2026-06-11T16:01:59.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. # 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. ## Endpoint ``` POST /v3/dict/claim/{pix_key_claim_id}/conclude ``` ## 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 conclude | abc123def456ghi789 | ## Body Details ```json Body JSON (Raw) { "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:** ```http 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):** ```http 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):** ```http POST /v3/dict/claim/abc123def456ghi789/conclude Authorization: Bearer access_token_here hmac: computed_hmac_signature Content-Type: application/json {} ``` ## Response Details ```json Response { "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` | | **EMAIL** | 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 `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 # 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}/conclude": { "post": { "operationId": "post_dict_claim_pix_key_claim_id_conclude", "summary": "Conclude PIX Key Claim", "description": "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.", "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" ] } } ```