Create Virtual Account

This method allows the merchant to create a unique virtual bank account for a specific user within Monnet. The account is local to the user’s country and can receive transfers from both banking and non-banking institutions, functioning as an interoperable deposit channel whenever supported by the sender’s financial entity.

A merchant can create only one virtual account per user. However, the same user may hold additional virtual accounts in Monnet as long as they are created through different merchants.

📤POST Endpoints

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

📝Creation 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 + payer.referenceId)

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 mandatory parameters that must be included in the request body to ensure the successful creation of a virtual account.

Field	Description
payer.referenceId	String (Required) Internal merchant identifier for the user. Max length 36 - Min length 1
payer.type	String (Required) Payer category. Enum: PERSON, COMPANY.
payer.document.type	String (Required) Document type. For now we only accepted CUIT in ARG, RFC in MEX and DNI - RUC in PER.
payer.document.number	String (Required) Document number as a string (keep leading zeros, do not include hyphens, spaces, or periods, only digits)
payer.firstName	String (Optional) Required for PERSON type. Max length 50 - Min length 1
payer.lastName	String (Optional) Required for PERSON type. Max length 50 - Min length 1
payer.companyName	String (Optional) Required for COMPANY type. Max length 80 - Min length 1
payer.email	String (Optional) Contact email. Must be a valid email format. Max length 50 - Min length 1. The value of this field is not mandatory — you may send it as null or empty. However, the field must still be included in the request payload. This ensures a consistent API structure and preserves compatibility across all supported countries, as well as with future features of our API and business.
payer.phone.countryCode	String (Optional) Numeric country calling code (no +). Max length 4 - Min length 1. The value of this field is not mandatory — you may send it as null or empty. However, the field must still be included in the request payload. This ensures a consistent API structure and preserves compatibility across all supported countries, as well as with future features of our API and business.
payer.phone.number	String (Optional) National phone number (digits only). Max length 14 - Min length 1. The value of this field is not mandatory — you may send it as null or empty. However, the field must still be included in the request payload. This ensures a consistent API structure and preserves compatibility across all supported countries, as well as with future features of our API and business.
account.category	String (Required) Business category of the account. Enum: VIRTUAL. Max length 36 - Min length 1
account.type	String (Required) Account type. Enum: CVU, CCI and CLABE - For now we only accepted CVU in ARG, CLABE in MEX and CCI in PER
account.country	String (Required) Country code where the virtual account will exist. Use ISO 3166-1 alfa-3.
account.currency	String (Required) ISO 4217 currency code.
account.name	String (Required) Account label, nickname, or username used to create the account. Max length 20- Min length 3
metadata	Objet Collection of up to 5 key–value pairs that allows merchants to include custom complementary information when creating a subscription. Each element must contain the subfields key and value. The metadata included in the subscription creation will be replicated in subsequent operations and webhook notifications related to that subscription. If no metadata is provided, this field must be omitted.
key	String (optional) Identifier of the additional data sent within the metadata. Must not exceed 20 alphanumeric characters Allowed format - Letters (`a–z`, `A–Z`), digits (`0–9`), hyphen (`-`), underscore (`_`)
value	String (optional) Value associated with the corresponding key within the metadata. Must not exceed 100 characters. Allowed format - Allowed characters: letters, digits, spaces, and symbols: `- _ . : , / @` - Currency symbols allowed if needed (e.g. `S/ 150.00`, `$150.00`)

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

Items Notes
Proper use of the parameter payer.referenceId It is recommended that merchants use this field to send the internal identifier assigned to each customer, commonly known as the merchant’s internal user ID.
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 `payer.referenceId`	It is recommended that merchants use this field to send the internal identifier assigned to each customer, commonly known as the merchant’s internal user ID.
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": {
    "referenceId": "COMPANY-USER-1234",
    "type": "PERSON",
    "document": {
      "type": "CUIT",
      "number": "20123456783"
    },
    "firstName": "John",
    "lastName": "Doe",
    "companyName": null,
    "email": "[email protected]",
    "phone": {
      "countryCode": "54",
      "number": "989012931"
    }
  },
  "account": {
    "category": "VIRTUAL",
    "type": "CVU",
    "country": "ARG",
    "currency": "ARS",
    "name": "john.doe"
  },
  "metadata": {
    "external_ref": "EXT-123456",
    "segment": "VIP"
  }
}

📄Creation Response

📥Success Response Data

The successful creation response will include all the data you submitted in the original request. These fields may be echoed back exactly as provided or normalized (e.g., formatting adjustments, standardized casing, or validated identifiers) according to Monnet’s internal processing rules.

In addition to your submitted data, the response also includes server-generated fields required for resource identification, operation traceability, and Virtual Account lifecycle management. Merchants should persist these values and rely on them as the authoritative source for account management.

Below, we describe only the new fields added by Monnet in the response.

Field	Description
id	String (Required) Unique identifier assigned to the newly created Virtual Account.
traceId	String (Required) Operation trace identifier used to correlate and track the request across Monnet’s systems.
timestamp	String (Required) Timestamp indicating when the Virtual Account was created and processed by Monnet. (ISO-8601).
status	String (Required) Current operational status of the Virtual Account (e.g., ACTIVE, INACTIVE)
account.number	String (Required) Unique virtual bank account number created for the user. The account is linked to both the user and the merchant within Monnet.
resultUrl	String (Opcional) URL pointing to the resource or detailed view associated with the Virtual Account

✅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": "989012931"
    }
  },
  "account": {
    "category": "VIRTUAL",
    "type": "CVU",
    "number": "200300310012",
    "name": "john.doe",
    "country": "ARG",
    "currency": "ARS"
  },
  "metadata": {
    "external_ref": "EXT-123456",
    "segment": "VIP"
  },
  "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.