Cuentas virtuales

Las cuentas virtuales son números de cuenta generados automáticamente que facilitan el procesamiento de pagos de manera segura y organizada entre empresas y clientes. Actúan como intermediarios en las transacciones financieras, asignándose a clientes o transacciones específicas según las necesidades del negocio.

Estas cuentas pueden configurarse para uso único o para relaciones de pago recurrentes, lo que proporciona flexibilidad según el tipo de operación.

¿Cómo funciona?

El proceso de uso de cuentas virtuales a través de ProntoPaga consta de las siguientes etapas:

1. Creación de una cuenta virtual. El comercio inicia el proceso de creación de cuentas virtuales a través de la API de ProntoPaga.
2. Generación de una cuenta virtual. ProntoPaga genera automáticamente una cuenta virtual única y envía los datos de la cuenta al comercio a través de nuestra API.
3. Asignación de cuenta virtual. El comercio asigna la cuenta virtual al subcomercio, lo que permite una atribución y conciliación precisas de los pagos por su parte.
4. Instrucciones de pago. El subcomercio envía las instrucciones de pago al pagador, proporcionándole los datos necesarios para completar la transacción en la cuenta virtual asignada.
5. Pago a una cuenta virtual. El pagador inicia un pago a la cuenta virtual recibida. Esta transacción se procesa como una transferencia bancaria normal desde la app/web de su banco.
6. Confirmación de pago al comercio. ProntoPaga envía una confirmación de pago al comercio con los datos clave de la transacción para la gestión financiera y la conciliación.
7. Confirmación de pago al subcomercio/beneficiario. El comercio envía la confirmación de pago al subcomercio/beneficiario, con lo que se cierra el ciclo de la transacción.

Países y monedas

Los códigos de país están en formato ISO 3166-1 Alpha-2. Las monedas están en formato ISO 4217.

Genera un access token

Para conectarte de forma segura con las APIs de ProntoPaga y gestionar tus cuentas virtuales en el producto Cuentas Virtuales, debes generar un access token utilizando tus credenciales (clientId y clientSecret).

Ten en cuenta que estas credenciales se te proporcionarán durante el onboarding por el equipo de ProntoPaga. Consulta el endpoint para generar tu access token.

A continuación, puedes ver un ejemplo del body de la solicitud.

{
  "clientId": "4h123jl00",
  "clientSecret": "virtualaccountspp"
}

👍

Respuesta

Al autenticarte correctamente con tus credenciales, recibirás un accessToken para autenticar las solicitudes a la API de cuentas virtuales, un expiresIn que indica el tiempo de expiración del token en segundos y un tokenType que especifica el esquema de autenticación utilizado (Bearer).

Códigos de respuesta

A continuación, puedes ver los distintos códigos de respuesta que podrías recibir durante la generación del access token.

Crea una cuenta virtual

Para solicitar la creación de una cuenta virtual a través de nuestra API, deberás usar este endpoint.

📘

Datos del beneficiario

Ten en cuenta que debes recopilar los siguientes datos del subcomercio/beneficiario: nombre, apellido, dirección completa, país, número de identificación, entre otros.

A continuación, puedes ver un ejemplo del body request:

{
  "beneficiary": {
    "type": "individual",
    "address": {
      "city": "Lima",
      "country": "Peru",
      "number": "12",
      "state": "Departamento de Lima",
      "street": "Test St",
      "zipCode": "01234"
    },
    "document": {
      "type": "dni",
      "id": "987654321"
    },
    "legalRepresentative": {
      "document": {
        "type": "ruc",
        "id": "1234567001"
      },
      "name": "Jane Doe"
    },
    "industry": "gambling",
    "lastname": "Doe",
    "name": "John",
    "website": "www.website.com"
  },
  "type": "recurrent",
  "accountNumber": "1234567890",
  "referenceId": "9238271J134"
}

Respuestas

Como respuesta a una solicitud de creación de cuenta virtual exitosa, recibirás el número de la cuenta virtual creada en el parámetro vaNumber, junto con el estado y el tipo de cuenta, así como el virtualAccountId, que te permite identificar el número de cuenta asociado al subcomercio o al beneficiario.

Si la transacción es exitosa, recibirás la siguiente respuesta:

{
  "accountNumber": "1234567890",
  "channel": "api",
  "currency": "PEN",
  "referenceId": "9238271J134",
  "status": "enabled",
  "type": "recurrent",
  "vaNumber": "12345678902",
  "virtualAccountId": "98124568532"
}

Si la transacción es rechazada, recibirás una respuesta similar a esta:

{
  "message": "string"
}

Códigos de respuesta

A continuación, puedes ver los distintos códigos de respuesta que podrías recibir durante la creación de una cuenta virtual.

Detalles de una cuenta virtual

Puedes consultar los detalles de una cuenta virtual creada mediante nuestro endpoint.

Respuesta

A continuación se muestra la respuesta que recibirás con los detalles de la cuenta virtual.

{
  "accountNumber": "1234567890",
  "bankCode": "001",
  "bankName": "BCP",
  "beneficiary": {
    "type": "individual"
  },
  "country": "Peru",
  "currency": "PEN",
  "referenceId": "3fa85f74-5717-4562-b3fc-2c963f66afr0",
  "status": "enabled",
  "type": "recurrent",
  "vaNumber": "1234567890",
  "virtualAccountId": "98124568532"
}

