Create a Virtual Account

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.

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:

ℹ️

Notes:

• Account Owner refers to the legal account holder name registered in the banking system (the name visible at the bank level).
• Bank Transfer Display Name: refers to the payer-facing name shown during an electronic fund transfer to the virtual account.

💡

For Argentina, Brazil, and Chile: If your beneficiary is a foreign resident (non-local), the virtual account must be registered under Localpayment as the account holder. This ensures compliance with local banking regulations while still allowing you to receive payments on behalf of foreign entities.

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.

Optional Information:

• Beneficiary Document: Official identification information to verify identity. Required for Virtual Accounts in Peru.
• 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:

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:

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": "MEX",
  "beneficiary": {
    "type": "INDIVIDUAL",
    "document": {
      "id": "EXTF900101NI1",
      "type": "RFC"
    },
    "name": "John",
    "lastName": "Doe"
  },
  "externalId": "de14bcf2-15ee-22e3-ab59-99c3fcba31e8",
  "accountNumber": "484.484.00000011"
}
'

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.

Important country exception: For Argentina, Peru and Mexico (TEF), the activation is instantaneous. The API response will directly return a final status (e.g., COMPLETED) instead of the intermediate INPROGRESS state.

{
  "currency": "MXN",
  "externalId": "de14bcf2-15ee-22e3-ab59-99c3fcba31e8",
  "internalId": "0a8bc036-98bc-417e-984a-3ff8dd227d22",
  "accountNumber": "484.484.00000011",
  "beneficiary": {
    "type": "INDIVIDUAL",
    "name": "John",
    "document": {
      "type": "RFC",
      "id": "EXTF900101NI1"
    },
    "fullName": "John Doe",
    "lastName": "Doe"
  },
  "status": {
    "code": "100",
    "description": "INPROGRESS",
    "detail": "Virtual account in progress"
  },
  "errors": []
}

Key Response Fields

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
• 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:

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": "de14bcf2-45ee-22e3-ab59-99c3fcba31e8",
  "accountNumber": "484.484.00000011",
  "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": "7facbc4f-4c79-4a15-caeb-75833a3f35ec",
  "internalId": "1748f8f8-dcac-4547-b3fb-7d6529245d84",
  "accountNumber": "484.484.00000011",
  "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

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.

Next Steps