Create a Virtual Account (API)

Overview

The Virtual Account API allows merchants to provision dedicated bank accounts for their customers. When you initiate an account creation request, the API registers the user's information with the local clearinghouse and returns a unique payment instrument that can be shown to your customer.

ℹ️
Document Requirements
This API has specific identification requirements based on the target country. If you send DocumentType, the DocumentNumber becomes mandatory, and viceversa.

1. Choose your Environment

You must invoke a POST request to the following URLs according to your testing or production needs:

Environment	Endpoint
Development/Stage	`https://api.stage.bamboopayment.com/v3/api/VirtualAccount`
Production	`https://api.bamboopayment.com/v3/api/VirtualAccount`

2. Building the Request

Request Body Parameters

Parameter	Type	Required?	Description
`Country`	`string`	Yes	ISO 2-letter country code (e.g., `MX`, `AR`).
`Currency`	`string`	Yes	ISO 3-letter currency code (e.g., `MXN`, `ARS`).
`PaymentMethod`	`string`	Yes	The local clearinghouse method (e.g., `SPE`). Available payment methods: Virtual Accounts
`UniqueId`	`string`	No	Merchant's internal unique identifier for the customer. Highly recommended for reconciliation.
`AccountOwner`	`object`	Yes	Object containing the legal and personal details of the end-user.
`MetadataIn`	`object`	No	Additional key-value pairs for custom data routing.

ℹ️
Account Idempotency
If a creation request is sent with an ExternalReference that already exists for your merchant account, the API will not create a new duplicate account. Instead, it will safely return the existing active Virtual Account details.

AccountOwner Object

Parameter	Type	Required?	Description
`Type`	`string`	Yes	Entity type. Values: `INDIVIDUAL`, `COMPANY`.
`BusinessName`	`string`	Cond.*	The company name. (*Required if Type is `COMPANY`).
`FirstName`	`string`	Cond.*	The end-user's first name. (*Required if Type is `INDIVIDUAL`).
`LastName`	`string`	Cond.*	The end-user's last name. (*Required if Type is `INDIVIDUAL`).
`DocumentType`	`string`	No	e.g., `TAX_ID`, `RFC`, `CUIT`.
`DocumentNumber`	`string`	No	Alphanumeric string of the document number.
`Email`	`string`	No	Contact email address of the account owner.
`PhoneNumber`	`string`	No	Contact phone number (e.g., `+59899123456`).

3. Request Example

{
  "Country": "MX",
  "Currency": "MXN",
  "PaymentMethod": "SPE",
  "UniqueId": "Customer-123",
  "AccountOwner": {
    "Type": "COMPANY",
    "BusinessName": "Acme Corp Latam",
    "DocumentType": "RFC",
    "DocumentNumber": "ACME900101ABC",
    "Email": "[email protected]",
    "PhoneNumber": "+525512345678"
  },
  "MetadataIn": {
    "InternalSegment": "VIP_Customer"
  }
}

{
  "Country": "AR",
  "Currency": "ARS",
  "PaymentMethod": "BKT",
  "UniqueId": "Customer-123",
  "AccountOwner": {
    "Type": "INDIVIDUAL",
    "FirstName": "Juan",
    "LastName": "Pérez",
    "DocumentType": "CUIT",
    "DocumentNumber": "20301234567",
    "Email": "[email protected]",
    "PhoneNumber": "+5491123456789"
  },
  "MetadataIn": {
    "InternalSegment": "VIP_User"
  }
}

4. Understanding the Response

Once the API successfully creates the account, it will return the generated banking details.

⚠️
Displaying the Payment Instructions
Your platform must extract the BankAccount and BankName from the PaymentInstrument object and display them clearly to your user.

Response Parameters

Parameter	Type	Description
`VirtualAccountId`	`string`	Bamboo's unique internal identifier for this virtual account (e.g., `321355465202074912`).
`Status`	`string`	Current operational state. Will return `ACTIVE` upon successful creation.
`Created`	`string`	ISO 8601 timestamp of the account creation.
`OwnershipModel`	`string`	The legal ownership model of the generated account. Values: `BAMBOO_OWNED` (Master/FBO account) or `NAMED_ACCOUNT` (Registered under the specific `AccountOwner` details).
`Country`	`string`	The ISO 2-letter country code (e.g., `MX`, `AR`).
`Currency`	`string`	The ISO 3-letter currency code (e.g., `MXN`, `ARS`).
`UniqueId`	`string`	The original reference you sent in the request.
`PaymentMethod`	`string`	The local clearinghouse network used (e.g., `SPEI`, `MCC`).
`PaymentInstrument`	`object`	Contains the actual banking details to be displayed to the user.
`AccountOwner`	`object`	Echoes the legal and personal details of the end-user provided in the request.
`MetadataOut`	`object`	The metadata provided in the request, returned unchanged.
`ErrorCode`	`string`	The error code if the request failed, or `null` if successful.
`ErrorDescription`	`string`	A description of the error if the request failed, or `null` if successful.

