Errores al llamar /InicioPago
| Síntoma | Causa probable | Solución |
|---|---|---|
| HTTP 404 | URL mal escrita | Verifica que sea Apis_CicloPago/api/InicioPago (no dummie_ciclopago). |
| HTTP 415 | Falta header Content-Type | Añadir Content-Type: application/json. |
| HTTP 400 | JSON malformado | Validar con un JSON linter antes de enviar. |
| HTTP 500/502/503 | Error del servidor | Reintentar con backoff. Si persiste, contactar soporte. |
| Timeout | Red saturada o servidor lento | Timeout recomendado: 30s. Reintentar si procede. |
int_codigo: 2 + “Object reference…” | Credenciales inválidas, campo faltante, o comercio inexistente | Revisar credenciales y estructura del body. |
int_codigo: 2 sin descripción útil | Falta un campo obligatorio | Revisar InformacionPago.flt_total_con_iva, str_id_pago, str_descripcion_pago. |
| ”Código 50 requerido” | Tu comercio tiene PSE pero no enviaste AdicionalesConfiguracion con código 50 | Incluir { "int_codigo": 50, "str_valor": "tu_codigo_servicio" }. |
| str_id_pago rechazado | Tiene ceros a la izquierda o supera 30 caracteres | Usar un ID sin ceros iniciales, máximo 30 chars. |
| Duplicate key / ID ya usado | Reutilizaste un str_id_pago | Generar un ID único por pago. |
Errores al llamar /VerificacionPago
| Síntoma | Causa probable | Solución |
|---|---|---|
int_estado: 2, str_detalle: "Credenciales inválidas" | Usuario/clave mal | Revisar env vars. |
int_cantidad_pagos: 0 cuando esperabas pagos | El usuario no inició el ciclo de pago, o estás consultando un ID que nunca creaste | Verificar str_id_pago exacto. |
str_res_pago vacío a pesar de int_cantidad_pagos > 0 | Bug raro del API | Contactar soporte. |
Campo str_pwd_Comercio rechazado | Lo escribiste con minúscula (str_pwd_comercio) | Debe ser str_pwd_Comercio con C mayúscula. |
Errores durante la sonda
| Síntoma | Causa probable | Solución |
|---|---|---|
| Dos sondas corriendo en paralelo | Falta lock distribuido | Implementar lock con Redis/DB. |
| Sonda consume 100% CPU | Query SQL no filtra pagos cerrados | Revisar WHERE estado_local = 'pendiente'. |
Pagos que nunca cambian de 999 | Usuario abandonó tras autorizar PSE | Marcar como abandonado tras 48h. |
| Sonda falla silenciosamente | Excepción no manejada | Envolver cada iteración en try/catch. |
| Notificaciones duplicadas al usuario | Sonda no marca pagos como “notificado” | Añadir flag notificado en BD. |
Errores en el callback
| Síntoma | Causa probable | Solución |
|---|---|---|
| No recibes callback | URL de retorno mal configurada en el comercio | Verificar config o enviar código 104 dinámicamente. |
| Callback llega al dominio equivocado | Dev y prod comparten config | Usar código 104 con URL según ambiente. |
Recibes callback sin id_pago | El formulario fue interrumpido | Manejar este caso sin crashear. |
| Callback duplicado | Usuario recarga la página | Implementar idempotencia. |
Errores al parsear str_res_pago
| Síntoma | Causa probable | Solución | |
|---|---|---|---|
| Array vacío cuando sí hay pagos | str_res_pago es null o string vacío | Verificar en int_cantidad_pagos primero. | |
| Campos shifted (datos en posiciones incorrectas) | Un valor opcional tiene un pipe ` | ` interno | No enviar pipes en str_opcional1-5. |
Campo int_id_forma_pago vacío | Pago aún no ha sido procesado por ningún medio | Normal si estado es 888. | |
| Campos extras faltantes para medio 29 o 32 | Parser no considera el medio | Revisar el mapa EXTRAS_POR_MEDIO. |
Errores de producción
| Síntoma | Causa probable | Solución |
|---|---|---|
| Pagos aprobados que no se reflejan en mi BD | Callback no llega o es ignorado | Verificar logs del endpoint de retorno. La sonda debería resolverlo. |
| Pedidos duplicados en producción | Falla de idempotencia en callback | Revisar Idempotencia. |
| Clientes reclaman que pagaron pero no recibieron producto | Falla en la sonda o en lógica de entrega | Consultar /VerificacionPago manualmente con el str_id_pago reportado. |
| Tasa de rechazo súbitamente alta | Problema con la red de pagos, no contigo | Contactar soporte ZonaPagos para confirmar. |
Cuándo contactar soporte
Contacta a soporte@zonapagos.com cuando:- Un pago específico tiene comportamiento anómalo y ya verificaste tu código.
- Recibes errores que no aparecen en estas tablas.
- La tasa de errores sube sin cambios en tu código.
- Necesitas credenciales de preproducción.
- Necesitas certificación PSE.
- Tu
int_id_comercio. str_id_pagodel caso específico.- Timestamp del intento (hora Colombia).
- Request y response completos (ocultando
str_clave). - Logs de tu lado si los tienes.
Ver también
FAQ
Preguntas más frecuentes.
Manejo de errores
Estrategia general.