--- updatedAt: 2026-06-11T16:01:50.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. # Include PIX Key Claim Initiate a new PIX key claim process to transfer a key via portability (same owner) or request ownership of a key registered to a different owner. ## Endpoint ``` POST /v3/dict/claim ``` ## Headers | Parameter | Type | Description | Example | | :---------------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Authorization** | String | Bearer + Access\_token | Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEzMzAwOTMxLCJpYXQiOjE3MTMyOTczMzEsImp0aSI6Ijc2ZWI4ZTE5ZjM4YjQ4NmZiODdmNzNjNTdkMWVmNDJhIiwidXNlcl9pZCI6MjQ2fQ.5zekMa7CUj9p-MvNHns5ke4ZPhYV3Y1CLOsYL7hDUUo | | **hmac** | String | HMAC (Hash-based Message Authentication Code) is an authentication algorithm that combines a private key with a message to create a Message Authentication Code (MAC). | hmac: 57373705c83bc5efe41001790c54642e670088c0c87d56bc8f990f2260c7740b99f4081ff231b87f82118c1e77a959e1f40eacf690a8fa61a827a9ba01d546f6 | ## Body Details ```json Body JSON (Raw) { "source_account_branch_identifier": "0001", "source_account_number": "12345678", "type": "CELL_PHONE", "verification_request_id": "550e8400-e29b-41d4-a716-446655440000", "token": "123456" } ``` | Field | Type | Description | Required or Optional | | :-------------------------------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------- | | **source\_account\_branch\_identifier** | String | Branch identifier of the source account | required | | **source\_account\_number** | String | Account number of the source account | required | | **type** | String | PIX key type. Valid values: CPF, CNPJ, CELL\_PHONE, EMAIL (EVP not allowed for claims) | required | | **verification\_request\_id** | String | Verification request ID (required for EMAIL and CELL\_PHONE key types). Must be obtained from the verification endpoint first | 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 **Portability claim with phone number:** ```http POST /v3/dict/claim Authorization: Bearer access_token_here hmac: computed_hmac_signature Content-Type: application/json { "source_account_branch_identifier": "0001", "source_account_number": "12345678", "type": "CELL_PHONE", "verification_request_id": "550e8400-e29b-41d4-a716-446655440000", "token": "123456" } ``` **Ownership claim with CPF:** ```http POST /v3/dict/claim Authorization: Bearer access_token_here hmac: computed_hmac_signature Content-Type: application/json { "source_account_branch_identifier": "0001", "source_account_number": "12345678", "type": "CPF" } ``` **Portability claim with email:** ```http POST /v3/dict/claim Authorization: Bearer access_token_here hmac: computed_hmac_signature Content-Type: application/json { "source_account_branch_identifier": "0001", "source_account_number": "12345678", "type": "EMAIL", "verification_request_id": "6b3e2bc7-9a12-4c8e-bf72-335aa814d091", "token": "789012" } ``` ## Response Details ```json Response { "worked": true, "pix_key_claim_id": "abc123def456ghi789", "claim_id": "123e4567-e89b-12d3-a456-426655440000", "type": "CELL_PHONE", "key": "+5511999999999", "claim_type": "PORTABILITY", "status": "OPEN", "resolution_deadline": "2024-12-31T23:59:59.999Z", "conclusion_deadline": "2025-01-02T23:59:59.999Z", "created_at": "2024-12-24T10:30:00.000Z", "message": "Claim opened 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) | | **type** | String | PIX key type being claimed | | **key** | String | The PIX key value being claimed | | **claim\_type** | String | Type of claim: `PORTABILITY` or `OWNERSHIP` | | **status** | String | Current claim status. Initially `OPEN` | | **resolution\_deadline** | String | Deadline for donor to respond (ISO 8601 format). Typically 7 days from creation | | **conclusion\_deadline** | String | Deadline for claimer to conclude (ownership claims only). Typically 2 days after confirmation | | **created\_at** | String | Timestamp when the claim was created (ISO 8601 format) | | **message** | String | Informative message about the operation result | ## Error Responses | HTTP Code | Error Message | Description | | :-------- | :----------------------------- | :------------------------------------------------------------------------------------------------------- | | 400 | Invalid key type | The key type provided is invalid or not supported for claims (e.g., EVP) | | 400 | Verification required | Verification request ID and token are required for EMAIL and CELL\_PHONE keys | | 400 | HMAC header required | HMAC authentication header is missing | | 400 | Company not found | The company associated with the authenticated user was not found | | 400 | Account not found | The source account was not found or is not active | | 400 | AccountBank is closed | The account is closed and cannot be used | | 401 | Unauthorized | Invalid or missing authentication token. Ensure you are sending a valid Bearer token and HMAC signature. | | 404 | Verification request not found | The verification request ID was not found or has expired | | 422 | Validation error | Request validation failed. Check that all required fields are present and in the correct format. | ## Business Rules **Key Type Restrictions:** * EVP (random) keys cannot be claimed - users must create a new random key instead * Email keys can only be used for portability claims, not ownership claims * Phone, CPF, and CNPJ keys support both portability and ownership claims **Verification Requirements:** * **Email and Phone keys**: Must provide `verification_request_id` and `token` (OTP code) * First request verification using the verification endpoint with purpose `CLAIM_INCLUSION` * Then include the claim with the verification ID and OTP received * **CPF/CNPJ keys**: Authentication via HMAC signature only (no token needed) **Claim Type Determination:** * System automatically determines if the claim is **PORTABILITY** or **OWNERSHIP** based on: * If the key is registered to the same CPF/CNPJ → PORTABILITY * If the key is registered to a different CPF/CNPJ → OWNERSHIP **Account Requirements:** * Source account must be active and not blocked * You must have access to the specified account **Existing Claims:** * Only one active claim per key is allowed * If a claim already exists, the endpoint will return an error **Important Notes:** * Portability claims: Donor has 7 days to respond; automatic confirmation if no response * Ownership claims: Donor must explicitly confirm; claimer must then conclude within 2 days * Both claimer and donor can cancel claims while in OPEN or WAITING\_RESOLUTION status * Once a claim is confirmed, only the claimer can act (conclude for ownership, or wait for automatic completion for portability) # 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": { "post": { "operationId": "post_dict_claim", "summary": "Include PIX Key Claim", "description": "Initiate a new PIX key claim process to transfer a key via portability (same owner) or request ownership of a key registered to a different owner.", "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" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "x-readme": { "explorer-enabled": false, "proxy-enabled": true, "samples-languages": [ "curl", "python", "javascript", "java", "go" ] } } ```