HomeGuidesRecipesAPI Reference
Guides
Sign in
Start typing to search…

Virtual Accounts

Virtual accounts are digital accounts created within the Localpayment platform. They provide a unique and dedicated account number for each customer or transaction, simplifying the process of receiving and reconciling payments.

The workflow for using virtual accounts involves:

  1. Requesting the creation of a virtual account through the API.
  2. Providing the generated virtual account details to the customer for initiating bank transfers.
  3. Receiving webhook notifications from Localpayment with updates on the transfer status.

You can request the creation of virtual accounts individually or in batch.

How it Works

The process of using virtual accounts through Localpayment involves the following steps:

  1. Create Virtual Accounts: The merchant initiates the process by creating virtual accounts through Localpayment's platform. Each virtual account is uniquely generated to facilitate individual tracking.​
  2. Virtual Account Creation: Localpayment automatically generates a unique virtual account and sends the account details.
  3. Assign to Customers: Each virtual account is assigned to a specific customer, ensuring that incoming payments can be accurately attributed to the correct source.​
  4. Customer Initiates ACH Transfer: Customers perform local ACH bank transfers, directing funds to their assigned virtual account numbers. This method ensures that payments are routed correctly without the need for additional identifiers.​
  5. Real-Time Reconciliation: Upon receipt, payments are automatically reconciled in real-time. Localpayment's system performs automatic matching of incoming funds to the designated virtual accounts, with immediate updates to transaction records.
  6. Notification: Merchants receive instant notifications for successful payments. These alerts confirm transactions and provide key details for efficient financial management.

Availability

Virtual account processing is available in the following countries:

  • 🇦🇷 Argentina
  • 🇧🇷 Brazil
  • 🇲🇽 Mexico

Before Creating a Virtual Account

Before submitting a request to create a virtual account, ensure you have completed the following:

  1. Generate an Access Token (Required): You'll need a valid access token to authenticate your API requests. Refer to the Generate an Access Token documentation for instructions.
  2. Validate Identity Document (Optional): You can optionally validate the customer's identity document information before processing the payment. This helps prevent transaction failures and ensures compliance with local regulations. Refer to the Validate Identity Document documentation for more information.
  3. Get National Holidays (Optional): You can optionally retrieve information about national holidays in the relevant country. This information can be useful for anticipating potential delays in bank processing. See the Get National Holidays documentation for more information.

Create a Virtual Account

When creating a virtual account, it is crucial to accurately gather and securely transmit all necessary beneficiary information. This includes:

  1. Beneficiary Information:
    • Name
    • Country-specific identification document
  2. Additional Requirements
    • Merchant reference ID

To create a virtual account, you'll need to send a POST request to the Create a Virtual Account endpoint.

Request Example

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",
    "lastName": "Doe"
  },
  "externalId": "de14bcf2-15ee-22e3-ab59-99c3fcba31e8",
  "accountNumber": "484.484.00000011"
}
'

Parameters

  • externalId: A unique identifier generated by your system to track the transaction (alphanumeric and hyphens). We recommend using UUID4 to ensure uniqueness (e.g. de14bcf2-15ee-22e3-ab59-99c3fcba31e8).
  • country: Set the country from which the operation is made. ISO 3166-1 alpha-3 (e.g. MEX).
  • accountNumber: The Localpayment account number where the specified amount will be credited.
  • beneficiary: Information about the virtual account beneficiary.
  • beneficiary.type: beneficiary type (e.g. COMPANY).
  • beneficiary.name: beneficiary name.
  • beneficiary.document: beneficiary documentation information.
  • beneficiary.document.type: The type of identity document, such as a National Identity Number, Social Security Number, or Driver's License, depending on the country of issuance.
  • beneficiary.document.id: Identity document number (usually a number). This must be a valid number according to the rules for the specific document type.

See all available parameters in the request.

Successful response example

A successful request will result in the API returning a status code of 100, with the account status set to INPROGRESS.

