LengoPay

Capabilities

Gotchas

• ⚠amount doit être une string numérique (ex: "1000"), pas un number. Passer un number provoque une erreur 400.
• ⚠Le status "Success" dans la réponse indique seulement que la requête a été reçue, pas que le paiement est effectué. Utiliser cashin_status ou le callback pour connaître le résultat final.
• ⚠pay_id retourné est encodé en base64 — le conserver tel quel pour l'utiliser dans cashin_status, sans décodage.
• ⚠callback_url doit être une URL HTTPS valide. Les URLs HTTP sont ignorées silencieusement.
• ⚠type_account doit correspondre au réseau du numéro account (ex: ne pas utiliser lp-om-gn pour un numéro MTN).
• ⚠Utiliser le pay_id base64 retourné par cashin_request sans décodage — LengoPay l'attend tel quel.
• ⚠PENDING signifie que le paiement est en cours de traitement sur le réseau mobile. Ne pas considérer PENDING comme final — attendre SUCCESS ou FAILED.
• ⚠Ne jamais fulfiller une commande sur le statut PENDING, même après plusieurs vérifications successives.
• ⚠Stocker pay_id immédiatement avant de rediriger l'utilisateur — c'est le seul identifiant pour appeler verify_payment et confirmer le paiement côté serveur.
• ⚠Le header Authorization attend la license key directement : 'Basic {license_key}'. Ce n'est pas du Basic Auth standard (pas de base64 username:password) — passer la clé telle quelle.
• ⚠websiteid est un paramètre requis distinct de la license key. Les deux doivent être configurés comme variables d'environnement séparées.
• ⚠Il n'y a pas de sandbox. Tous les appels touchent la production — utiliser de petits montants pour les tests.
• ⚠balance est retourné comme une string (ex: "7792"), pas un number — utiliser parseFloat(balance) avant tout calcul.
• ⚠L'URL n'a pas de préfixe /v1/ contrairement aux autres endpoints LengoPay (ex: /api/getbalance/ et non /api/v1/getbalance/).
• ⚠Retourne uniquement les transactions Cash In (push vers numéro de téléphone via cashin_request). Pour les transactions Cash Out via URL de paiement, utiliser list_transactions.
• ⚠Le champ account peut être retourné comme number ou string selon la réponse — normaliser avec String(account) avant utilisation.
• ⚠Retourne uniquement les transactions Cash Out (paiements initiés via create_payment avec URL de paiement). Pour les transactions Cash In, utiliser list_cashin_transactions.
• ⚠Le champ status peut être une string ("SUCCESS") ou un entier (0) selon la transaction — normaliser avant utilisation.
• ⚠Toujours appeler verify_payment côté serveur avant de valider une commande. Le webhook seul ne suffit pas — il peut être forgé par quiconque connaît votre callback_url.
• ⚠PENDING est un statut valide : le paiement est en cours de traitement. Ne pas fulfiller la commande sur PENDING — attendre SUCCESS.
• ⚠Le statut est en UPPERCASE strict : comparer avec status === 'SUCCESS'.
• ⚠L'endpoint a changé en v1.2.0 : il est désormais POST /api/v1/transaction/status avec pay_id et websiteid dans le body. L'ancien GET /api/v1/payments/{payId} ne fonctionne plus.
• ⚠Ne jamais fulfiller une commande sur la base du webhook seul. Appeler verify_payment (GET /api/v1/payments/{payId}) pour confirmer côté serveur — le webhook peut être forgé par quiconque connaît votre callback_url.
• ⚠Répondre HTTP 200 immédiatement et traiter le paiement de façon asynchrone. LengoPay retry en cas d'échec, ce qui peut provoquer des doublons si votre handler est lent.
• ⚠Implémenter l'idempotence : LengoPay peut envoyer le même webhook plusieurs fois pour le même pay_id. Vérifier que la commande n'est pas déjà fulfillée avant d'agir.
• ⚠Le champ Client contient le numéro de téléphone du payeur (ex: '624897845'). Il est absent du payload dans certains cas — ne pas en dépendre.
• ⚠[MUST TELL USER] LengoPay n'appelle le callback_url qu'en HTTPS — les URLs http:// sont silencieusement ignorées. En développement local, le webhook ne se déclenchera jamais sans tunnel HTTPS. Indiquer explicitement à l'utilisateur : lancer `ngrok http 3000`, puis mettre à jour NEXT_PUBLIC_BASE_URL (ou l'équivalent) avec l'URL ngrok avant de tester.