3. Intégrez Papi à votre application web

Intégrez Papi dans votre application, notamment la gestion des flux de paiement, des notifications et des paramètres spécifiques à l'environnement.

Environnements

Papi fournit un seul endpoint de production. Pour les tests, utilisez les indicateurs mode test décrits ci-dessous.

Production (transactions en direct) : https://app.papi.mg/dashboard/api/payment-links

Pendant le développement, définissez isTestMode: true dans vos requêtes pour simuler des paiements sans mouvement d'argent réel.
Pour les tests par carte, activez le Mode Test de l'application dans les paramètres de votre boutique depuis le tableau de bord et utilisez la carte de test dédiée.

Vue d'ensemble du flux de paiement

Le processus de paiement se compose des étapes suivantes :

Obtenez votre clé API depuis le tableau de bord.
Créez un lien de paiement : Envoyez une requête API pour générer un lien de paiement unique pour le client.
Redirigez le client : Utilisez le paymentLink retourné pour envoyer le client vers la page de paiement sécurisée.
Traitement du paiement : Le client finalise le paiement sur la page sécurisée.
Recevez une notification : Après le paiement, Papi appelle votre notificationUrl avec le statut final.
Vérifiez et gérez le résultat : Contrôlez le notificationToken et le paymentReference pour confirmer l'authenticité et mettre à jour votre application.

Guide pas à pas pour implémenter l'intégration des paiements

Ce guide vous accompagne pas à pas pour intégrer l'API de paiement, depuis la création des pages de redirection jusqu'à la gestion des notifications.

Créez des pages de redirection

Vous devez configurer deux pages sur votre site web vers lesquelles les clients seront redirigés après le paiement :

URL de succès – La page affichée après un paiement réussi (ex. : confirmation de commande).
URL d'échec – La page affichée après un paiement échoué (ex. : message d'erreur avec option de réessai).

Notez ces deux URLs – vous en aurez besoin lors de la création du lien de paiement.

Créez l'endpoint de notification (API de callback)

L'endpoint de notification est une API que vous implémentez pour recevoir les mises à jour automatiques de statut de Papi.
Il doit accepter les requêtes POST.

Exemple de corps de notification envoyé par Papi

{
  "paymentStatus": "SUCCESS",
  "paymentMethod": "MVOLA",
  "currency": "MGA",
  "amount": 15000,
  "fee": 500,
  "clientName": "Nom du client",
  "description": "Paiement pour la commande #123",
  "merchantPaymentReference": "MERCHANT-0001",
  "paymentReference": "ORDER-123",
  "notificationToken": "xyz789",
  "message": "Paiement effectué avec succès.",
  "payerEmail": "client@example.com",
  "payerPhone": "+261340000000"
}

Explication des champs de notification

Champ	Type	Description
`paymentStatus`	string	`SUCCESS`, `PENDING` ou `FAILED`.
`paymentMethod`	string	La méthode utilisée (`MVOLA`, `ARTEL_MONEY`, `ORANGE_MONEY`, `BRED`).
`currency`	string	Code de la devise (toujours `MGA`).
`amount`	integer	Montant payé.
`fee`	integer	Frais de transaction déduits.
`clientName`	string	Nom du client tel que fourni.
`description`	string	La description du paiement que vous avez envoyée.
`merchantPaymentReference`	string	Référence interne du prestataire de paiement.
`paymentReference`	string	Votre référence unique pour ce paiement (depuis le champ `reference`).
`notificationToken`	string	Jeton retourné lors de la création du lien de paiement – utilisez-le pour vérifier l'authenticité.
`message`	string	Informations supplémentaires lisibles par l'humain.
`payerEmail`	string	Adresse email du client (si fournie).
`payerPhone`	string	Numéro de téléphone du client (si fourni).

Vérification de la notification

Pour s'assurer que la notification est authentique, vérifiez que :

paymentReference correspond à la référence que vous avez envoyée.
notificationToken correspond à celui que vous avez reçu dans la réponse de création du lien de paiement.

Si les deux correspondent, la notification est authentique et vous pouvez mettre à jour votre base de données en toute sécurité.

Préparez le corps et les en-têtes pour la création d'un lien de paiement

Vous enverrez une requête POST pour générer un lien de paiement.
Le corps doit inclure les URLs créées aux étapes 1 et 2, ainsi que les détails du paiement.

Endpoint

POST https://app.papi.mg/dashboard/api/payment-links

En-têtes

{
  "Content-Type": "application/json",
  "Token": "<VOTRE_CLÉ_API>"
}

Exemple de corps de requête

{
  "amount": 15000.0,
  "clientName": "Nom du client",
  "reference": "ORDER-123",
  "description": "Paiement pour la commande #123",
  "successUrl": "https://votreapp.com/paiement-succes",
  "failureUrl": "https://votreapp.com/paiement-echec",
  "notificationUrl": "https://votreapp.com/paiement-notif",
  "validDuration": 60,
  "provider": "MVOLA",
  "payerEmail": "client@example.com",
  "payerPhone": "+261340000000",
  "testReason": "QA interne",
  "isTestMode": false
}

