Create a Virtual Account
Generate virtual accounts for customers via Localpayment's API. Support for individual and batch processing.
Programmatically generate virtual accounts for your customers through Localpayment's API. Support both individual account creation and batch processing for multiple accounts.
Before You Begin
Ensure you have:
Virtual Account Creation Methods
We offer flexible options for virtual account creation to suit different operational needs. You can create virtual accounts through both online (API) and offline methods, and regardless of the method chosen, you have two creation modes available:
- Individual Creation : Generate single virtual accounts with specific configurations, ideal for customer-driven flows and scenarios requiring per-account customization.
- Batch Creation : Process multiple virtual accounts in a single operation, optimized for bulk account generation, mass onboarding, and scenarios where processing efficiency is prioritized.
| Country | Online | Offline |
|---|---|---|
| Argentina | ✔ | ✔ |
| Brazil | ✔ | ✔ |
| Chile | — | ✔ |
| Colombia | ✔ | — |
| Costa Rica (CRC & USD) | ✔ | ✔ |
| Mexico (SPEI, SPID, & TEF) | ✔ | ✔ |
| Peru (PEN & USD) | ✔ | — |
Beneficiary Requirements
Understanding beneficiary restrictions is crucial for successful virtual account creation. Each country has specific regulations regarding who can be listed as account beneficiaries, which directly impacts how you structure your payment operations.
Residency Requirements by Country
The following table outlines which beneficiary types are accepted in each country:
| Country | Local Residents | Foreign Residents | Account Owner | Alias | Bank Transfer Display Name |
|---|---|---|---|---|---|
| Argentina | ✅ | ✅ |
| Up to 1 alias creation |
|
| Brazil | ✅ | ✅ |
| N/A | Localpayment's legal entity name |
| Chile | ✅ | ✅ | FBO | N/A | Localpayment's legal entity name |
| Colombia | ✅ | ✅ | FBO | Default key | Localpayment's legal entity name |
| Mexico | ✅ | ✅ | DDA = Local Residents | N/A | Localpayment's legal entity name |
| Peru | ✅ | ✅ | FBO | N/A | Localpayment's legal entity name |
| Costa Rica | ✅ | ✅ | FBO | N/A | Localpayment's legal entity name |
Notes:
- Account Owner refers to the legal account holder name registered in the banking system (the name visible at the bank level). FBO (For Benefit Of) means the account is opened in Localpayment's name, holding funds for the benefit of the end customer. DDA (Demand Deposit Account) means the account is opened directly in the beneficiary's name.
- Alias: refers to the number of aliases (or type of alias) that can be registered for a virtual account, when supported.
- Bank Transfer Display Name: refers to the payer-facing name shown during an electronic fund transfer to the virtual account.
Beneficiary Information Required to Create a Virtual Account
Required Information:
- Beneficiary Type: Defines whether the virtual account belongs to an individual or a company:
- INDIVIDUAL: For a personal account.
- COMPANY: For a business/legal entity.
- Beneficiary Name: Full name of the person or legal business name.
- Beneficiary Document: Official identification information to verify identity.
- Address: Full address of the beneficiary.
- Website: The beneficiary’s website URL.
Country-Specific Requirements
Implementation details for Virtual Accounts vary by country. Any country not explicitly mentioned adheres to the standard procedure without special requirements. Review these requirements before integration:
| Property | Description |
|---|---|
| SLA Payment Confirmation | Real Time 24/7 |
| Processing Currency | ARS (Argentine Peso) |
| Minimum Transaction Amount | ARS 1.00 |
| Maximum Transaction Amount | No maximum limit. |
| Local Account Format | Cuenta Virtual Uniforme (CVU) |
| Clearinghouse | COELSA |
| Maximum Virtual Accounts | Unlimited |
| Virtual Account Creation Model | Online, Offline |
Account Format
In Argentina, the CVU (Clave Virtual Uniforme) is a 22-digit numeric code used by virtual accounts issued by PSPs (Payment Service Providers).
Structure:
- Positions 1-3: 3 digits - Issuing entity (PSP) code.
- Positions 4-7: 4 digits - Account type identifier within the PSP.
- Position 8: 1 digit - Verification digit (checksum).
- Positions 9-21: 13 digits - Unique account number within the PSP.
- Position 22: 1 digit – Control digit (checksum validator).
Example: 0000003112345678901234
| Property | Description |
|---|---|
| SLA Payment Confirmation | Real Time 24/7 |
| Processing Currency | BRL (Brazilian Real) |
| Minimum Transaction Amount | BRL 0.01 |
| Maximum Transaction Amount | BRL 1,000,000.00 |
| Local Account Format | Bank code, branch, and account number (used by both TED and Pix). For Pix, the payer can alternatively use the Pix Key (alias). |
| Supported Deposit Methods | Pix and TED |
| Clearinghouse | Pix, TED |
| Maximum Virtual Accounts | Unlimited |
| Virtual Account Creation Model | Online, Offline |
Account Format
In Brazil, each virtual account is identified by a Pix Key (alias) and accepts incoming funds through both Pix and TED. Both rails resolve to the same underlying account, and your integration receives the same webhook notification regardless of which rail the payer used.
For both TED and Pix transfers, the payer can use the following three fields from the API response:
beneficiary.bank.code— the bank code.beneficiary.bank.branch.code— the branch (agency) code.beneficiary.bank.account.number— the account number.
For Pix only, the payer can alternatively use the Pix Key (alias) returned in beneficiary.bank.account.aliases. No other fields are required.
Pix Key structure:
A Pix Key can be one of the following formats:
- Mobile phone number: 10 digits — the beneficiary's registered cell phone number.
- Email address: the beneficiary's registered email.
- Random key: Alphanumeric string generated by the system.
Notes:
- Individual accounts (PF) may register up to 5 Pix Keys, while corporate accounts (PJ) may register up to 20.
Be aware of local bank transfer limits and security rules to avoid transaction rejections. Refer to the Chile country guide for detailed information.
| Property | Description |
|---|---|
| SLA Payment Confirmation | Real Time 24/7 |
| Processing Currency | CLP (Chilean Peso) |
| Minimum Transaction Amount | CLP 1.00 |
| Maximum Transaction Amount | CLP 100,000,000.00 |
| Local Account Format | Account number (between 6 and 16 digits) |
| Clearinghouse | CCA |
| Maximum Virtual Accounts | Please contact your Account Manager |
| Virtual Account Creation Model | Offline |
| Property | Description |
|---|---|
| SLA Payment Confirmation | Real Time 24/7 |
| Processing Currency | COP (Colombian Peso) |
| Minimum Transaction Amount | COP 1.00 |
| Maximum Transaction Amount | COP 12,110,000.00 |
| Local Account Format | Sistema de Cuentas de Deposito (CUD) |
| Clearinghouse | ACH Colombia |
| Maximum Virtual Accounts | Unlimited |
| Virtual Account Creation Model | Online |
| Property | SINPE - IN | SINPE USD - IN |
|---|---|---|
| SLA Payment Confirmation | Real Time 24/7 | Real Time 24/7 |
| Processing Currency | CRC (Costa Rican Colón) | USD (US Dollar) |
| Minimum Transaction Amount | CRC 1.00 | USD 1.00 |
| Maximum Transaction Amount | CRC 100,000,000,000.00 | USD 1,000,000,000,000.00 |
| Local Account Format | IBAN (22 characters) | IBAN (22 characters) |
| Clearinghouse | SINPE (Banco Central de Costa Rica) | SINPE (Banco Central de Costa Rica) |
| Maximum Virtual Accounts | Unlimited | Unlimited |
| Virtual Account Creation Model | Online, Offline | Online, Offline |
Costa Rica Virtual Accounts
- Virtual accounts in Costa Rica cannot be disabled once created. To stop receiving payments, delete the account instead.
- The IBAN follows the format
CR+ 20 digits (e.g.,CR75090100056938278310).- According to SINPE regulations, Virtual Accounts with no movement for over 90 days must be inactivated. In practice, inactivation runs automatically on the first Tuesday of each month at 00:00 CR time.
| Property | SPEI | TEF | SPID |
|---|---|---|---|
| SLA Payment Confirmation | Real Time 24/7 | T+1 cut off 5PM (UTC-6) | Real Time 24/7 |
| Processing Currency | MXN (Mexican Peso) | MXN (Mexican Peso) | USD (US Dollar) |
| Minimum Transaction Amount | MXN 1.00 | MXN 1.00 | USD 1.00 |
| Maximum Transaction Amount | MXN 1,000,000,000.00 | MXN 1,000,000,000.00 | USD 10,000,000.00 |
| Local Account Format | 18-digit CLABE (Clave Bancaria Estandarizada) | 18-digit CLABE (Clave Bancaria Estandarizada) | 18-digit CLABE (Clave Bancaria Estandarizada) |
| Clearinghouse | Banco de Mexico | CECOBAN | Banco de Mexico |
| Maximum Virtual Accounts | Unlimited | Unlimited | Please contact your Account Manager |
| Payer Type | Individual and Company | Individual and Company | Company |
| Virtual Account Creation Model | Online, Offline | Online, Offline | Online,Offline |
Mexico SPID
To request a virtual account for USD transfers via Mexico's SPID system, please note:
- Available Banks: Consult the list of supported banks and codes for transfers.
- Localpayment Account:You must have a USD Localpayment account to receive funds. If you don't have one, please contact our Support Team to have it set up before proceeding.
Account Format
In Mexico, virtual accounts must use the standardized CLABE (Clave Bancaria Estandarizada) number.
Structure:
- Positions 1-3: Bank Code (assigned by Banco de México)
- Positions 4-6: Branch/Office Code (geographic location)
- Positions 7-17: Customer Account Number
- Position 18: Control Digit (checksum)
In Mexico, local bank transfers in Mexican Pesos (MXN) are conducted through two main clearing systems:
-
SPEI (Sistema de Pagos Electrónicos Interbancarios): a real-time interbank payment system operated by Banco de México, enabling fund transfers between banks within seconds. Transactions typically settle instantly, and accounts must be identified using the standardized CLABE number.
-
TEF (Transferencia Electrónica de Fondos): a payment method in Mexico operated by CECOBAN used for interbank transfers, where transactions are processed on the next business day. It requires the standardized CLABE account number for identification, is only available on business days according to the Mexican banking schedule, and is commonly used for payments that are not time-sensitive, such as scheduled supplier disbursements or recurring transfers where immediate settlement is not required.
For U.S. Dollar (USD) transfers between Mexican bank accounts, we provide access to SPID.
- SPID (Sistema de Pagos Interbancarios en Dolares): is the specialized Mexican payment system for domestic, interbank transfers in U.S. Dollars. It enables companies based in Mexico to move USD funds efficiently between accounts held at different banks within the country.
How SPID Works:
-
Processing Schedule: Available on Mexican banking business days, between 8:00 AM and 5:00 PM (UTC -6). Transactions are processed in batches throughout the day.
-
Account Requirement: Transactions are processed using the standardized CLABE number for the recipient's USD account.
-
Typical Applications: Best suited for B2B payments, international supplier settlements, and other corporate treasury operations where funds must remain in USD.
| Property | CCI-In | CCI-In USD |
|---|---|---|
| SLA Payment Confirmation | Real Time 24/7 | Real Time 24/7 |
| Processing Currency | PEN (Peruvian Sol) | USD (US Dollar) |
| Minimum Transaction Amount | PEN 1.00 | USD 1.00 |
| Maximum Transaction Amount | PEN 30,000.00 | USD 10,000.00 |
| Local Account Format | Codigo de Cuenta Interbancario (CCI) | Codigo de Cuenta Interbancario (CCI) |
| Clearinghouse | CCE | CCE |
| Maximum Virtual Accounts | Unlimited | Unlimited |
| Virtual Account Creation Model | Online | Online |
Important:
The currency (PEN or USD) of your virtual account is determined by the configuration of your Localpayment account.
If you require payins to your virtual account exceeding 30,000 PEN, you must contact our support team.
Account Format
In Peru, virtual accounts use the CCI (Código de Cuenta Interbancario) format, which is a standardized 20-digit interbank account code.
Structure:
- Positions 1-3: 3 digits - Bank code (assigned by SBS - Superintendencia de Banca, Seguros y AFP)
- Positions 4-6: 3 digits - Branch number
- Positions 7-18: 12 digits - Unique account number within the bank
- Position 19-20: 2 digit - Control digits (checksum validator)
Example: 92250610000000101419
Step 1: Create a Virtual Account
Option 1: Individual Virtual Account Creation
Create single virtual accounts with detailed configuration for specific customers or transactions.
To create a virtual account, you'll need to send a POST request to the Create a Virtual Account endpoint.
Key Request Parameters
The request requires several key parameters:
| Parameter | Description | Required |
|---|---|---|
| externalId | Unique identifier assigned by the merchant to reference the virtual account. | ✅ |
| accountNumber | Merchant's account number to which the virtual account will be linked or associated. | ✅ |
| country | Country where the virtual account will be provisioned. | ✅ |
| beneficiary | Object containing the beneficiary's personal information (beneficiary type, name, document, address, website). | ✅ |
Example Request
Below is an example using curl:
curl --request POST \
--url https://api.stage.localpayment.com/api/virtual-account \
--header 'Authorization: Bearer <your_access_token>' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"country": "ARG",
"beneficiary": {
"type": "COMPANY",
"document": {
"id": "30-71234567-9",
"type": "CUIT"
},
"name": "ACME INTERNATIONAL LTD",
"lastName": "",
"fullName": "ACME INTERNATIONAL LTD",
"address": {
"street": "Av. Corrientes",
"number": "1234",
"city": "Buenos Aires",
"state": "CABA",
"country": "Argentina"
},
"website": "https://yongxin.technology.com"
},
"externalId": "de14bcf2-15ee-22e3-ab59-99c3fcba31e8",
"accountNumber": "{{accountNumber}}"
}
'See all available parameters in the request.
Successful Response
A successful request will result in the API returning a status code of 100, with the account status initially set to INPROGRESS. The virtual account will remain in this state during activation and will transition to one of the available statuses once the activation process completes.
{
"externalId": "de14bcf2-15ee-22e3-ab59-99c3fcba31e8",
"internalId": "5ba31ea0-669b-43f6-88a1-1601f3cade0a",
"accountNumber": "{{accountNumber}}",
"country": "ARG",
"currency": "ARS",
"beneficiary": {
"type": "COMPANY",
"name": "ACME INTERNATIONAL LTD",
"fullName": "ACME INTERNATIONAL LTD",
"lastName": "",
"document": {
"type": "CUIT",
"id": "30-71234567-9"
},
"address": {
"street": "Av. Corrientes",
"number": "1234",
"city": "Buenos Aires",
"state": "CABA",
"country": "Argentina"
}
},
"status": {
"code": "100",
"description": "INPROGRESS",
"detail": "Virtual account in progress"
},
"errors": []
}Key Response Fields
| Field | Description |
|---|---|
externalId | A unique identifier for the transaction in your system. It will be used to perform other operations such as obtaining virtual account status. |
internalId | A unique identifier for the transaction in Localpayment's system. |
status | Object with information about the status of the virtual account. |
status.code | The status code (e.g., 100 for INPROGRESS). |
date.processedDate | When transaction began processing. |
Error Response
When a request fails, you'll receive detailed error information:
{
"externalId": "f5c4529e-67c1-43e0-bc2a-97250e736c98",
"internalId": "f2d9d9b0-093d-469b-c8d6-728b0cc67e80",
"status": {
"code": "300",
"description": "REJECTED",
"detail": "Invalid param + [document.id] + verification failed"
},
"errors": [
{
"code": "300",
"detail": "Invalid param + [document.id] + verification failed"
}
]
}Account Activation Time
The activation time for virtual accounts varies by country. Below are the estimated times for accounts to become active and ready to receive payments:
- Argentina: Up to 6 seconds
- Brazil: Up to 15 minutes
- Colombia: Up to 6 seconds
- Mexico: Up to 6 seconds
- Peru: Up to 6 seconds
Option 2: Create Virtual Accounts in Batch
Generate multiple virtual accounts in a single API request for efficient bulk operations. To create virtual accounts in bulk, you'll need to send a POST request to the Create Virtual Accounts in Batch endpoint.
Only accounts within the same country can be created in a single batch request.
Key Request Parameters
The request requires several key parameters:
| Parameter | Description | Required |
|---|---|---|
| externalId | Unique identifier assigned by the merchant to reference the virtual account. | ✅ |
| accountNumber | Merchant's account number to which the virtual account will be linked or associated. | ✅ |
| country | Country where the virtual account will be provisioned. | ✅ |
| beneficiary | Object containing the beneficiary's personal information. | ✅ |
| accounts | Array containing the individual sub-accounts and their respective beneficiaries associated with the virtual account. |
Example Request
Below is an example using curl:
curl --request POST \
--url https://api.stage.localpayment.com/api/virtual-account-batch \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer <your_access_token>' \
--data '
{
"externalId": "f059a032-9253-4607-9b8e-2948ed18d595",
"accountNumber": "{{accountNumber}}",
"country": "MEX",
"name": "Virtual Account",
"accounts": [
{
"externalId": "9210b519-5c29-4419-8d28-04f7543a914f",
"beneficiary": {
"type": "INDIVIDUAL",
"name": "John",
"lastname": "Doe",
"document": {
"id": "EXTF900101NI1",
"type": "RFC"
}
}
},
{
"externalId": "e4914217-41bc-49a5-b2f8-df950bf9bae7",
"beneficiary": {
"type": "INDIVIDUAL",
"name": "Alicia",
"lastname": "Doe",
"document": {
"id": "EXTF900101NI2",
"type": "RFC"
}
}
}
]
}
'
'See all available parameters in the request.
Successful Response
A successful request will result in the API returning a status code of 100, with the account status set to INPROGRESS.
{
"externalId": "f059a032-9253-4607-9b8e-2948ed18d595",
"internalId": "1748f8f8-dcac-4547-b3fb-7d6529245d84",
"accountNumber": "{{accountNumber}}",
"status": {
"code": "100",
"description": "INPROGRESS",
"detail": "Batch Process Virtual Account in progress"
},
"comment": "For obtaining the asynchronous response, kindly submit a request to the service after a brief interval. GET {api_environment_url}/api/virtual-account-batch/7facbbbf-d279-4ab5-9aeb-7583fa3f35ec"
}Key Response Fields
| Field | Description |
|---|---|
externalId | A unique identifier for the transaction in your system. It will be used to perform other operations such as obtaining virtual account status. |
internalId | A unique identifier for the transaction in Localpayment's system. |
status | Object with information about the status of the virtual account. |
status.code | The status code (e.g., 100 for INPROGRESS). |
date.processedDate | When transaction began processing. |
Error Response
When a request fails, you'll receive detailed error information:
{
"timestamp": "2025-01-03T22:03:39.657+00:00",
"status": 400,
"error": "Bad Request.",
"message": "External ID already used - Duplication",
"path": "/virtual-account/batch"
}For a complete list of status codes and their meanings, please refer to the Transaction Status documentation.
Step 2. Track Virtual Account Status
Monitoring your virtual accounts' status is essential for maintaining optimal payment operations. Localpayment provides comprehensive tracking capabilities for both individual and batch-created accounts through consistent API endpoints and real-time status updates.
To check the status of an individual virtual account, you'll need to send a GET request to the Get Virtual Account Status endpoint.
To monitor the processing status of batch-created virtual accounts, you'll need to send a GET request to the Get Virtual Account Status (Batch) endpoint.
Next Steps
Monitor the lifecycle of your virtual accounts to maintain optimal payment operations. Learn about the different status types and understand what each one means for your payment processing capabilities.
Provide payers with the correct beneficiary details returned in the Get Virtual Account Status API response to process payments correctly. View country-specific instructions to ensure accurate and compliant payment execution.
Manage account availability by temporarily activating or deactivating virtual accounts. This is useful for seasonal businesses, account maintenance, or temporary suspensions.
Permanently deactivate a virtual account. This prevents all future payments to it but retains its full history. The action is irreversible. Use for accounts no longer needed; create a new one to resume operations.
Updated about 1 month ago
