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 Endpoint

📘
URL
Endpoint: {{base_url}}/merchant-payin-accounts/v1/accounts
Please consult our Integrations team to obtain the environment-specific base URL required to begin your testing.

📝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)
X-Account-deposit-mode	✅ Yes	OWNER: Only the owner of the Virtual Account is allowed to make deposits. ANY: Any person is allowed to make the deposit.

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
owner.referenceId	String (Required) Internal merchant identifier for the user. Max length 36 - Min length 1
owner.type	String (Required) Qwner category. Enum: PERSON, COMPANY.
owner.document.type	String (Required) Document type. For now we only accepted CUIT in ARG, RFC in MEX, DNI - RUC in PER and RUN-RUT-PASS in CHL, TAX_ID is supported as a generic document type for all countries.
owner.document.number	String (Required) Document number as a string (keep leading zeros, do not include hyphens, spaces, or periods, only digits)
owner.firstName	String (Optional) Required for PERSON type. Max length 50 - Min length 1
owner.lastName	String (Optional) Required for PERSON type. Max length 50 - Min length 1
owner.companyName	String (Optional) Required for COMPANY type. Max length 80 - Min length 1
owner.companyInfo.url	String (Optional) Allows the user to enter the owner's URL. The URL is optional and must contain between 1 and 250 characters.
owner.companyInfo.mcc	String (Optional) Allows the user to specify the Merchant Category Code (MCC), an optional 4-digit code selected from the MCC list that identifies the merchant's business category.
owner.companyInfo.customsCode	String (Optional) Allows the user to specify the customs code, an optional code selected from the Customs Code list, with a length of 1 to 2 characters
owner.email	String (optional) Contact email. Must be in a valid format and contain between 1 and 50 characters. This field is required for Mexico (MEX) and optional for all other countries.
owner.phone.countryCode	String (optional) Numeric country calling code (no +). Max length 4 - Min length 1.
owner.phone.number	String (Optional) National phone number (digits only). Max length 14 - Min length 1.
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, CCI in PER, ACCOUNT_NUMBER in Chile.
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 (Optional) Account label, nickname, or username used to create the account. Validation rules by `account.type`: - CVU (Argentina only) • Must contain between 6 and 20 characters. • Allowed characters: letters (`A-Z`, `a-z`), numbers (`0-9`), dot (`.`), underscore (`_`), and hyphen (`-`). • Spaces are not allowed. • Example: `john.doe` - CLABE (Mexico only) • Must consist of exactly two words. • Each word must contain at least 2 letters. • Only alphabetic characters are allowed. • Words must be separated by a single space. • Numbers, symbols, accented characters, and `ñ` are not allowed. • Example: `John Doe` - CCI (Peru only) • Must contain between 3 and 15 characters. • Allowed characters: letters (`A-Z`, `a-z`), numbers (`0-9`), dot (`.`), underscore (`_`), and hyphen (`-`). • Spaces are not allowed. • Example: `JohnDoe` - ACCOUNT_NUMBER (Chile only) • Must contain between 3 and 15 characters. • Allowed characters: letters (`A-Z`, `a-z`), numbers (`0-9`), dot (`.`), underscore (`_`), and hyphen (`-`). • Spaces are not allowed. • Example: `JohnDoe` - Requests that include an `account.name` value that does not comply with the validation rules for the selected `account.type` will be rejected by the API and the account creation process will not continue.
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 owner.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 (Argentina)
The value must be a CVU Alias, following this pattern:
^[a-zA-Z0-9._-]{6,20}$ (no spaces allowed).

If type = CLABE (Mexico)
The value must be an account alias, composed of exactly two words, using alphabetic characters only (no numbers or special characters), with a maximum length of 20 characters in total, including the space.
Example: John Doe
^[A-Za-z]{1,9} [A-Za-z]{1,10}$

If type = CCI (Perú)
The value must be an account alias composed of two words, using only alphabetic characters (no numbers or special characters).
The words must be separated by a dot (.), which is also counted as part of the total length.
The total length of the alias (including the dot) must not exceed 20 characters.
Example: John.Doe
^[A-Za-z]{1,9}.[A-Za-z]{1,10}$

Items	Notes
Proper use of the parameter `owner.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 (Argentina) The value must be a CVU Alias, following this pattern: ^[a-zA-Z0-9._-]{6,20}$ (no spaces allowed). If type = CLABE (Mexico) The value must be an account alias, composed of exactly two words, using alphabetic characters only (no numbers or special characters), with a maximum length of 20 characters in total, including the space. Example: John Doe ^[A-Za-z]{1,9} [A-Za-z]{1,10}$ If type = CCI (Perú) The value must be an account alias composed of two words, using only alphabetic characters (no numbers or special characters). The words must be separated by a dot (.), which is also counted as part of the total length. The total length of the alias (including the dot) must not exceed 20 characters. Example: John.Doe ^[A-Za-z]{1,9}.[A-Za-z]{1,10}$

Request body example

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

{
	"owner": {
		"referenceId": "COMPANY-USER-1234",
		"type": "PERSON",
		"document": {
			"type": "CUIT",
			"number": "20123456783" },
			"companyInfo": {
				"url": "http:\\companyInfo.com",
				"mcc": "0742",
				"customscode": "1"
		},
		"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"
	}
}

{
	"owner": {
		"referenceId": "COMPANY-USER-1234",
		"type": "PERSON",
		"document": {
			"type": "DNI",
			"number": "12345678"
		},
		"firstName": "John",
		"lastName": "Doe",
		"companyName": null,
		"email": "[email protected]",
		"phone": {
			"countryCode": "51",
			"number": "989012931"
		},
		"companyInfo": {
			"url": "http:\\companyInfo.com",
			"mcc": "0742",
			"customscode": "1"
	},
	"account": {
		"category": "VIRTUAL",
		"type": "CCI",
		"country": "PER",
		"currency": "PEN",
		"name": "john.doe"
	},
	"metadata": {
		"external_ref": "EXT-123456",
		"segment": "VIP"
	}
}

{
  "owner": {
    "referenceId": "COMPANY-USER-1234",
    "type": "PERSON",
    "document": {
      "type": "RFC",
      "number": "PVSX150510VS0"
    },
    "firstName": "John",
    "lastName": "Doe",
    "companyName": null,
    "email": "[email protected]",
    "phone": {
      "countryCode": "52",
      "number": "1234567897"
    },
	"companyInfo": {
	  "url": "http:\\companyInfo.com",
	  "mcc": "0742",
	  "customscode": "1"
  },
  "account": {
    "category": "VIRTUAL",
    "type": "CLABE",
    "country": "MEX",
    "currency": "MXN",
    "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",
  "owner": {
    "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.

📤POST Endpoint

📘URL

📝Creation Request

🔐Header

📦Request Data

🚧

Recommendations by Monnet

Request body example

📄Creation Response

📥Success Response Data

✅Successful Response – 200

📥Error Response Data

❌Error Response Body Detail

Error Codes

📘
URL