Create Virtual Account Alias

Availability: Brazil

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

---

An alias can only be configured once per virtual account and cannot be modified after creation. To change the alias, the current one must be canceled and a new alias must be created with the desired value.

A verification code will be sent via email or SMS, depending on the alias type, to confirm the creation request. This code is valid for 5 minutes and must be submitted through the corresponding confirmation endpoint to complete the alias assignment process.

Request

To create an alias for a virtual account, you'll need to send a POST request to the /api/virtual-account/:externalId/alias endpoint.

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 Examples

Below are examples using curl:

Email address

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

Mobile phone number

curl --request POST \
     --url https://api.stage.localpayment.com/api/virtual-account/{externalId}/alias/ \
     --header 'Authorization: Bearer <your_access_token>' \
     --data '
{
  "type": "P",
  "value": "1151000001"
}
'

Response

A successful request returns an HTTP status code 200, along with the updated status of the virtual account alias. 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 creation pending confirmation"
    }
}

Error Response Example

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