Guides
FAQs
  1. Virtual accounts (BETA)

Cuentas virtuales

Descubre cómo realizar transacciones de forma segura con cuentas virtuales

1. ¿Cómo funciona?

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.

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.

1.2. 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.

PaísCódigo del país (ISO 3166-1 alpha-2)Código de moneda (ISO 4217)
ChileCLCLP
PerúPEPEN / USD

2. 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 (username y password).

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

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

{
  "password": "4h123jl00",
  "username": "virtualaccountspp"
}
👍

Respuesta

Al autenticarte correctamente con tus credenciales, recibirás un accessToken que te permite usar las APIs de cuentas virtuales, un refreshToken para renovar tu accessToken, un expiresIn que indica la duración del token en segundos y un tokenType que indica el tipo de token.


2.1. Renueva un access token

Este endpoint te permite renovar un access token utilizando el refreshToken recibido en la respuesta de tu solicitud de inicio de sesión.

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

{
  "refreshToken": "1234uj00"
}

3. 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",
      "comment": "reference",
      "country": "peru",
      "number": "12",
      "state": "lima",
      "street": "example st",
      "zipCode": "12345"
    },
    "document": {
      "type": "dni",
      "id": "12345678"
    },
    "legalRepresentative": {
      "document": {
        "type": "ruc"
      }
    },
    "industry": "gambling",
    "lastname": "Doe",
    "name": "Jane",
    "website": "www.website.com"
  },
  "type": "recurrent",
  "accountNumber": "1234567890",
  "referenceId": "123456789"
}

3.1. 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 esta respuesta similar a esta:

{
  "message": "string"
}

3.2. Detalles de una cuenta virtual

Para consultar los detalles de una cuenta virtual creada utilizando nuestro endpoint, visita esta página.

3.2.1. 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"
}

3.3. 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.

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

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

3.3.1. Respuesta

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

{
  "status": "disabled",
  "updatedAt": "2026-04-17T15:47:20.714Z",
  "virtualAccountId": "12345688765432"
}

4. 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.

{
  "virtualAccounts": [
    {
      "accountNumber": "1234567890",
      "beneficiary": {
        "type": "individual",
        "address": {
          "city": "lima",
          "comment": "blue house",
          "country": "peru",
          "number": "12",
          "state": "lima",
          "street": "example st",
          "zipCode": "12345"
        },
        "document": {
          "id": "879018341",
          "type": "dni"
        },
        "industry": "gambling",
        "lastname": "Doe",
        "name": "Jane",
        "website": "www.website.com"
      },
      "referenceId": "123456888"
    }
  ]
}

4.1. 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": 0,
  "virtualAccountBatchId": "98210492a01"
}

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

{
  "message": "string"
}

4.2. 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.

4.2.1. 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"
    }
  ],
  "status": "received",
  "successRecords": 0,
  "totalRecords": 0,
  "updatedAt": "2026-04-17T15:47:20.714Z",
  "virtualAccountBatchId": "98210492a01"
}

5. Reembolsa un pago recibido en una cuenta virtual

Para crear una solicitud de reembolso de un pago recibido en una cuenta virtual, realiza la solicitud a este endpoint.

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

{
  "amount": 100,
  "comment": "refund",
  "referenceId": "1203pas012",
  "transactionId": "3fa85f74-5717-4562-b3fc-2c963f66afr0"
}

5.1. Respuesta

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

{
  "refundId": "12345678901",
  "status": "received",
  "transactionId": "3fa85f74-5717-4562-b3fc-2c963f66afr0"
}

5.2. Detalles de un reembolso

Consulta el detalle de un reembolso, usando el identificador de la solicitud de reembolso refundId. Utiliza este endpoint para conocer el detalle.

5.2.1. Respuesta

A continuación se muestran los detalles de un reembolso:

{
  "amount": 100,
  "comment": "refund",
  "createdAt": "2026-04-17T05:47:25.028Z",
  "referenceId": "12345678901",
  "refundId": "12300009812",
  "status": "received",
  "transactionId": "3fa85f74-5717-4562-b3fc-2c963f66afr0",
  "type": "partial",
  "updatedAt": "2026-04-17T05:47:25.028Z"
}

📘

Webhooks

Conoce los webhooks para reembolsos en esta guía.


6. Genera un wire out

A través de nuestro endpoint para wire out, podrás solicitar una transferencia internacional en USD desde tu cuenta interna hacia un beneficiario previamente registrado en ProntoPaga.

Al enviar la solicitud con los datos requeridos, recibirás inmediatamente un identificador único del wire out y un estado inicial de procesamiento, lo que te permite iniciar la remesa de fondos de manera segura y realizar el seguimiento de su resultado final.

Esta operación garantiza trazabilidad de la solicitud y confirma que la instrucción ha sido aceptada para su procesamiento, sin implicar que la transferencia ya se haya ejecutado.

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

{
  "amount": 1000,
  "currency": "USD",
  "payerAccountId": "acc_usd_PP_099",
  "referenceId": "PP123456789",
  "referenceNote": "PP123456789",
  "settlementAccountId": "0912483721",
  "wireOutId": "fe0f96ff-95d4-4c18-97e3-99f72b8c7b20"
}

6.1. Respuesta

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

{
  "amount": 1000,
  "currency": "USD",
  "payerAccountId": "acc_usd_PP_099",
  "processingStatus": "processing",
  "referenceId": "PP123456789",
  "settlementAccountId": "0912483721",
  "wireOutId": "fe0f96ff-95d4-4c18-97e3-99f72b8c7b20"
}
📘

Webhooks

Conoce los webhooks para wire outs en esta guía.

6.2. Detalles de un wire out

Este endpoint te permite consultar el detalle de un wire out específico que ya fue solicitado previamente mediante nuestro endpoint de generación de un wire out.

6.2.1. Respuesta

A continuación se muestra la respuesta que recibirás con los detalles del wire out solicitado.

{
  "amount": 1000,
  "completedAt": "2026-04-17T05:47:25.028Z",
  "currency": "USD",
  "payerAccountId": "acc_usd_PP_099",
  "processingStatus": "processing",
  "referenceId": "PP123456789",
  "settlementAccountId": "0912483721",
  "statusMessage": "processing",
  "updatedAt": "2026-04-17T05:47:25.028Z",
  "wireOutId": "fe0f96ff-95d4-4c18-97e3-99f72b8c7b20"
}

Updated 1 day ago