Exclude PIX Key

Time	Status	User Agent
Retrieving recent requests…

Endpoint

DELETE /v3/dict/key/{key}

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). Must sign the JSON object `{"key": "<key_value_in_path>"}`. See details in the Business Rules section.	hmac: 57373705c83bc5efe41001790c54642e670088c0c87d56bc8f990f2260c7740b99f4081ff231b87f82118c1e77a959e1f40eacf690a8fa61a827a9ba01d546f6

Parameter	Type	Description	Example
key	String	Active PIX key value to be excluded. Must be sent with URL-encoding when necessary (email, phone with +, etc.).	+5511999999999 or [email protected]

Exclude CELL_PHONE PIX key:

DELETE /v3/dict/key/%2B5511999999999
Authorization: Bearer <access_token>
hmac: <computed_hmac>

Exclude EMAIL PIX key:

DELETE /v3/dict/key/usuario%40exemplo.com
Authorization: Bearer <access_token>
hmac: <computed_hmac>

Exclude CPF PIX key:

DELETE /v3/dict/key/12345678901
Authorization: Bearer <access_token>
hmac: <computed_hmac>

Exclude EVP PIX key:

DELETE /v3/dict/key/f47ac10b-58cc-4372-a567-0e02b2c3d479
Authorization: Bearer <access_token>
hmac: <computed_hmac>

{
  "worked": true,
  "message": "PIX key excluded successfully."
}

Field	Type	Description
worked	Boolean	Always `true` for successful requests.
message	String	PIX key exclusion confirmation message.

HTTP Code	Error Message	Description
400	Authentication failed	The authentication token could not be validated.
400	Invalid HMAC signature	The HMAC signature provided in the header does not match the expected value. Verify that the object `{"key": "<value>"}` was signed correctly.
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 provided PIX key does not exist, is not active, or the user does not have permission to exclude it.
422	Validation error	Request validation failed. Check that the path parameter is present and in the correct format.

HMAC Generation:

To exclude a PIX key, the client must generate the HMAC by signing a specific JSON object.
The JSON object to be signed is: {"key": "<key_value_in_path>"}.
Example: If the PIX key to be excluded is [email protected], the client must:
1. Build the JSON object: {"key": "[email protected]"}
2. Sign this object with your secret key using the HMAC algorithm.
3. Send the signature in the hmac header of the request.
Important: Even though the DELETE request has no body, the HMAC must be calculated based on the object {"key": "value"} to validate the authenticity of the operation.

URL Encoding:

The PIX key value in the path must be encoded with URL-encoding when it contains special characters.
Examples:
- Phone with +: +5511999999999 → %2B5511999999999
- Email with @: [email protected] → usuario%40exemplo.com
- EVP (UUID): f47ac10b-58cc-4372-a567-0e02b2c3d479 (does not require encoding)

Validations:

The provided PIX key must exist and be active in the database.
The authenticated user must have PIX key deletion permission for the account associated with the key.
The PIX key must belong to an account that the authenticated user has access to.

Authentication:

The hmac header is required and must sign the object {"key": "<key_value>"} using your secret key.

Notes:

The PIX key exclusion in the DICT is performed immediately through the banking proxy.
After successful exclusion in the DICT, the key is marked as inactive (is_active = False) in the local database.
An excluded key cannot be restored — to use it again, a new registration will be required.
This operation is irreversible.