{
  "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 Fields in the Response

  • externalId: A unique identifier for the transaction in your system. It will be used to perform other operations such as obtaining transaction information.
  • internalId: A unique identifier for the transaction in Localpayment’s system.
  • status: Object with information about the status of the transaction.
  • status.code: The status code (e.g., 100 for INPROGRESS).

For a complete list of status codes and their meanings, please refer to the Transaction Status documentation.

Localpayment also sends webhooks to your application to notify you of changes in the virtual account status. For more information on webhooks, please refer to the Webhooks documentation.

Create Virtual Accounts in Batch

To create virtual accounts in bulk, you'll need to send a POST request to the Create Virtual Accounts in Batch endpoint.

Request Example

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",
  "externalId": "de14bcf2-15ee-22e3-ab59-99c3fcba31e8",
  "accountNumber": "484.484.00000011",
  "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": "John",
        "lastname": "Doe",
        "document": {
          "id": "EXTF900101NI2",
          "type": "RFC"
        }
      }
    }
  ]
}
'

Successful response example

{
  "externalId": "7facbc4f-4c79-4a15-caeb-75833a3f35ec",
  "internalId": "1748f8f8-dcac-4547-b3fb-7d6529245d84",
  "accountNumber": "{{YourAccountNumber}}",
  "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"
}

Retrieve Virtual Account Information

After a successful virtual account creation request, Localpayment automatically sends a webhook with the COMPLETED status once the account has been generated. You can also manually retrieve the status and details of a virtual account via the API.

To retrieve the details of a virtual account, send a GET request to the Get Virtual Account Status endpoint.

Request Example

Below is an example using curl:

curl --location \
--request GET 'https://api.stage.localpayment.com/api/virtual-account/{externalId}/' \
--header 'Authorization: Bearer <your_access_token>'

Successful response example

You will receive the virtual account details once its status changes from INPROGRESS to COMPLETED.

{
    "externalId": "de14bcf2-15ee-22e3-ab59-99c3fcba31e8",
    "internalId": "bbcada95-ee39-460f-8e57-b01ca17fa8b5",
    "accountNumber": "484.484.00000011",
    "country": "MEX",
    "currency": "MXN",
    "beneficiary": {
    "type": "INDIVIDUAL",
    "name": "John",
    "document": {
      "type": "RFC",
      "id": "EXTF900101NI1"
    },
    "bank": {
            "account": {
                "number": "646010319800000073"
            }
        },
    "fullName": "John Doe",
    "lastName": "Doe"
  },
    "status": {
        "code": "200",
        "description": "COMPLETED",
        "detail": "Virtual account has been created"
    },
    "errors": []
}

Key Fields in the Response

  • externalId: A unique identifier for the transaction in your system. It will be used to perform other operations such as obtaining transaction information.
  • internalId: A unique identifier for the transaction in Localpayment’s system.
  • status: Object with information about the status of the transaction.
  • status.code: The status code (e.g., 100 for INPROGRESS).
  • beneficiary: Information about the virtual account beneficiary.
  • beneficiary.bank.account.number: Virtual Account Number.

For a complete list of status codes and their meanings, please refer to the Transaction Status documentation.


Virtual Account Lookup: Non existent account Response

When a virtual account is queried using an externalId that does not exist in the system, the API returns an HTTP 404 response indicating that no matching record was found.

What Does It Mean?

A "non-existent virtual account" refers to a situation where the externalId provided in the
request does not match any record in the virtual accounts database. This typically happens when:

  • The account has not been created or registered yet.
  • There was a typo or formatting issue in the externalId.
  • The account was deleted.

Request Example

curl --location
'http://micro-payin-core.stage.localpayment.internal:8080/virtual-account/
1744231671-nico' \
--header 'x-client-code: 0001'

Response example

{
"timestamp": "2025-06-04T15:28:39.691+00:00",
"status": 404,
"error": "Not Found",
"message": "Virtual account not found with externalId: 1744231671-nico",
"path": "/virtual-account/1744231671-nico"
}

📘

Info

When the provided externalId does not match any existing virtual account, the service returns:

  • HTTP Status Code: 404 Not Found.
  • Message: "Virtual account not found with externalId: externalId".

Enable/Disable Virtual Account

You can enable or disable a virtual account to control the receipt of payments. When a virtual account is disabled, any incoming payments will be rejected.

ℹ️

Note

This functionality is currently supported only in Mexico.

To enable or disable a virtual account, send a PUT request to the Update Virtual Account Status endpoint.

