Integrar Yappy y pagos en Panamá sin sorpresas (Laravel + WordPress)

Poner un botón de “Pagar con Yappy” es la parte visible. Lo que evita dolores de cabeza es lo invisible: el monto se calcula en el servidor, el pedido tiene estados claros, y el sistema sabe qué hacer si el cliente cierra la app a mitad del pago.

Esta guía describe un patrón backend-first con Laravel. Si tu vitrina es WordPress o WooCommerce, el CMS se queda como escaparate; la lógica sensible vive fuera del tema. El mismo enfoque sirve para Yappy (Banco General), BAC Credomatic, Paguelo Fácil y pasarelas unificadas.

Por qué importa en Panamá

Yappy es una forma de cobro muy usada. Un flujo mal diseñado no solo “falla en staging”: genera ventas fantasmas, cobros sin pedido, o pedidos pagados que nadie puede probar ante soporte o contabilidad.

• Confianza: el cliente necesita saber si pagó o no, sin ambigüedad.
• Operación: el equipo debe reconciliar banco vs pedidos sin Excel eterno.
• Seguridad: si el navegador decide el precio, alguien lo manipula.
• Escalabilidad: mañana quieres BAC o Paguelo Fácil sin reescribir la tienda.

Qué es Yappy en la práctica

Piensa en Yappy como una “ventanilla digital”: tu servidor pide una intención de cobro, el cliente completa el pago en la app o redirect, y tu sistema recibe la confirmación por un canal confiable (no solo por la URL de retorno).

1. Alta del comercio y credenciales (merchantId / secret) en el portal comercial.
2. El servidor genera URL o intención de pago con el monto correcto.
3. El usuario completa el pago en el flujo de Yappy (app / redirect).
4. Redirect + notificación al endpoint actualizan la orden con validación de firma.

Regla de oro: el pago nace en el backend

Antes de mostrar el botón, el servidor debe hacer el trabajo pesado:

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 con esas cifras.
5. Devolver al front solo lo necesario para continuar (redirect o datos mínimos).

WordPress / WooCommerce sin ensuciar el tema

En sitios con Elementor, temas a medida o WooCommerce, los secretos no deben vivir en functions.php ni en snippets del page builder. Es como dejar la llave de la caja fuerte pegada en la vitrina.

• 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 (pasos)

1. Modelos 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

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 visible.
• Deploy con tag latest y secretos horneados en la imagen Docker.
• No persistir el payload del proveedor: imposible auditar después.

Checklist técnico

1. Credenciales solo en variables de entorno.
2. Sandbox y 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 (firma / campos).
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.

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