Integra pagos de agua potable con Openpay Paynet

Genera referencias de tienda, procesa layouts masivos, recibe webhooks, entrega callbacks firmados y concilia pagos para multiples organismos operadores.

Explorar Swagger UI Leer Redoc Abrir consola admin

Ambientes

Sandbox	`https://sandbox-api.example.com`
Producción	`https://api.example.com`
Local	`http://localhost:3000`

Guía rápida

Autentica cada solicitud con x-api-key y usa Idempotency-Key para evitar duplicados.

curl -X POST http://localhost:3000/api/v1/payment-references \
  -H "Content-Type: application/json" \
  -H "x-api-key: test-api-key" \
  -H "Idempotency-Key: RECIBO-2026-000001" \
  -d '{
    "external_reference": "RECIBO-2026-000001",
    "contract_number": "CONTRATO-123456",
    "customer_name": "Juan Perez",
    "amount": 248.50,
    "currency": "MXN",
    "description": "Pago de agua potable junio 2026",
    "due_date": "2026-07-15T23:59:59-06:00",
    "period": "2026-06"
  }'

Autenticación

API keys por cliente para integraciones y Bearer Token para administración. Permisos por alcance y auditoría por actor.

Layouts masivos

Soporte documentado para JSON, CSV y XLSX con procesamiento parcial, errores por línea y reintentos.

Conciliación

Jobs automáticos cada 15 minutos, cada hora, diarios y semanales para recuperar eventos y pagos tardíos.

Endpoints principales

Método	Endpoint	Uso
POST	`/api/v1/payment-references`	Crear referencia Paynet individual.
POST	`/api/v1/payment-references/batches`	Crear lote masivo JSON.
POST	`/api/v1/payment-references/batches/upload`	Cargar CSV/XLSX.
POST	`/api/v1/webhooks/openpay`	Recibir webhooks Openpay.
POST	`/api/v1/reconciliation`	Conciliar referencias pendientes.

SDKs y ejemplos

La API es REST/JSON y puede consumirse con cualquier cliente HTTP. La guía incluye ejemplos en curl, JavaScript, PHP, C# y Java.

Ver ejemplos de integración

Errores

Código	Significado
400	Validación fallida.
401	API key, token o firma inválida.
403	Permisos insuficientes.
404	Recurso no encontrado.
409	Conflicto de idempotencia o duplicado.
429	Rate limit excedido.
502	Error al comunicarse con Openpay.

Sandbox y producción

Usa sandbox para pruebas con referencias simuladas o credenciales Openpay de pruebas. En producción se exige HTTPS, secretos reales, CORS restringido y callbacks firmados.

Webhooks y callbacks

Openpay notifica cambios de estado y la plataforma envía callbacks HMAC-SHA256 al sistema externo configurado.

sequenceDiagram participant Openpay participant API participant Cliente Openpay->>API: payment.paid API->>API: Validar firma y registrar evento API->>API: Actualizar referencia a paid API->>Cliente: POST callback firmado Cliente-->>API: 200 OK

Conciliación y recuperación

El módulo de conciliación consulta Openpay, compara estados/importes, actualiza diferencias, registra bitácora y reintenta callbacks fallidos.

flowchart TD A[Referencias pendientes] --> B[Job cada 15 minutos] B --> C[Consultar Openpay] C --> D{Hay diferencia} D -- No --> E[Registrar reconciled] D -- Si --> F[Actualizar estado] F --> G[Enviar callback] G --> H{Callback OK} H -- Si --> I[callback_sent] H -- No --> J[callback_failed y retry]