# API de paiement Mobile Money pour les développeurs Pour les développeurs LonghoPay donne à votre serveur une requête pour créer une page de paiement hébergée, des webhooks signés pour connaître le résultat, et un bac à sable qui se comporte comme les vrais réseaux. Vos clients paient par MTN Mobile Money ou Orange Money, et l’argent arrive à l’entreprise pour laquelle vous développez. Aucune entreprise marchande, aucun numéro de versement ni aucune vérification n’est nécessaire pour commencer. Le bac à sable ne coûte rien. Commande 1001 Deux billets pour le départ de samedi. Montant du paiement 5 000 FCFA Numéro mobile money 655010010 Votre nom Aisha N. Infos facultatives E-mail pour votre reçu ## Ce que vous obtenez ### Page de paiement hébergée Une requête authentifiée renvoie une URL de paiement. La page LonghoPay gère le numéro de téléphone, les frais et la validation sur le téléphone du client. ### Webhooks signés Les événements de paiement réussi, échoué, en cours et expiré, signés en HMAC-SHA256, retentés avec délai croissant et renvoyables depuis le portail. ### Un vrai bac à sable Une clé d’accès bac à sable atteint un simulateur. Le numéro du payeur choisit le résultat, pour répéter un refus ou une absence de réponse sans vrai téléphone. ### Journaux, usage et état Journal des requêtes, historique des livraisons et usage de l’API par application, plus une lecture d’état pour les moments où un webhook tarde. ## Comment les pièces se parlent Quatre appels et un webhook. Les deux flèches en pointillé sont celles qui ne prouvent jamais un paiement à elles seules. ## Ce que votre serveur envoie La même requête dans trois langages. Gardez la clé d’accès sur le serveur ; le navigateur ne reçoit jamais que checkout_url. ## Du compte au premier paiement Inscrivez-vous et vérifiez votre adresse e-mail. Ouvrez votre espace et soumettez une application bac à sable. Un administrateur de la plateforme l’examine et l’approuve. Créez une clé d’accès serveur et un point de réception webhook. Intégrez, répétez dans le bac à sable, puis passez en production avec une application de production. ## Guide d’intégration, pas à pas D’un compte vide à un paiement réel. Chaque étape nomme l’écran ou la requête concernée, et rien ne suppose qu’une entreprise marchande existe déjà. ### 1. Créez votre compte développeur et ouvrez un espace Inscrivez-vous avec votre nom et votre adresse e-mail, ouvrez le lien de vérification et choisissez un mot de passe. Ouvrez ensuite le portail développeur, puis votre espace. Aucune entreprise marchande, aucun numéro de versement ni aucune vérification d’entreprise n’est nécessaire à ce stade. Une même personne peut détenir un compte marchand et un espace développeur, mais chacun est autorisé séparément : s’inscrire comme développeur ne donne accès aux paiements d’aucune entreprise. ### 2. Soumettez une application et attendez son approbation Dans Applications, soumettez une application par environnement. Commencez par une application bac à sable : elle atteint un réseau simulé, donc rien de ce que vous en faites ne déplace d’argent. Un administrateur de la plateforme examine chaque application, bac à sable comme production. Tant qu’elle n’est pas approuvée, vous ne pouvez ni créer de clé d’accès ni enregistrer de webhook. Modifier le type d’intégration, les domaines de retour ou les restrictions d’adresse IP retire l’approbation et demande un nouvel examen. ### 3. Créez une clé d’accès serveur Une fois l’application approuvée, ouvrez Clés d’accès API et créez une clé avec les seules portées dont votre serveur a besoin. Pour une page de paiement hébergée, ce sont payments:create, payments:read et webhooks:manage. ### 4. Créez une session de paiement depuis votre serveur Votre site ou votre application demande à votre serveur de lancer un paiement. Votre serveur enregistre la commande, puis demande une session de paiement à LonghoPay. Chaque requête porte la clé d’accès en jeton Bearer, un X-Request-ID unique et une Idempotency-Key que vous conservez avec la commande. Champ Ce qu’il doit contenir La réponse est un 201 avec la session sous data. Conservez id, external_reference, amount, currency, expires_at et checkout_url. Le statut commence à OPEN ; payment_status et status_token restent null tant qu’un client n’a pas commencé à payer. Réessayer est sans risque. La même clé avec le même corps renvoie la session existante, de nouveau en 201. La même clé avec un montant, une référence, une URL de retour ou des métadonnées différents est refusée par un 409 IDEMPOTENCY_KEY_CONFLICT. Après un délai dépassé, réessayez avec la clé et le corps d’origine, jamais avec une nouvelle référence tant que l’originale n’est pas résolue. ### 5. Envoyez le client vers la page de paiement Redirigez le navigateur du client vers checkout_url. La page LonghoPay affiche le montant et les frais, demande le nom du client et son numéro MTN ou Orange, et envoie la demande d’approbation sur son téléphone. Votre clé d’accès n’est jamais utilisée par le navigateur. Une fois le paiement réussi ou échoué, la page propose un bouton vers votre URL de retour, complétée de longhopay_reference=. Un client qui arrive sur cette page n’est pas une preuve de paiement : retrouvez la commande dans vos propres enregistrements et affichez ce que votre serveur sait. ### 6. Recevez les webhooks et vérifiez leur signature Dans Webhooks, ajoutez un point de réception HTTPS abonné au moins à payment.succeeded et payment.failed ; ajoutez payment.processing et payment.expired pour suivre tout le cycle de vie. Le secret de signature n’est affiché qu’une fois, comme une clé d’accès. Lisez les octets bruts avant d’analyser le JSON. X-MobilePay-Signature est un HMAC-SHA256 de ., avec pour clé le secret de signature entier, préfixe whsec_ compris. Comparez en temps constant, rejetez un horodatage périmé, et enregistrez l’identifiant d’événement sous une contrainte d’unicité pour qu’une nouvelle livraison reste sans effet. Répondez 2xx rapidement et faites le vrai travail depuis votre propre file d’attente. Si vous préférez une bibliothèque Standard Webhooks, donnez-lui la valeur signing_secret_standard et laissez-la vérifier les en-têtes webhook-id, webhook-timestamp et webhook-signature. Vérifiez un seul schéma entièrement ; ne mélangez pas les deux. ### 7. Confirmez le paiement et honorez la commande Un événement payment.succeeded ressemble à ceci. Des champs peuvent être ajoutés ; jamais retirés. La livraison est au moins une fois : une livraison échouée est retentée jusqu’à sept fois sur environ une journée, et tout événement peut être renvoyé depuis le portail. Votre récepteur doit traiter un doublon comme déjà pris en charge. ### 8. Rattrapez un webhook qui n’arrive pas Exécutez une vérification en arrière-plan pour les commandes encore ouvertes après leur expiration. Lisez la session avec son jeton, puis l’état du paiement avec le status_token que la session renvoie. Ce que vous voyez Ce qu’il faut faire Les webhooks et cette vérification peuvent se croiser. Les deux doivent passer par la même déduplication de livraison. ### 9. Répétez dans le bac à sable Une clé d’accès bac à sable atteint un simulateur, jamais MTN ni Orange. Le résultat est scénarisé à partir du numéro du payeur saisi sur la page de paiement. Numéro du payeur Résultat Pour forcer le cas en attente vers une fin, appelez la route bac à sable avec la référence du paiement, le trid de la ressource d’état. FAILED est l’autre résultat accepté. Répétez le succès, le refus, le paiement non résolu, l’expiration d’une session inutilisée, une réponse perdue réessayée avec la même clé, une panne du récepteur et son renvoi, et des événements en double ou dans le désordre. Les paiements bac à sable ne sont jamais versés et n’apparaissent sur le tableau de bord d’aucune entreprise. ### 10. Passez en production L’entreprise est propriétaire des fonds et des versements. Révoquer l’autorisation arrête les nouvelles sessions de paiement ; les paiements déjà soumis vont jusqu’à leur résultat enregistré. ### Erreurs et codes d’état Décidez d’après le code HTTP et le champ code de la réponse, jamais d’après le texte du message. Code Signification et action Un délai dépassé côté client pendant une commande monétaire est un résultat inconnu. Interrogez avec votre référence enregistrée, réutilisez la même clé d’idempotence, et laissez le webhook ou la vérification d’état trancher. Conservez le request_id de chaque réponse pour le support. La spécification OpenAPI complète peut être téléchargée depuis le portail développeur. ## Commencez à développer aujourd’hui Créez votre compte développeur, soumettez une application bac à sable et effectuez votre premier paiement de test.