Pagos externos

🟡 Próximamente. Este es el diseño completo del contrato; se está construyendo.

Cuando un cliente paga su factura de internet en un cajero automático, la banca en línea de su banco, o un kiosco de pago de servicios, esa red necesita tres cosas de Valwisp: saber cuánto debe el cliente, poder confirmar que se pagó, y poder revertir si algo salió mal. Este grupo de endpoints resuelve exactamente eso.

Un contrato, cualquier red

En vez de un contrato distinto por cada red de cobro con la que te integres, estos 4 endpoints son genéricos — sirven para cualquier banco, cajero o kiosco que quiera integrarse con Valwisp, presente o futuro. Cada red que se conecta recibe su propia API key con scope pagos-externos, y el nombre de la red viaja en cada petición:

{ "red": "banco-popular", "...": "..." }

Esto significa que sumar una red de cobro nueva es una integración nueva, no un endpoint nuevo que Valwisp tenga que construir y mantener por separado.

Consultar deuda

El primer paso: el cliente ingresa su cédula en el cajero/app del banco, y la red consulta cuánto debe.

POST /pagos-externos/consultar-deuda
Authorization: Bearer vw_live_...
Content-Type: application/json

{
  "red": "banco-popular",
  "cedula": "40245678901"
}

{
  "success": true,
  "data": {
    "codigo": "000",
    "facturas": [
      { "idFactura": "inv_2161", "detalle": "Servicio de internet — Agosto 2026", "monto": 1500.00 }
    ]
  },
  "timestamp": "2026-08-05T14:00:00.000Z"
}

Si el cliente no tiene facturas pendientes, facturas viene vacío — no es un error.

Registrar pago

El cliente paga en el cajero/kiosco; la red confirma el pago a Valwisp.

POST /pagos-externos/registrar-pago
Content-Type: application/json

{
  "red": "banco-popular",
  "idFactura": "inv_2161",
  "monto": 1500.00,
  "fecha": "2026-08-05",
  "secuencial": "123456789123"
}

secuencial es el número de operación que asigna la red — es la clave de idempotencia: si la red reintenta la confirmación (por ejemplo, porque no recibió respuesta a tiempo), el mismo secuencial no genera un segundo pago.

{
  "success": true,
  "data": {
    "codigo": "000",
    "idFactura": "inv_2161",
    "mensaje": "Pago registrado — Factura inv_2161"
  },
  "timestamp": "2026-08-05T14:00:00.000Z"
}

codigo sigue la convención bancaria estándar ("000" = éxito) para que los sistemas de conciliación de la red puedan procesarlo sin lógica especial para Valwisp.

Reversar un pago

Si la red no recibe confirmación de registrar-pago a tiempo, o necesita deshacer un pago aplicado por error:

POST /pagos-externos/reversar
Content-Type: application/json

{
  "red": "banco-popular",
  "idFactura": "inv_2161",
  "secuencial": "123456789123"
}

Solo revierte pagos que coincidan exactamente por secuencial — no se puede reversar "el último pago" a ciegas.

Conciliación diaria

Para que la red compare sus registros contra los de Valwisp al cierre del día:

GET /pagos-externos/conciliacion?red=banco-popular&fecha=2026-08-05

{
  "success": true,
  "data": {
    "transacciones": [
      { "secuencial": "123456789123", "idFactura": "inv_2161", "monto": 1500.00, "estado": "aplicado" }
    ]
  },
  "timestamp": "2026-08-05T14:00:00.000Z"
}