Enable or Disable Virtual Account

Availability: Argentina | Brazil | Mexico

PUT {{api_base_url}}/api/virtual-account/:externalId/activation/:status

---

You can temporarily enable or disable a virtual account to control the receipt of payments. When a virtual account is disabled, any incoming payments will be rejected.

Note

Virtual accounts in Chile currently support only offline operations. For full details on how to proceed, refer to the Offline Virtual Account Creation article.

Request

To enable or disable a virtual account, send a PUT request to the /api/virtual-account/:externalId/activation/:status 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.
status	String	Required	enable or disable.

Request Examples

Below is an example using curl:

enable

curl --location \
--request PUT '{{api_base_url}}/api/virtual-account/fb5c9683-cfac-40c9-b81d-ad99de86c0d2/activation/enable' \
--header 'Authorization: Bearer  <your_access_token>'

disable

curl --location \
--request PUT '{{api_base_url}}/api/virtual-account/fb5c9683-cfac-40c9-b81d-ad99de86c0d2/activation/disable' \
--header 'Authorization: Bearer  <your_access_token>'

Response

A successful request returns an HTTP status code 200, along with the updated status of the virtual account. 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
currency	String	Currency codes.	Currency codes.	ARS
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
internalId	String	Localpayment transaction identifier.		d710312c-8c3f-4b65-8e62-7f83eeba321a
accountNumber	String	Localpayment account number.
beneficiary	Object	Information about the virtual account beneficiary.
beneficiary.type	String	Beneficiary type.	COMPANY, INDIVIDUAL	646011319800152616
beneficiary.name	String	Beneficiary name.
beneficiary.document	Object	Beneficiary documentation.
beneficiary.document.type	String	The type of identity document, such as a National Identity Number, Social Security Number, or Driver's License, depending on the country of issuance.
beneficiary.document.id	String	Identity document number (usually a number). This must be a valid number according to the rules for the specific document type.
beneficiary.lastName	String	Beneficiary's last name.
beneficiary.fullName	String	Beneficiary's full name.
beneficiary.bank	Object	Beneficiary Bank Information.
beneficiary.bank.branch	Object	Bank branch details.
beneficiary.bank.branch.code	String	Branch code.
beneficiary.bank.account	Object	Beneficiary's bank account details.
beneficiary.bank.account.number	String	Virtual Account Number (VAN) to which the customer must complete the payment.		646011319800152616
beneficiary.bank.account.aliases	Array of objects	Configured aliases for a virtual account. Available only for virtual accounts in Brazil.
beneficiary.bank.account.aliases.type	String	The type of alias (e.g., E).	E , P or RandomKeyCode	P
beneficiary.bank.account.aliases.value	String	Alias value.
beneficiary.bank.account.owner	Object	Account owner's document details.
beneficiary.bank.account.owner.document	Object	Account owner's document
status	Object	Operation status.
status.code	String	Status code
status.description	String	Status description
status.detail	String	Additional status information.
errors	Array of objects	Array of errors that occurred during the transaction. If the transaction was successful, this array will be empty.

Response Examples

Argentina

{
    "currency": "ARS",
    "externalId": "de14bcf2-15ee-22e3-ab59-99c3fcba31e8",
    "internalId": "ab111111-88cf-4ac3-8fe5-49610795a33d",
    "accountNumber": "{{YourAcountNumber}}",
    "beneficiary": {
        "type": "INDIVIDUAL",
        "name": "John",
        "document": {
            "type": "CUIL",
            "id": "27-32548697-5"
        },
        "bank": {
            "branch": {},
            "account": {
                "number": "0000472900016608609046",
                "aliases": [],
                "owner": {
                    "document": {}
                }
            }
        },
        "fullName": "John Doe",
        "lastName": "Doe"
    },
    "status": {
        "code": "300",
        "description": "DISABLED",
        "detail": "Virtual account disabled"
    },
    "errors": []
}

Brazil

{
    "currency": "BRL",
    "externalId": "7ad8bd1f-7227-4de7-9683-ff1f8ad635c5",
    "internalId": "762d92db-340f-456b-97e1-39ff315c908a",
    "accountNumber": "{{YourAcountNumber}}",
    "beneficiary": {
        "type": "INDIVIDUAL",
        "name": "John",
        "document": {
            "type": "RG",
            "id": "12.345.678-9"
        },
        "bank": {
            "branch": {},
            "account": {
                "number": "0b477655-78b0-4eac-bbc1-6db1b72f4281",
                "aliases": [],
                "owner": {
                    "document": {}
                }
            }
        },
        "fullName": "John Doe",
        "lastName": "Doe"
    },
    "status": {
        "code": "300",
        "description": "DISABLED",
        "detail": "Virtual account disabled"
    },
    "errors": []
}

Mexico

{
    "currency": "MXN",
    "externalId": "fb5c9683-cfac-40c9-b81d-ad99de86c0d2",
    "internalId": "de052584-e3ef-4b13-a9c9-f76074fa33ab",
    "accountNumber": "{{YourAcountNumber}}",
    "cvu": "646011319800153220",
    "beneficiary": {
        "type": "INDIVIDUAL",
        "name": "John",
        "document": {
            "type": "RFC",
            "id": "EXTF900101NI1"
        },
        "bank": {
            "branch": {},
            "account": {
                "number": "646011319800153220",
                "aliases": [],
                "owner": {
                    "document": {}
                }
            }
        },
        "fullName": "John Doe",
        "lastName": "Doe"
    },
    "status": {
        "code": "300",
        "description": "DISABLED",
        "detail": "Virtual account disabled"
    },
    "errors": []
}

Error Response Example

{
  "timestamp": "2025-01-07T00:03:14.639+00:00",
  "status": 400,
  "error": "Bad Request.",
  "message": "Virtual Account doesn't exist",
  "path": "/virtual-account/e36ef959-12d4-4cf0-b00c-99dc51798f4b2/activation/disable"
}