Referencias Agua Potable

Integra referencias de pago para agua potable

Genera referencias Paynet/Openpay, BBVA CIE, Banco Azteca y Santander para recibos individuales o masivos, consulta estados, recibe webhooks y concilia pagos.

Explorar Swagger UI Leer guia rapida

Ambientes

Sandbox publicadohttps://pagos-op.aiscomds.com.mx
Webhook Openpayhttps://pagos-op.aiscomds.com.mx/api/v1/webhooks/openpay

Guia rapida

Autentica con x-api-key y usa Idempotency-Key para evitar duplicados. Si no envias providers, la API genera por defecto Paynet/Openpay, BBVA, Banco Azteca y Santander. BBVA, Banco Azteca y Santander no requieren datos internos por recibo; la plataforma genera las referencias localmente. Openpay usa payment_order_id como order_id tecnico.

curl -X POST https://pagos-op.aiscomds.com.mx/api/v1/payment-references \
  -H "Content-Type: application/json" \
  -H "x-api-key: TU_API_KEY" \
  -H "Idempotency-Key: RECIBO-2026-000001" \
  -d '{
    "external_id": "RECIBO-2026-000001",
    "customer_id": "CONTRATO-123456",
    "amount": 248.50,
    "description": "Pago de agua potable junio 2026",
    "expiration_date": "2026-07-31",
    "providers": ["openpay", "bbva", "banco_azteca", "santander"],
    "metadata": {
      "contract_id": "CONTRATO-123456",
      "customer_name": "Juan Perez",
      "customer_email": "juan@example.com",
      "customer_phone": "5555555555",
      "period": "2026-06"
    }
  }'

Importante: si repites el mismo external_id, la API devuelve la orden existente. El folio externo no se envia a Openpay como order_id; se usa un identificador tecnico payord_.... En sandbox Openpay envia datos de cliente completos en metadata: customer_name, customer_email y customer_phone.

Endpoints para integradores

MetodoEndpointUso
POST/api/v1/payment-referencesCrear referencias Paynet, BBVA, Banco Azteca y/o Santander.
POST/api/v1/payment-references/batchesCrear lote masivo JSON.
POST/api/v1/payment-references/batches/uploadCargar CSV/XLSX.
GET/api/v1/payment-references/{id}Consultar una orden.
GET/api/v1/payment-references/by-external/{external_id}Consultar por folio externo.
POST/api/v1/reconciliationConciliar referencias pendientes.

Respuesta resumida

{
  "payment_order_id": "payord_xxx",
  "external_id": "RECIBO-2026-000001",
  "status": "success",
  "references": [
    { "provider": "openpay", "reference": "1010100000000000" },
    { "provider": "bbva", "reference": "35842169876400000000" },
    { "provider": "banco_azteca", "reference": "00035842169876421995201" },
    { "provider": "santander", "reference": "123456789006759111970003286274" }
  ],
  "errors": []
}

Webhooks y callbacks

Openpay debe enviar eventos a https://pagos-op.aiscomds.com.mx/api/v1/webhooks/openpay. Cuando el pago se confirma, la plataforma actualiza el estado y puede avisar al callback configurado del sistema comercial.

En webhooks Openpay, transaction.order_id corresponde al payment_order_id tecnico de la plataforma.

Nota real: el webhook actualiza ordenes unificadas por la referencia Openpay. El callback automatico esta activo para el flujo legacy Paynet; en ordenes unificadas el reenvio de callback se realiza desde la consola administrativa.

Conciliacion

Si un webhook no llega, el sistema puede consultar o solicitar conciliacion de referencias pendientes. La plataforma tambien permite conciliacion operativa desde la consola administrativa.

Recursos