Integración de Yappy y pagos en Panamá con Laravel y WordPress

Integrar Yappy en un comercio panameño implica más que poner un botón de pago. Necesitas un flujo claro, el monto firmado en el servidor, estados que sobrevivan si el usuario interrumpe el proceso, y un backend que pueda explicar por qué un pedido quedó pagado o no.

Este artículo describe el patrón backend-first con Laravel y, cuando el front es WordPress o WooCommerce, deja el CMS como vitrina y checkout visual, y mueve la lógica sensible fuera del tema. Aplica a integraciones con Yappy, BAC Credomatic, Paguelo Fácil y pasarelas unificadas.

Qué es Yappy en la práctica

Yappy (Banco General) es una forma de cobro muy usada en Panamá. En integraciones comerciales típicas:

1. Alta del comercio y credenciales (merchantId / secret) en el portal comercial.
2. Generación de una URL o intención de pago desde el servidor.
3. El usuario completa el pago en el flujo de Yappy (app / redirect).
4. El sistema recibe el resultado por redirect + notificación al endpoint y actualiza la orden.

Regla de oro: el pago nace en el backend

Antes de mostrar el botón en el front, el servidor debe:

1. Crear o recuperar la orden con ítems, moneda e impuestos.
2. Calcular el total en servidor (nunca confiar en el JSON del navegador).
3. Guardar un registro de pago en estado pending con order_id interno.
4. Pedir a Yappy la URL / token de pago con esas cifras.
5. Redirigir o devolver al front solo lo necesario para continuar.

WordPress / WooCommerce sin ensuciar el tema

En sitios WordPress con Elementor, temas a medida o WooCommerce, los secretos no deben ir en functions.php ni en snippets del page builder.

Patrón recomendado:

• WooCommerce crea el pedido local.
• Un endpoint o plugin delgado llama a la API Laravel (pasarela).
• Laravel habla con Yappy / BAC / Paguelo Fácil.
• WordPress refleja el estado cuando el backend confirma.

Implementación en Laravel

1. Modelo Order + Payment con estados normalizados.
2. Servicio PaymentGateway con adapters detrás de una interfaz.
3. Endpoint protegido para iniciar pago: valida carrito, calcula total, persiste pending.
4. Endpoint de callback/IPN: verifica firma, es idempotente, despacha job de conciliación.
5. Página de retorno que consulta el estado en DB; no marca paid por query string.
6. Cola para reintentos cuando el banco notifica tarde.
7. Secrets solo en env del host (Coolify: variables del servicio, no .env en Git).

Estados normalizados

Checklist técnico

1. Credenciales solo en variables de entorno.
2. Sandbox vs producción separados.
3. Idempotencia: el mismo order_id no crea dos cobros.
4. Persistir payload para auditoría.
5. Validar lo que el proveedor envía de vuelta.
6. Jobs para reintentos de conciliación.
7. Logs sin secretos ni datos de tarjeta.
8. Página de resultado que consulta el backend.
9. Healthcheck y workers vivos en el deploy.
10. Runbook de rotación de secrets y reprocesamiento de IPN.

Errores frecuentes en producción

• Confirmar venta solo porque el usuario llegó a /pago-exitoso.
• Dejar el secret en un plugin de WordPress versionado en Git.
• Mezclar lógica de Yappy, BAC y Paguelo Fácil en un solo if gigante.
• Olvidar el caso "usuario pagó y cerró la app" sin callback.
• Deploy con latest y secretos horneados en la imagen Docker.

La integración conecta con Docker, CI/CD y Coolify, auditoría de seguridad y pagos en línea .