Confirm Virtual Account Alias Creation

Availability: Brazil

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

---

After initiating the alias creation, a verification code is sent to the configured email address or phone number. You must use this code to finalize the alias setup. This code is valid for 5 minutes from the time of issuance.

Request

Confirm the alias by sending a POST request to the /api/virtual-account/:externalId/alias/confirm endpoint, including the verification code you received.

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]
confirmationCode	String	Required	Confirmation code.		285187

Request Examples

Below is an example using curl:

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

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]
alias.confirmationCode	String	Confirmation code.		285187
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]",
        "confirmationCode": "221595"
    },
    "status": {
        "code": "100",
        "description": "INPROGRESS",
        "detail": "Alias confirmed"
    }
}

Error Response Example

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