Alter PIX 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.

PUThttps://api.socredsa.com.br/v3/dict/key/{key}

curl --request PUT \
  --url 'https://api.socredsa.com.br/v3/dict/key/{key}' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'hmac: <HMAC_SIGNATURE>' \
  --header 'Content-Type: application/json' \
  --data '{
  "source_account_branch_identifier": "0001",
  "source_account_number": "987654-3"
}'

Response200

{
  "worked": true,
  "key": "+5511999999999",
  "created_at": "2024-01-15T10:30:00Z",
  "possession_started_at": "2024-01-15T10:30:00Z",
  "claim_opened_at": null
}

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@example.com

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/user@example.com
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, or CELL_PHONE can 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 hmac header, signing the raw JSON request body
Bearer token is required in the Authorization header

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

curl --request PUT \
  --url 'https://api.socredsa.com.br/v3/dict/key/{key}' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'hmac: <HMAC_SIGNATURE>' \
  --header 'Content-Type: application/json' \
  --data '{
  "source_account_branch_identifier": "0001",
  "source_account_number": "987654-3"
}'

Response200

{
  "worked": true,
  "key": "+5511999999999",
  "created_at": "2024-01-15T10:30:00Z",
  "possession_started_at": "2024-01-15T10:30:00Z",
  "claim_opened_at": null
}