Update Virtual Account Status

This method allows the merchant to update the operational status of an existing virtual bank account within Monnet. Status changes can include activating, deactivating, or blocking the account, controlling whether it can receive new deposits or be used in transactions.

Merchants can modify only the accounts they have created, and status updates are applied immediately in Monnet, ensuring that subsequent operations or queries reflect the current account state. Core account information, user details, or banking identifiers cannot be modified through this method.

---

✏️PATCH Endpoints

📘

URL

Certification: {environment-url}/v1/accounts/{accountId}/status

Production: {environment-url}/v1/accounts/{accountId}/status

📝Update Request

🔐Header

All requests to the this endpoint must include a custom Authorization header to ensure secure communication and proper merchant validation.

Header	Required	Value Format
X-Api-Key	✅ Yes	Public merchant identifier
X-Timestamp	✅ Yes	Unix timestamp of the request. Validated against a time window ≤ 2 minutes.
X-Signature	✅ Yes	HMAC_SHA512(secret-key, timestamp + api-key + account.Id)

The signature value must be a SHA-512 hash generated by concatenating the fields as decribed.

The secret-key is a credential provided by Monnet that must be used to build the final string before generating the hash.

📦Request Data

Specifies the structure and required parameters that must be included in the request body to update the operational status of an existing virtual account, ensuring the change is correctly applied and immediately reflected in Monnet.

Field	Description
status	String (Optional) Status to change the account. Enum: ACTIVE, INACTIVE, DELETED
reason	String (Optional) Short reason of change.

📘

Important to Know

The INACTIVEstatus is not available for ARG. If this status is sent in the request, the API will return an error. At this time, virtual accounts in Argentina can only be set to ACTIVE or DELETED; inactive an account is not supported for this country.

❗️

Be careful

Setting the account status to DELETED will permanently remove the user and disable the virtual account. The account will no longer be able to receive transfers, and this action is irreversible.

Request body example

The merchant must send a JSON payload with the following structure:

JSON

{
  "status": "INACTIVE",
  "reason": "Requested by merchant"
}

📄Update Response

📥Success Response Data

The successful response will return all the account data submitted in the update request, reflecting the changes made. Fields may be echoed back exactly as provided or normalized (e.g., formatting adjustments or standardized casing) according to Monnet’s internal processing rules.

In addition to the updated data, the response may include server-generated fields such as traceId, timestamp, or resultUrl to track the specific update event. Merchants should persist these values and rely on them as the authoritative source for the account’s current state.

✅Successful Response – 200

JSON

{
  "id": "acc_8af98b8c8a4",
  "traceId": "93963JM-38A1A",
  "timestamp": "2025-11-10T15:14:22Z",
  "status": "INACTIVE",
}

📥Error Response Data

This response indicates that the virtual account creation request could not be processed due to a business, validation, or service error. It provides both a general error message and a detailed list of one or more specific underlying errors.

Field	Description
error.type	String (Required) Classifies the general type of error. -> validation_error → data validation issues -> authentication_error → invalid signature or incorrect API key -> conflict_error → duplicated data or inconsistent state -> provider_error → external provider failure -> internal_error → unexpected server error
error.summary	String (Required) Short and clear description of the overall issue
details[].code	String (Required) Technical and stable error code generated by Monnet.
details[].message	String (Required) Description of the specific error
details[].field	String (Required) Refers to the affected field.
error.timestamp	String (Required) Timestamp indicating when the Virtual Account was created and processed by Monnet. (ISO-8601).
error.traceId	String (Required) Operation trace identifier used to correlate and track the request across Monnet’s systems.

❌Error Response Body Detail

JSON

{
  "error": {
    "type": "validation_error",
    "summary": "One or more fields failed validation",
    "details": [
      {
        "code": "ERR_MISSING_FIELD",
        "message": "Missing required field: beneficiary.email",
        "field": "beneficiary.email"
      },
      {
        "code": "ERR_INVALID_ACCOUNT_NAME",
        "message": "Invalid account.name: must match ^[a-zA-Z0-9._-]{3,15}$",
        "field": "account.name"
      }
    ],
    "timestamp": "2025-11-12T15:45:03Z",
    "traceId": "req_4f83b1f8c99"
  }
}

Error Codes

Review the list of error codes at the following link.