3. Intégrez Papi à votre boutique en ligne

Intégrez Papi dans votre application, y compris la gestion des flux de paiement, des callbacks, et des URLs spécifiques à l'environnement.

---

Environnements

Utilisez les bonnes URLs d'environnement en fonction de l'étape de votre application :

• Sandbox (Préproduction) : Pour les tests.
  • URL : https://paymentapi23i.ibonia.com/
• Production : Pour les transactions en direct.
  • URL : https://api.papi.mg/

---

Vue d'ensemble du flux de paiement

Le processus de paiement se compose des étapes suivantes :

1. Créer un lien de paiement : Envoyez une requête API pour générer un lien de paiement pour le client.
2. Rediriger le client : Utilisez l'URL de paiement retournée pour rediriger le client vers la page de paiement sécurisée.
3. Traiter le paiement : Le client termine le paiement sur la page sécurisée.
4. Recevoir un callback : Après le paiement, le système notifie votre serveur avec le résultat du paiement (succès ou échec).
5. Gérer le résultat : Mettez à jour votre application en fonction du statut du paiement reçu dans le callback.

---

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

Ce guide vous accompagnera pas à pas pour intégrer l'API de paiement, depuis la création des endpoints pour la redirection jusqu'à la gestion des callbacks et l'envoi des requêtes de lien de paiement.

---

Étape 1 : Créez des pages de redirection

Vous devez configurer deux pages sur votre site web pour rediriger les clients après le paiement :

• URL de succès : Cette page est celle où le client sera redirigé après un paiement réussi. Cela peut être une page existante (par exemple, une page de produits) ou une page nouvellement créée. Une fois la page configurée, notez son URL, car elle sera requise lors de la requête pour générer un lien de paiement.

• URL d'échec : Cette page est celle où le client sera redirigé après un paiement échoué. Elle peut être une page d'erreur ou une page existante (par exemple, une page de produits) avec un message personnalisé pour informer le client de l'échec du paiement. Une fois la page configurée, notez son URL, car elle sera requise lors de la requête pour générer un lien de paiement.

---

Étape 2 : Créez l'API de callback

L'API de callback est un endpoint que vous créez pour gérer les notifications de Papi sur le statut d'un paiement. Cette API sera appelée automatiquement par Papi une fois qu'une transaction est terminée, qu'elle soit réussie ou échouée.

Ce que vous devez faire :

1. Créer un endpoint API :

   • Le endpoint doit accepter les requêtes POST.
   • Par exemple, l'URL du endpoint pourrait être https://yourdomain.com/payment-callback.

2. Objectif de l'API de callback :

   • Papi enverra les détails du paiement à ce endpoint dans le corps d'une requête POST après la transaction.
   • Ces détails incluront des informations sur le statut de la transaction, le montant, la méthode de paiement, et plus encore.
   • Votre application pourra utiliser ces informations pour mettre à jour les enregistrements, notifier les utilisateurs ou déclencher d'autres processus.

---

Exemple de corps de callback envoyé par Papi :

{
  "description": "Paiement pour la commande #12345",
  "amount": 500.00,
  "transactionId": "abc123def456",
  "status": 200,
  "paymentMethod": 2,
  "sender": "customer@example.com"
}

---

Explication des champs du callback :