Explication des champs de la requête

Champ	Type	Requis	Description
`clientName`	string	✓	Nom du client.
`amount`	number	✓	Montant du paiement (minimum 300).
`reference`	string	✓	Votre identifiant unique pour ce paiement (ex. : ID de commande).
`description`	string	✓	Description courte (max 255 caractères).
`successUrl`	string	✗	URL de redirection après le succès (doit commencer par http(s)://).
`failureUrl`	string	✗	URL de redirection après l'échec (doit commencer par http(s)://).
`notificationUrl`	string	✓	Votre endpoint qui reçoit les notifications de paiement (http(s)://).
`validDuration`	integer	✗	Durée de validité du lien en minutes (défaut : 1, doit être > 0).
`provider`	string	✗	Restreindre à un seul prestataire : `MVOLA`, `ARTEL_MONEY`, `ORANGE_MONEY`, `BRED`.
`payerEmail`	string	✗	Adresse email du client.
`payerPhone`	string	✗	Numéro de téléphone du client.
`testReason`	string	✗	Raison de l'utilisation du mode test (apparaît dans le tableau de bord).
`isTestMode`	boolean	✗	Définir à `true` pour activer le mode test (voir la section « Mode Test » ci-dessous).

Envoyez la requête POST pour récupérer le lien de paiement

Effectuez la requête avec le corps et les en-têtes de l'étape 3.
En cas de succès, vous recevez une réponse comme celle-ci :

{
  "data": {
    "amount": 15000.0,
    "currency": "MGA",
    "linkCreationDateTime": 1723850012,
    "linkExpirationDateTime": 1723853612,
    "paymentLink": "https://pay.papi.mg/payment/abc123",
    "clientName": "Nom du client",
    "paymentReference": "ORDER-123",
    "description": "Paiement pour la commande #123",
    "successUrl": "https://votreapp.com/paiement-succes",
    "failureUrl": "https://votreapp.com/paiement-echec",
    "notificationUrl": "https://votreapp.com/paiement-notif",
    "payerEmail": "client@example.com",
    "payerPhone": "+261340000000",
    "notificationToken": "xyz789",
    "testReason": "QA interne",
    "isTestMode": false
  }
}

Champs importants de la réponse

Champ	Description
`paymentLink`	L'URL vers laquelle le client doit être redirigé pour payer.
`notificationToken`	Conservez-le – vous en aurez besoin pour vérifier les futures notifications.

Redirigez l'utilisateur vers l'URL de paiement

Extrayez le paymentLink de la réponse et redirigez le client :

Applications web : Ouvrez le lien dans un nouvel onglet de navigateur ou effectuez une redirection HTTP.
Applications mobiles : Utilisez une WebView ou le navigateur par défaut de l'appareil.
Conseil : Certaines plateformes réinitialisent les WebViews lorsque l'application passe en arrière-plan – gérez cela avec soin pour éviter la perte d'état.

Une fois redirigé, le client finalise le paiement sur la page sécurisée de Papi. Après la transaction, il est renvoyé vers votre successUrl ou failureUrl, et votre notificationUrl reçoit le statut final.

Écran de choix du paiement

Formulaire de paiement Orange Money

Mode Test

Papi propose deux façons de tester votre intégration :

1. Indicateur `isTestMode` dans la requête

Définissez "isTestMode": true dans le corps de la requête.
La transaction est marquée comme test dans votre tableau de bord, mais de l'argent réel est quand même déplacé.
Utile pour les tests de bout en bout avec de vrais prestataires (sauf pour le mobile money, qui ne prend pas en charge les transactions de test non réelles).

2. Mode Test de l'application (cartes uniquement)

Dans les paramètres de votre boutique dans le tableau de bord, activez le Mode Test.
Utilisez les informations de la carte de test suivante :
- Numéro de carte : 4000 0000 0000 5126
- Date d'expiration : 01/2028
- CVV : 123
Cela simule un paiement par carte sans mouvement de fonds réels.

Récapitulatif du flux de travail

Obtenez votre clé API depuis le tableau de bord (Icône avatar → Boutiques → sélectionnez la boutique → onglet Développeur).
Créez un lien de paiement en envoyant une requête POST avec les champs requis.
Redirigez le client vers le paymentLink retourné.
Recevez une notification sur votre notificationUrl lorsque le statut du paiement change.
Vérifiez la notification à l'aide de paymentReference et notificationToken.
Mettez à jour vos enregistrements et informez le client.

En suivant ces étapes, vous pouvez accepter des paiements en ligne de manière sécurisée avec Papi. Testez toujours minutieusement en mode test avant de passer en production.

Environnements​

Vue d'ensemble du flux de paiement​

Guide pas à pas pour implémenter l'intégration des paiements​

Exemple de corps de notification envoyé par Papi​

Explication des champs de notification​

Vérification de la notification​

Endpoint​

En-têtes​

Exemple de corps de requête​

Explication des champs de la requête​

Champs importants de la réponse​

Mode Test​

1. Indicateur isTestMode dans la requête​

2. Mode Test de l'application (cartes uniquement)​

Récapitulatif du flux de travail​