Update Virtual Account Information

This method allows the merchant to update non-sensitive information of an existing virtual bank account within Monnet. Changes can include metadata, labels, or other account attributes that do not affect the core banking identifiers or transactional capabilities.

Merchants can modify only the accounts they have created, and updates are reflected immediately in Monnet, ensuring that subsequent operations or queries return the latest account information. Sensitive fields such as the account number, personal information or country cannot be changed through this method.

✏️PATCH Endpoints

📘
URL
Certification: {environment-url}/v1/accounts/{accountId}
Production: {environment-url}/v1/accounts/{accountId}

📝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 optional parameters that can be included in the request body to update non-sensitive information of an existing virtual account, ensuring the changes are correctly applied and reflected in Monnet.

Field	Description
payer.email	String (Optional) Contact email. Must be a valid email format. Max length 50 - Min length 1
payer.phone.countryCode	String (Optional) numeric country calling code (no +). Max length 4 - Min length 1
payer.phone.number	String (Optional) national phone number (digits only). Max length 14 - Min length 1
account.name	String (Optional) Account label, nickname, or username used to create the account. Max length 20- Min length 3

🚧
Recommendations by Monnet
To ensure that the account is created correctly, we suggest reading the following notes

Items Notes
Proper use of the parameter account.name This field represents the account’s unique label or alias. The required format depends on the selected account type:

If type = CVU
The value must be a CVU Alias, following this pattern:
^[a-zA-Z0-9._-]{6,20}$ (no spaces allowed).

For all other types
The value functions as an account descriptor or label, and must follow:
^[a-zA-Z0-9._-]{3,15}$

Items	Notes
Proper use of the parameter `account.name`	This field represents the account’s unique label or alias. The required format depends on the selected account type: If type = CVU The value must be a CVU Alias, following this pattern: ^[a-zA-Z0-9._-]{6,20}$ (no spaces allowed). For all other types The value functions as an account descriptor or label, and must follow: ^[a-zA-Z0-9._-]{3,15}$

Request body example

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

{
  "payer": {
    "email": "[email protected]",
    "phone": {
      "countryCode": "54",
      "number": "987654321"
    }
  },
  "account": {
    "name": "jane.doe"
  }
}

📄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

{
  "id": "acc_8af98b8c8a4",
  "traceId": "93963JM-38A1A",
  "timestamp": "2025-11-10T15:14:22Z",
  "status": "ACTIVE",
  "payer": {
    "referenceId": "COMPANY-USER-1234",
    "type": "PERSON",
    "document": {
      "type": "CUIT",
      "number": "20123456783"
    },
    "firstName": "John",
    "lastName": "Doe",
    "companyName": null,
    "email": "[email protected]",
    "phone": {
      "countryCode": "54",
      "number": "987654321"
    }
  },
  "account": {
    "category": "VIRTUAL",
    "type": "CVU",
    "number": "200300310012",
    "country": "ARG",
    "currency": "ARS",
    "name": "jane.doe"
  },
  "metadata": {
    "segment": "PREMIUM",
    "external_ref": "EXT-654321"
  },
  "resultUrl": "https://monnet.com/virtual-accounts/id?va_7f92c9f8b1a54f0ba2c4c8d3"
}

📥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

{
  "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.