Intégration de Yappy et des paiements au Panama avec Laravel et WordPress

Intégrer Yappy dans un commerce panaméen, c'est bien plus qu'ajouter un bouton de paiement. Il faut un flux clair, un montant signé côté serveur, des états qui survivent aux interruptions de l'utilisateur, et un backend capable d'expliquer pourquoi une commande est payée ou non.

Cet article décrit le modèle backend-first avec Laravel et, lorsque le front est WordPress ou WooCommerce, laisse le CMS comme vitrine et interface de checkout tout en déplaçant la logique sensible hors du thème. S'applique aux intégrations Yappy, BAC Credomatic, Paguelo Fácil et passerelles unifiées.

Yappy en pratique

Yappy (Banco General) est un moyen de paiement très utilisé au Panama. Dans les intégrations commerciales typiques :

1. Inscription du commerce et credentials (merchantId / secret) sur le portail commercial.
2. Génération d'une URL ou intention de paiement depuis le serveur.
3. L'utilisateur finalise le paiement dans le flux Yappy (app / redirect).
4. Le système reçoit le résultat via redirect + notification endpoint et met à jour la commande.

Règle d'or : le paiement naît dans le backend

Avant d'afficher le bouton côté front, le serveur doit :

1. Créer ou récupérer la commande avec articles, devise et taxes.
2. Calculer le total côté serveur (ne jamais faire confiance au JSON du navigateur).
3. Enregistrer un paiement en état pending avec un order_id interne.
4. Demander à Yappy l'URL / token de paiement avec ces montants.
5. Rediriger ou renvoyer au front uniquement ce qui est nécessaire pour continuer.

WordPress / WooCommerce sans polluer le thème

Sur des sites WordPress avec Elementor, thèmes sur mesure ou WooCommerce, les secrets ne doivent pas se trouver dans functions.php ni dans des snippets du page builder.

Modèle recommandé :

• WooCommerce crée la commande locale.
• Un endpoint ou plugin léger appelle l'API Laravel (passerelle).
• Laravel communique avec Yappy / BAC / Paguelo Fácil.
• WordPress reflète l'état lorsque le backend confirme.

Implémentation Laravel

1. Modèles Order + Payment avec états normalisés.
2. Service PaymentGateway avec adapters derrière une interface.
3. Endpoint protégé pour démarrer le paiement : valide le panier, calcule le total, persiste pending.
4. Endpoint callback/IPN : vérifie la signature, est idempotent, dispatch un job de réconciliation.
5. Page de retour qui consulte l'état en DB ; ne marque pas paid via query string.
6. File d'attente pour les retries quand la banque notifie tard.
7. Secrets uniquement dans l'env de l'hôte (Coolify : variables du service, pas de .env dans Git).

États normalisés

Checklist technique

1. Credentials uniquement dans les variables d'environnement.
2. Sandbox et production séparés.
3. Idempotence : le même order_id ne crée pas deux prélèvements.
4. Persister le payload pour l'audit.
5. Valider ce que le fournisseur renvoie.
6. Jobs pour les retries de réconciliation.
7. Logs sans secrets ni données de carte.
8. Page de résultat qui interroge le backend.
9. Healthcheck et workers actifs au déploiement.
10. Runbook de rotation des secrets et retraitement IPN.

Erreurs fréquentes en production

• Confirmer une vente uniquement parce que l'utilisateur est arrivé sur /pago-exitoso.
• Laisser le secret dans un plugin WordPress versionné dans Git.
• Mélanger la logique Yappy, BAC et Paguelo Fácil dans un seul if géant.
• Oublier le cas « l'utilisateur a payé et fermé l'app » sans callback.
• Déployer avec latest et des secrets intégrés dans l'image Docker.

Cette intégration est liée à Docker, CI/CD et Coolify, l'audit de sécurité et les paiements en ligne .