put
https://api.somossimpay.com.br/v3/dict/key/
Changes the transactional account linked to a PIX key in the DICT (Brazilian PIX Key Directory). The origin and destination accounts must belong to the same client. EVP (random) keys cannot be altered. Requires HMAC signature for authentication.
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
Endpoint
PUT /v3/dict/key/{key}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 |
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| key | String | The active PIX key whose account binding will be changed | +5511999999999 or [email protected] |
Body Details
{
"source_account_branch_identifier": "0001",
"source_account_number": "123456-7"
}| Field | Type | Description | Required or Optional |
|---|---|---|---|
| source_account_branch_identifier | String | Branch (agency) identifier of the destination account that will be linked to the PIX key. | required |
| source_account_number | String | Account number of the destination account that will be linked to the PIX key. | required |
Request Examples
Alter phone PIX key binding:
PUT /v3/dict/key/+5511999999999
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
hmac: 57373705c83bc5efe41001790c54642e670088c0c87d56bc8f990f2260c7740b...
Content-Type: application/json
{
"source_account_branch_identifier": "0001",
"source_account_number": "987654-3"
}Alter email PIX key binding:
PUT /v3/dict/key/[email protected]
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
hmac: 57373705c83bc5efe41001790c54642e670088c0c87d56bc8f990f2260c7740b...
Content-Type: application/json
{
"source_account_branch_identifier": "0001",
"source_account_number": "555444-2"
}Response Details
{
"worked": true,
"key": "+5511999999999",
"created_at": "2024-01-15T10:30:00Z",
"possession_started_at": "2024-01-15T10:30:00Z",
"claim_opened_at": null
}| Field | Type | Description |
|---|---|---|
| worked | Boolean | Indicates whether the operation was successful (always true on success) |
| key | String | The PIX key value (unchanged) |
| created_at | DateTime | Date/time when the key was originally created in DICT (ISO 8601 format) |
| possession_started_at | DateTime | Date/time when possession of the key started in DICT (ISO 8601 format) |
| claim_opened_at | DateTime | Date/time when a claim was opened in DICT, if applicable (ISO 8601 format) |
Error Responses
| HTTP Code | Error Message | Description |
|---|---|---|
| 400 | EVP PIX keys cannot be altered | EVP (random) type keys cannot have their account binding changed |
| 400 | The PIX key is already linked to this account | The key is already bound to the specified destination account |
| 400 | The accounts belong to different clients | Origin and destination accounts must belong to the same client |
| 400 | Account not found | The destination account does not exist, is not active, or you don't have access to it |
| 400 | Invalid HMAC signature | The provided HMAC signature does not match the request body |
| 401 | Unauthorized | Invalid or missing authentication token. Ensure you are sending a valid Bearer token and HMAC signature |
| 404 | Active PIX key not found | The specified PIX key does not exist, is not active, or you don't have access to it |
| 500 | Internal server error | An unexpected error occurred on the server |
Business Rules
Key Type Restrictions:
- Only PIX keys of type
CPF,CNPJ,EMAIL, orCELL_PHONEcan be altered - EVP (random) keys cannot have their account binding changed
- The key must be active in the DICT
Account Requirements:
- The destination account must exist and be active
- You must have access to both the origin and destination accounts
- Origin and destination accounts must belong to the same client
Authentication:
- Requires HMAC signature in the
hmacheader, signing the raw JSON request body - Bearer token is required in the
Authorizationheader
Operation Behavior:
- The operation changes the account binding in the DICT
- The key value remains unchanged; only the linked account changes
- The operation is atomic: if it fails, no changes are made
Use Cases:
- Account Migration: Move PIX keys when migrating to a new account structure
- Account Restructuring: Reorganize keys across different accounts
- Key Consolidation: Consolidate multiple accounts' keys into a single account
- Operational Changes: Adjust key bindings due to operational requirements
Important Notes:
- Cannot change binding if the key is already linked to the specified destination account
- URL-encode the key parameter when necessary (e.g., for email addresses with special characters)
- Changes are immediately reflected in the Brazilian DICT system
Bad request - Invalid parameters or EVP key
Unauthorized - Invalid or missing authentication
PIX key not found
Internal server error