Intégrer Yappy et les paiements au Panama sans mauvaises surprises (Laravel + WordPress)

Ajouter un bouton « Payer avec Yappy » est la partie visible. Ce qui évite les maux de tête, c’est l’invisible : le montant est calculé côté serveur, la commande a des états clairs, et le système sait quoi faire si le client ferme l’app au milieu du paiement.

Ce guide décrit un modèle backend-first avec Laravel. Si votre vitrine est WordPress ou WooCommerce, le CMS reste la devanture ; la logique sensible vit hors du thème. La même approche s’applique à Yappy (Banco General), BAC Credomatic, Paguelo Fácil et aux passerelles unifiées.

Pourquoi c’est important au Panama

Yappy est un moyen de paiement très utilisé. Un flux mal conçu ne « échoue » pas seulement en staging : il crée des ventes fantômes, des encaissements sans commande, ou des commandes payées que personne ne peut prouver au support ou à la compta.

• Confiance : le client doit savoir s’il a payé ou non, sans ambiguïté.
• Opérations : l’équipe doit réconcilier banque vs commandes sans Excel éternel.
• Sécurité : si le navigateur décide du prix, quelqu’un le manipule.
• Évolutivité : demain vous voudrez peut-être BAC ou Paguelo Fácil sans réécrire la boutique.

Yappy en pratique

Pensez à Yappy comme un « guichet numérique » : votre serveur demande une intention d’encaissement, le client finalise le paiement dans l’app ou via redirect, et votre système reçoit la confirmation par un canal de confiance (pas seulement l’URL de retour).

1. Inscription du commerce et credentials (merchantId / secret) sur le portail commercial.
2. Le serveur génère une URL ou intention de paiement avec le bon montant.
3. L’utilisateur finalise le paiement dans le flux Yappy (app / redirect).
4. Redirect + notification endpoint mettent à jour la commande après validation de signature.

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

Avant d’afficher le bouton, le serveur doit faire le travail lourd :

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 avec ces montants.
5. Renvoyer au front uniquement ce qui est nécessaire pour continuer (redirect ou données minimales).

WordPress / WooCommerce sans polluer le thème

Sur des sites avec Elementor, thèmes sur mesure ou WooCommerce, les secrets ne doivent pas vivre dans functions.php ni dans des snippets du page builder. C’est comme coller la clé du coffre sur la vitrine.

• 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 (étapes)

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

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 visible.
• Déployer avec le tag latest et des secrets intégrés dans l’image Docker.
• Ne pas persister le payload du fournisseur : impossible d’auditer ensuite.

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 (signature / champs).
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.

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