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.
POSThttps://api.somossimpay.com.br/v3/dict/claim
curl --request POST \
--url 'https://api.somossimpay.com.br/v3/dict/claim' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'hmac: <HMAC_SIGNATURE>' \
--header 'Content-Type: application/json' \
--data '{
"source_account_branch_identifier": "0001",
"source_account_number": "12345678",
"type": "CELL_PHONE",
"verification_request_id": "550e8400-e29b-41d4-a716-446655440000",
"token": "123456"
}'Response200
{
"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."
}Endpoint
POST /v3/dict/claimHeaders
| 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
{
"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:
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:
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:
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
{
"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_idandtoken(OTP code)- First request verification using the verification endpoint with purpose
CLAIM_INCLUSION - Then include the claim with the verification ID and OTP received
- First request verification using the verification endpoint with purpose
- 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)