Exclude PIX Key

DELETE https://api.somossimpay.com.br/v3/key/{key}

Removes the active PIX key from the DICT (Brazilian PIX Key Directory) and marks the key as inactive in the local database. The key is identified by the value provided in the request path.

Headers

Parameter	Type	Description	Example
Authorization	String	Bearer + Access_token	Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEzMzAwOTMxLCJpYXQiOjE3MTMyOTczMzEsImp0aSI6Ijc2ZWI4ZTE5ZjM4YjQ4NmZiODdmNzNjNTdkMWVmNDJhIiwidXNlcl9pZCI6MjQ2fQ.5zekMa7CUj9p-MvNHns5ke4ZPhYV3Y1CLOsYL7hDUUo
hmac	String	Required for API audience. HMAC signing the JSON object {"key": "<key_value_in_path>"}. See details in the Business Rules section.	hmac: 57373705c83bc5efe41001790c54642e670088c0c87d56bc8f990f2260c7740b99f4081ff231b87f82118c1e77a959e1f40eacf690a8fa61a827a9ba01d546f6
mfa	String	Required for Web audience. User's MFA (multi-factor authentication) TOTP code.	mfa: 123456

Path Parameters

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.).	[phone] or [email protected]

Request Examples

Exclude CELL_PHONE PIX key (Web audience):

HTTP

DELETE /v3/key/%2B5511999999999
Authorization: Bearer <access_token>
mfa: 123456

Exclude EMAIL PIX key (API audience):

HTTP

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

Exclude CPF PIX key (Web audience):

HTTP

DELETE /v3/key/12345678901
Authorization: Bearer <access_token>
mfa: 654321

Exclude EVP PIX key (API audience):

HTTP

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

Response Details

Response

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

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

Error Responses

HTTP Code	Error Message	Description
400	Authentication failed	The authentication token could not be validated.
400	MFA not registered.	The user does not have MFA (multi-factor authentication) configured. Applicable only for Web audience.
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. Applicable only for API audience.
401	Unauthorized	Invalid or missing authentication token. Ensure you are sending a valid Bearer token.
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.

Business Rules

HMAC Generation (API Audience):

• To exclude a PIX key via API audience, 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 +: [phone] → %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:

• API Audience: The hmac header is required and must sign the object {"key": "<key_value>"} using your secret key.
• Web Audience: The mfa header with the user's MFA TOTP code is required.

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.