PaymentInstrument Object

Parameter	Type	Description
`Type`	`string`	The type of payment instrument (e.g., `CLABE`).
`BankAccount`	`string`	The actual account number the user needs to transfer to (18-digit CLABE or 22-digit CVU).
`BankName`	`string`	The destination bank name (e.g., `STP`, `Bind`).
`BankAccountHolder`	`string`	The legal name under which the account was opened (e.g., `ACME Corp - Bamboo Payments`).

Response Examples

{
  "VirtualAccountId": "321355465202074912",
  "Status": "ACTIVE",
  "Created": "2026-06-09T19:03:10.808Z",
  "OwnershipModel": "BAMBOO_OWNED",
  "Country": "MX",
  "Currency": "MXN",
  "UniqueId": "Customer-123",
  "PaymentMethod": "SPEI",
  "PaymentInstrument": {
    "Type": "CLABE",
    "BankAccount": "012700001234567890",
    "BankName": "STP",
    "BankAccountHolder": "ACME Corp - Bamboo Payments"
  },
  "AccountOwner": {
    "Type": "COMPANY",
    "BusinessName": "Acme Corp Latam",
    "FirstName": null,
    "LastName": null,
    "DocumentNumber": "ACME900101ABC",
    "DocumentType": "RFC",
    "Email": "[email protected]",
    "PhoneNumber": "+525512345678"
  },
  "MetadataOut": {
    "InternalSegment": "VIP_Customer"
  },
  "ErrorCode": null,
  "ErrorDescription": null
}

{
  "VirtualAccountId": "321355465202074913",
  "Status": "ACTIVE",
  "Created": "2026-06-09T19:05:00.000Z",
  "OwnershipModel": "NAMED_ACCOUNT",
  "Country": "AR",
  "Currency": "ARS",
  "UniqueId": "Customer-123",
  "PaymentMethod": "BKT",
  "PaymentInstrument": {
    "Type": "CVU",
    "BankAccount": "0000003100000000000012",
    "BankName": "Bind",
    "BankAccountHolder": "Juan Pérez"
  },
  "AccountOwner": {
    "Type": "INDIVIDUAL",
    "BusinessName": null,
    "FirstName": "Juan",
    "LastName": "Pérez",
    "DocumentNumber": "20301234567",
    "DocumentType": "CUIT",
    "Email": "[email protected]",
    "PhoneNumber": "+5491123456789"
  },
  "MetadataOut": {
    "InternalSegment": "VIP_User"
  },
  "ErrorCode": null,
  "ErrorDescription": null
}

5. Error Codes

If your creation request fails (e.g., due to missing fields or validation issues), the API will return a 400 Bad Request containing an ErrorCode and ErrorDescription.

Below is the list of error codes specific to the Virtual Account creation process:

Error Code	Description
`VA001`	Country is required or invalid.
`VA002`	Currency is required or not supported for this region.
`VA003`	Payment method is required or invalid.
`VA004`	Account owner document type and document number are required in a valid format.
`VA005`	Account owner type is required.
`VA006`	Business name is required when the account owner type is `COMPANY`.
`VA007`	First name and Last name are required when the account owner type is `INDIVIDUAL`.
`VA008`	The merchant account ID is required or invalid.
`VA009`	The specified merchant account was not found.
`VA010`	The provided status is invalid.
`VA011`	The provided email address is invalid.
`VP001`	Virtual Account operation denied by bank or processor
`VP002`	Bank or processor error or timeout
`VP003`	Unable to process the request due to a configuration error
`VP004`	Virtual account not found or inactive at the bank or processor
`VP005`	Unknown error returned by bank or processor

Error Response Example

{
  "ErrorCode": "VA006",
  "ErrorDescription": "Business name is required when the account owner type is COMPANY."
}