PayOuts

Con PayOuts de ProntoPaga puedes dispersar fondos hacia cuentas bancarias en Perú mediante una integración de API simple y segura. Envía transferencias a cuentas propias o de terceros, consulta el estado de cada operación en tiempo real y accede a la trazabilidad completa de tus transacciones para facilitar la conciliación y auditoría.

¿Qué puedes hacer?

¿Cómo funciona?

El proceso de un PayOut local en Perú sigue estas etapas, desde la solicitud hasta la confirmación de la transferencia.

1. Creación de la solicitud de PayOut. Tu sistema llama a la API de ProntoPaga indicando el beneficiario, la cuenta bancaria destino y el monto a dispersar. No se requiere ningún PayIn previo.
2. Registro y confirmación de recepción. Cuando se registra la solicitud, ProntoPaga asigna un identificador único.
3. Revisión y procesamiento interno. ProntoPaga revisa la solicitud y ejecuta la transferencia bancaria local. Durante este proceso, el PayOut puede quedar temporalmente en estado de on_hold si existe algún impedimento que requiera resolución.
4. Consultar el estado del PayOut. En cualquier momento puedes consultar el estado actualizado de tu PayOut usando su identificador. Esto te permite hacer el seguimiento de la transferencia.
5. Actualización al estado final. Una vez ejecutada la transferencia, el estado del PayOut se actualiza a su valor definitivo: completed si la operación fue exitosa, o failed si no pudo ejecutarse. Ambos son estados finales.

📘

Cuenta interna

Los fondos se dispersan desde el saldo disponible en tu cuenta registrada en ProntoPaga.

Monedas y límites

Las monedas disponibles para este producto están en formato ISO 4217.

• PEN
• CLP
• USD

Los montos permitidos por transacción son:

• Monto mínimo: 1
• Monto máximo: 100000000000

Genera un PayOut

Para conectarte de forma segura con las APIs de ProntoPaga y gestionar tus dispersiones, debes generar un access token utilizando tus credenciales (clientId y clientSecret). Estas credenciales se te proporcionarán durante el onboarding por ProntoPaga. Conoce el endpoint para generar tu access token.

Para solicitar una dispersión, envía un request a este endpoint indicando beneficiario, cuenta destino y monto.

{
  "amount": 100.90,
  "accountNumber": "1cb123e5-babd-67a8-915b-11471cf8b77",
  "comment": "PayOut cliente 1",
  "beneficiary": {
    "type": "company",
    "name": "ABC Company",
    "document": {
      "type": "ruc",
      "id": "123456"
    },
    "bankAccount": {
      "accountNumber": "1234567987",
      "bankName": "Example Bank",
      "currency": "PEN"
    }
  },
  "referenceId": "PayOut-001"
}

{
  "accountNumber": "1cb234e5-babd-67a8-985b-646471cf8b77",
  "amount": 100.90,
  "createdAt": "2026-06-18T14:30:45Z",
  "currency": "PEN",
  "payoutId": "1d23f45d-a678-4b9a-0bd9-9d34d01fff41",
  "referenceId": "23456787654345678",
  "status": "received"
}

{
  "message": "Internal account not found"
}

{
  "accountNumber": "0d10f23e-4567-891c-ab23-456e7041dfe8",
  "amount": 1000.90,
  "beneficiary": {
    "bankAccount": {
      "accountNumber": "123456789123456",
      "accountType": "savings",
      "bankName": "Example Bank",
      "currency": "PEN"
    },
    "document": {
      "id": "1234567891",
      "type": "ruc"
    },
    "name": "John",
    "lastName": "Doe",
    "type": "individual"
  },
  "comment": "Estimado equipo, solicito el procesamiento del payout correspondiente al balance disponible en mi cuenta. Agradezco de antemano su atención a esta solicitud",
  "createdAt": "2026-06-29T15:46:00.712Z",
  "currency": "PEN",
  "payoutId": "12345678-9220-4d6c-9cf0-4f5bcb1b4ffe",
  "referenceId": "12d3ce45-6fd7-8fbc-adb9-2561558d5f93",
  "status": "completed"
}

{
  "message": "Payout not found"
}

{
  "accountNumber": "0d10f23e-4567-891c-ab23-456e7041dfe8",
  "amount": 1000.90,
  "beneficiary": {
    "bankAccount": {
      "accountNumber": "123456789123456",
      "accountType": "savings",
      "bankName": "Example Bank",
      "currency": "PEN"
    },
    "document": {
      "id": "1234567891",
      "type": "ruc"
    },
    "name": "John",
    "lastName": "Doe",
    "type": "individual"
  },
  "comment": "Estimado equipo, solicito el procesamiento del payout correspondiente al balance disponible en mi cuenta. Agradezco de antemano su atención a esta solicitud",
  "createdAt": "2026-06-29T15:46:00.712Z",
  "currency": "PEN",
  "payoutId": "12345678-9220-4d6c-9cf0-4f5bcb1b4ffe",
  "referenceId": "12d3ce45-6fd7-8fbc-adb9-2561558d5f93",
  "status": "completed"
}

Estados

Las siguientes tablas muestran los estados de creación de un PayOut y los posibles estados derivados del endpoint de detalles de un PayOut.

Respuestas

A continuación te mostramos las posibles respuestas que pueden derivarse de un PayOut.

Respuestas de creación de un PayOut

La siguiente tabla contiene las respuestas comunes que pueden derivarse de la creación de un PayOut.

Respuestas de detalles de un PayOut

Esta tabla muestra las respuestas que pueden derivarse de la consulta de detalle de un PayOut.

Respuestas de detalles de un PayOut por referenceId

Esta tabla muestra las respuestas que pueden derivarse de la consulta de detalle de un PayOut por referenceId.

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": 1000,
  "comment": "refund",
  "referenceId": "567895432456789",
  "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Respuesta

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

{
  "amount": 1000,
  "refundId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "received",
  "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

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.

Respuesta

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

{
  "amount": 1000,
  "comment": "refund",
  "createdAt": "2026-08-06T16:25:24.463Z",
  "referenceId": "567895432456789",
  "refundId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "received",
  "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "partial",
  "updatedAt": "2026-08-06T16:25:24.463Z"
}

📘

Webhooks

Conoce los detalles acerca de los webhooks para reembolsos.

Detalles de un reembolso por referenceId

Consulta el detalle de un reembolso por su referenceId. Utiliza este endpoint para conocer el detalle.

Respuesta

A continuación, se muestra un ejemplo de la respuesta obtenida al consultar un reembolso:

{
  "amount": 1000,
  "comment": "refund",
  "createdAt": "2026-08-06T17:35:29.668Z",
  "referenceId": "567895432456789",
  "refundId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "received",
  "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "partial",
  "updatedAt": "2026-08-06T17:35:29.668Z"
}

Estados de un reembolso

La siguiente tabla muestra los estados de creación de un reembolso y los posibles estados derivados del endpoint de detalles de un reembolso.

Respuestas

A continuación te mostramos las posibles respuestas que pueden derivarse de un reembolso.

Respuestas de solicitud de reembolso

A continuación, puedes ver los distintos códigos de respuesta que podrías recibir durante una solicitud de reembolso.