Get Virtual Account Details

This method retrieves the latest and complete details of a virtual bank account created by the merchant in Monnet—including its current status, assigned account number, associated user information, and any metadata or lifecycle updates—ensuring the merchant can accurately track, validate, and manage the account within its own integration.

👁️‍🗨️GET Endpoints

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

📝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)

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.

🔍Query Params

Specifies the structure and parameters that can be included to obtain the details of a virtual account.

Field	Description
accountId	String (Optional) Monnet Internal ID returned when the account was created
accountNumber	String (Optional) The number or value of the virtual account.
documentType	String (Optional) Type of the payer’s document (CUIT, DNI, RUC). If provided, documentNumber becomes required.
documentNumber	String (Optional) Payer’s document number. Required if documentType is provided.

Example

All values must be sent as query parameters in the URL:

📄Response

📥Success Response Data

The successful response will return all the account data, reflecting the same values submitted during creation or any subsequent updates to the account’s details or status. Certain fields—such as traceId, timestamp, and resultUrl—may differ, as they represent the specific event generated at the time of the request.

✅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",
    "country": "ARG",
    "currency": "ARS",
    "name": "john.doe"
  },
  "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.