Request Example

Below is an example using curl:

curl --location \
--request PUT 'https://api.stage.localpayment.com/api/virtual-account/{externalId}/activation/{status}' \
--header 'Authorization: Bearer  <your_access_token>'

Successful response example

The API will return the updated status of the virtual account.

{
    "currency": "MXN",
    "externalId": "de14bcf2-15ee-22e3-ab59-99c3fcba31e8",
    "internalId": "bbcada95-ee39-460f-8e57-b01ca17fa8b5",
    "accountNumber": "484.484.00000011",
    "beneficiary": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "RFC",
            "id": "EXTF900101NI1"
        },
        "bank": {
            "account": {
                "number": "646010319800000073"
            }
        },
        "fullName": "John Doe"
    },
    "status": {
        "code": "300",
        "description": "DISABLED",
        "detail": "Virtual account disabled"
    },
    "errors": []
}

Delete Virtual Account

You can delete a virtual account using the API.

To delete a virtual account, you'll need to send a DELETE request to theDelete a Virtual Account endpoint.

Request Example

Below is an example using curl:

curl --location \
--request DELETE 'https://api.stage.localpayment.com/api/virtual-account/{externalId}/' \
--header 'Authorization: Bearer <your_access_token>'

Successful response example

The API will return the status of the deleted virtual account.

{
    "externalId": "de14bcf2-15ee-22e3-ab59-99c3fcba31e8",
    "internalId": "bbcada95-ee39-460f-8e57-b01ca17fa8b5",
    "accountNumber": "484.484.00000011",
    "country": "MEX",
    "currency": "MXN",
    "beneficiary": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "RFC",
            "id": "EXTF900101NI1"
        },
        "bank": {
            "account": {
                "number": "646010319800000073"
            }
        }
    },
    "status": {
        "code": "908",
        "description": "DELETED",
        "detail": "Virtual account has been deleted"
    },
    "errors": []
}

Create an Alias for your Virtual Account

⚠️

Important

This functionality is exclusive to Brazil.

You can generate an alias to a virtual account using the API. Follow the next steps:

Step 1

To create an alias for a virtual account, you'll need to send a POST request to theCreate an Alias to a Virtual Account endpoint.

Request Example

Below is an example using curl:

curl --request POST \
     --url https://api.stage.localpayment.com/api/virtual-account/ExternalIdVirtualAccount/alias/resendcode/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "type": "E",
  "value": "[email protected]"
}'

Successful response example

The API will return the status of the alias for your virtual account.

{
  "externalId": "716aa0-2d2d-4c556-8892-76",
  "alias": {
    "type": "E",
    "value": "[email protected]"
  },
  "status": {
    "code": "100",
    "description": "INPROGRESS",
    "detail": "Alias creation pending confirmation"
  }
}

📘

Info

If needed you can request a new validation token using the Resend Alias Token endpoint.

Step 2

After the request for the creation of an alias, you'll need to confirm by sending a POST request to the Confirm an Alias to a Virtual Account endpoint.

Request Example

Below is an example using curl:

curl --request POST \
     --url https://api.stage.localpayment.com/api/virtual-account/ExternalIdVirtualAccount/alias/confirm/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "type": "E",
  "value": "[email protected]",
  "confirmationCode": "285187"
}'

Successful response example

The API will return the status of the alias for your virtual account.

{
  "externalId": "716aa0-2d2d-4c556-8892-76",
  "alias": {
    "type": "E",
    "value": "[email protected]",
    "confirmationCode": "285187"
  },
  "status": {
    "code": "100",
    "description": "INPROGRESS",
    "detail": "Alias confirmed"
  }
}

📘

Info

You can delete an alias with the Cancel an Alias of a Virtual Account endpoint.


Next Steps

After a virtual account creation, you may need to perform additional actions, such as:

  • Refund the transaction: If necessary, you can refund the payment to the customer. Refer to the Refunds documentation for details.
  • Handle chargebacks: In case of a dispute, you may need to handle chargebacks. Refer to the Chargebacks documentation for information on this process.
  • Review transaction details: You can retrieve transaction information using the Localpayment API. See the Transaction Information documentation for details.

Updated 18 days ago