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.

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.

{
  "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