Cancel an Alias

Availability: Brazil

POST {{api_base_url}}/api/virtual-account/:externalId/alias/cancel

---

An alias linked to a virtual account can be canceled if it is no longer needed or was configured incorrectly. Canceling an alias deactivates it permanently, preventing any further payments from being processed through that alias.

Request

To cancel an alias, send a POST request to the /api/virtual-account/:externalId/alias/cancel endpoint, providing the required alias identifier.

Important

Once an alias is canceled, it cannot be reactivated or modified. To use a new alias, you must create a new one and complete the verification process again.

Headers

Parameter	Type	Required	Description
Authorization	String	Required	Mandatory. JWT token in format Bearer eyj0.... For more information about authentication, please refer to Authentication.

Path Parameters

Name	Type	Required	Description
externalId	String	Required	A unique identifier generated by your system to track the transaction (alphanumeric and hyphens). We recommend using UUID4 to ensure uniqueness.

Body Parameters

Parameter	Type	Required	Description	Possible values	Example
type	String	Required	The type of alias to be associated.	E, P	E
value	String	Required	Value indicating the type of alias to be configured—either an email address or a phone number.		[email protected]

Request Example

Below is an example using curl:

curl --request POST \
     --url {{api_base_url}}/api/virtual-account/94c6faee-0b35-4304-915b-e857981b4c01/alias/cancel \
     --header 'Authorization: Bearer <your_access_token>' \
     --data '
{
  "type": "E",
  "value": "[email protected]"
}'

You must have at least one alias associated with your account at all times.

Response

A successful request returns an HTTP status code 200, along with the updated deletion status. In contrast, if an error occurs, the API responds with an HTTP status code in the 40X range, and detailed error information is provided within the status object.

Body Parameters

Parameter	Type	Description	Possible values	Example
externalId	String	A unique identifier generated by your system to track the transaction (alphanumeric and hyphens). We recommend using UUID4 to ensure uniqueness.		a79aabec-16c6-4a84-8abe-be2dcd2e07a1
alias	Object	Alias information.
alias.type	String	The type of alias associated.	E, P	E
alias.value	Object	Information about the virtual account beneficiary.	Value indicating the type of alias to be configured—either an email address or a phone number.	[email protected]
status	Object	Operation status.
status.code	String	Status code
status.description	String	Status description
status.detail	String	Additional status information.

Response Examples

{
    "externalId": "94c6faee-0b35-4304-915b-e857981b4c01",
    "alias": {
        "type": "E",
        "value": "[email protected]"
    },
    "status": {
        "code": "100",
        "description": "INPROGRESS",
        "detail": "Alias cancellation confirmed"
    }
}

Error Response Example

{
    "externalId": "94c6faee-0b35-4304-915b-e857981b4c01",
    "alias": {
        "type": "E",
        "value": "[email protected]"
    },
    "status": {
        "code": "802",
        "description": "REJECTED"
    }
}