Champ	Type	Description
description	string	Une description du paiement (par exemple, le numéro de commande ou l'objet du paiement).
amount	number	Le montant de l'argent traité dans le paiement.
transactionId	string	Un identifiant unique pour la transaction, que vous pouvez utiliser pour suivre ou mettre à jour le paiement.
status	integer	Le statut de la transaction : 1 pour le succès, 0 pour l'échec.
paymentMethod	integer	La méthode de paiement utilisée : 1 pour carte, 2 pour mobile money, etc.
sender	string	L'email ou l'identifiant du payeur ayant initié le paiement.

---

Étape 3 : Préparez le corps et l'en-tête pour la requête de lien de paiement

Pour générer un lien de paiement, vous devez envoyer une requête POST avec le corps et les en-têtes appropriés. Cette étape est cruciale car elle lie ensemble les URLs de succès, d'échec et de callback créées précédemment.

Endpoint

/clients/login

En-têtes

{
  "Content-Type": "application/json",
  "AuthentificationKey": "Ibonia <your-application-api-key>"
}

---

Exemple de corps pour MGA :

{
  "amount": 500,
  "change": {
    "currency": "MGA",
    "rate": 1
  },
  "failureUrl": "https://yourdomain.com/failure",
  "successUrl": "https://yourdomain.com/success",
  "callbackUrl": "https://yourdomain.com/payment-callback",
  "clientEmail": "customer@example.com",
  "paymentDescription": "Paiement pour la commande #12345"
}

---

Exemple de corps pour EUR :

{
  "amount": 500,
  "change": {
    "currency": "EUR",
    "rate": 4800
  },
  "failureUrl": "https://yourdomain.com/failure",
  "successUrl": "https://yourdomain.com/success",
  "callbackUrl": "https://yourdomain.com/payment-callback",
  "clientEmail": "customer@example.com",
  "paymentDescription": "Paiement pour la commande #12345"
}

---

Explication des devises et des taux de conversion

Devises prises en charge :

Papi prend en charge les devises suivantes pour les paiements :

• MGA (Ariary Malgache)
• EUR (Euro)

Vous pouvez choisir la devise à utiliser en la spécifiant dans le champ change.currency du payload.

Champ de taux de conversion :

• Le champ rate spécifie le taux de conversion pour la devise sélectionnée.
• Le commerçant et son développeur (vous) sont responsables de fournir le taux de conversion à utiliser pour le paiement.
  • Par exemple, si vous souhaitez facturer le client en EUR, et que votre taux de conversion est de 4800 MGA pour 1 EUR, alors rate doit être défini sur 4800.
  • Pour les paiements en MGA, le rate est généralement défini sur 1, car aucune conversion n'est nécessaire.

Exemple d'utilisation :

• Si le montant du paiement est 500 EUR, et que le taux de conversion est 4800 MGA, le total en MGA serait 500 * 4800 = 2 400 000 MGA.
  Le paiement sera traité en conséquence à l'aide du taux spécifié.

En permettant au commerçant de définir le taux, Papi offre une flexibilité pour gérer les conversions de devises tout en garantissant que le processus de paiement s'aligne sur les besoins de l'entreprise.

---

---

Explication des champs du payload :

Champ	Type	Description
amount	number	Le montant du paiement dans la devise spécifiée.
change.currency	string	La devise dans laquelle le montant doit être converti (ex. : EUR, MGA).
change.rate	number	Le taux de conversion appliqué à la devise.
failureUrl	string	L'URL de la page d'échec créée précédemment.
successUrl	string	L'URL de la page de succès créée précédemment.
callbackUrl	string	L'URL de l'API de callback mise en œuvre.
clientEmail	string	Adresse email du client qui initie le paiement.
paymentDescription	string	Une description courte de ce pour quoi le paiement est effectué.

---

Here is the translated section for Steps 4 and 5 added to the markdown, ensuring all details are preserved:

---

Étape 4 : Envoyez la requête POST pour récupérer le lien de paiement

Ce que vous devez faire :

1. URL : Envoyez une requête POST à /clients/payment-form.
2. En-têtes : Incluez les en-têtes Content-Type et AuthentificationKey.
3. Corps : Utilisez la charge utile appropriée (par exemple, MGA ou EUR) selon votre cas d'utilisation.

Exemple de réponse :

{
  "data": {
    "token": "unique-transaction-token",
    "amount": "transaction-amount-id",
    "url": "https://payment-page-url.com"
  }
}

Champs de la réponse :

Champ	Type	Description
token	string	Un jeton unique généré pour la transaction, utilisé pour identifier la session de paiement.
amount	string	Un montant de référence ou un identifiant utilisé dans la transaction.
url	string	L'URL où le client sera redirigé pour terminer le paiement.

En suivant ces étapes, vous pouvez vous assurer que votre intégration est fluide et que vos clients bénéficient d'une expérience de paiement optimale. N'oubliez pas de tout tester dans un environnement Sandbox avant de passer en production.

---

Étape 5 : Redirigez l'utilisateur vers l'URL de paiement

Une fois que vous avez reçu le lien de paiement dans la réponse de Papi, la dernière étape consiste à rediriger l'utilisateur vers cette URL pour qu'il puisse terminer le paiement.

Ce que vous devez faire :

1. Extraire le champ url de la réponse reçue à l'Étape 4. Cette URL est la page de paiement sécurisée générée par Papi pour la transaction.
2. Redirigez l'utilisateur vers cette URL à l'aide du mécanisme de redirection de votre application (par exemple, une redirection HTTP dans une application web ou l'ouverture d'un onglet de navigateur dans une application mobile).

Exemple de réponse de Papi :

{
  "data": {
    "token": "unique-transaction-token",
    "amount": "transaction-amount-id",
    "url": "https://payment-page-url.com"
  }
}

Explication des champs :

Champ	Description
url	C'est la page de paiement où le client terminera la transaction. Vous devez rediriger l'utilisateur vers ce lien.

---

En suivant les cinq étapes décrites dans ce guide, vous avez mis en œuvre un flux de paiement complet en utilisant Papi. Cela comprend la configuration des pages de redirection, la création d'une API de callback pour gérer les notifications de paiement, la préparation et l'envoi de la requête pour générer un lien de paiement, et la redirection de l'utilisateur vers la page de paiement.

---