Códigos de respuesta

A continuación, puedes ver los distintos códigos de respuesta que podrías recibir durante la consulta de detalles de una cuenta virtual.

Detalles de una cuenta virtual por referenceId

Puedes consultar los detalles de una cuenta virtual por su referenceId mediante nuestro endpoint.

Respuesta

A continuación se muestra la respuesta que recibirás con los detalles de la cuenta virtual.

{
  "accountNumber": "1234567890",
  "bankCode": "001",
  "bankName": "BCP",
  "beneficiary": {
    "type": "individual"
  },
  "country": "Peru",
  "currency": "PEN",
  "referenceId": "3fa85f74-5717-4562-b3fc-2c963f66afr0",
  "status": "enabled",
  "type": "recurrent",
  "vaNumber": "1234567890",
  "virtualAccountId": "98124568532"
}

Códigos de respuesta

A continuación, puedes ver los distintos códigos de respuesta que podrías recibir durante la consulta de detalles por referenceId de una cuenta virtual.

Modifica el estado de una cuenta virtual

Este endpoint te permite habilitar o deshabilitar una cuenta virtual, controlando si puede recibir fondos o realizar operaciones.

📘

Parámetro virtualAccountId

Ten en cuenta que el número de la cuenta virtual debe enviarse como parte del path del endpoint.

A continuación, puedes ver un ejemplo del body de la solicitud:

{
  "status": "disabled",
  "reason": "no longer used"
}

Respuesta

Si tu solicitud se realiza correctamente, recibirás una respuesta similar a la que se muestra a continuación:

{
  "referenceId": "140009238291",
  "status": "disabled",
  "updatedAt": "2026-06-19T19:51:26.164Z",
  "virtualAccountId": "12345678901"
}

Códigos de respuesta

A continuación, puedes ver los distintos códigos de respuesta que podrías recibir durante la modificación del estado de una cuenta virtual.

Crea cuentas virtuales en batch

Para solicitar la creación de cuentas virtuales en batch a través de nuestra API, deberás usar este endpoint.

📘

Datos del beneficiario

Ten en cuenta que debes recopilar los siguientes datos del subcomercio/beneficiario: nombre, apellido, dirección completa, país, número de identificación, entre otros.

A continuación, puedes ver un ejemplo del body request:

{
  "referenceId": "123456789000",
  "virtualAccounts": [
    {
      "beneficiary": {
        "type": "individual",
        "address": {
          "city": "Lima",
          "country": "Peru",
          "number": "12",
          "state": "Departamento de Lima",
          "street": "Test St",
          "zipCode": "045667"
        },
        "document": {
          "type": "ruc",
          "id": "4857392012"
        },
        "legalRepresentative": {
          "document": {
            "type": "ruc"
          },
          "name": "Jane"
        },
        "industry": "gambling",
        "lastname": "Doe",
        "name": "John",
        "website": "www.website.com"
      },
      "type": "recurrent",
      "accountNumber": "0490183718111",
      "referenceId": "019384822"
    },
    {
      "beneficiary": {
        "type": "individual",
        "document": {
          "type": "ruc"
        },
        "legalRepresentative": {
          "document": {
            "type": "ruc"
          }
        }
      },
      "type": "recurrent",
      "accountNumber": "12345567789",
      "referenceId": "123345678900"
    }
  ]
}

Respuestas

Como respuesta a una solicitud de creación de cuentas virtuales en batch exitosa, recibirás el virtualAccountBatchId, que te permitirá tener un número de referencia del batch realizado.

Si la transacción es exitosa, recibirás la siguiente respuesta:

{
  "createdAt": "2026-04-17T15:47:20.714Z",
  "status": "received",
  "totalRecords": 2,
  "virtualAccountBatchId": "98210492A01"
}

Si la transacción es rechazada, recibirás una respuesta similar a esta:

{
  "message": "Unauthorized"
}

Códigos de respuesta

A continuación, puedes ver los distintos códigos de respuesta que podrías recibir durante la creación de cuentas virtuales en batch.

Estado de creación de cuentas virtuales en batch

Para conocer el estado de la creación de cuentas virtuales en batch a través de nuestra API, deberás usar este endpoint.

Respuesta

A continuación se muestra la respuesta que recibirás con el estado de la creación de cuentas virtuales en batch:

{
  "createdAt": "2026-04-17T15:47:20.714Z",
  "failedRecords": 0,
  "processedRecords": 0,
  "referenceId": "123456888",
  "results": [
    {
      "currency": "PEN",
      "error": {
        "code": 0,
        "description": "error"
      },
      "referenceId": "123456888",
      "status": "success",
      "vaNumber": "1234567890",
      "virtualAccountId": "4283245780987654"
    }
  ],
  "status": "received",
  "successRecords": 2,
  "totalRecords": 2,
  "updatedAt": "2026-04-17T15:47:20.714Z",
  "virtualAccountBatchId": "98210492A01"
}

Códigos de respuesta

A continuación, puedes ver los distintos códigos de respuesta que podrías recibir durante la consulta de estado de creación de cuentas virtuales en batch.