Aller au contenu principal
Version: 1.0.4

Guide de démarrage rapide

Ce guide est conçu pour les développeurs afin de les aider à intégrer Papi dans leur site Web ou application. Suivez ces étapes pour configurer un système de paiement qui fonctionne de manière fluide pour vos clients.

Prérequis​

  1. Votre application est en ligne et prête à accepter les paiements.

  2. Vous avez créé une entrée pour votre application dans Papi (et l'organisation associée). Vous pouvez créer une entrée d'application en visitant la page de gestion des applications de Papi.

  3. Vous avez la clé API de l'application, fournie par Papi.

  4. Choisissez une URL à laquelle Papi doit rediriger après un paiement réussi.

  5. Choisissez une URL à laquelle Papi doit rediriger après un paiement échoué.

  6. Choisissez une URL à fournir à Papi comme point de terminaison, afin que Papi puisse informer votre système du succès ou de l'échec du paiement.

Vue d'ensemble du workflow​

Avant de plonger dans les étapes, voici comment tout cela s'intègre :

  1. Un client passe une commande sur votre site Web.
  2. Vous créez un lien de paiement sécurisé à l'aide de Papi.
  3. Le client est redirigé vers la page de paiement pour finaliser son paiement.
  4. Papi envoie le résultat du paiement à votre système via un point de notification (une URL spéciale sur votre serveur qui traite les mises à jour).
  5. Votre système met à jour le statut de la commande en fonction du succès ou de l'échec du paiement.
  6. Le client voit le résultat sur votre site Web (succès ou échec).

Étape 1 : Générer un lien de paiement​

Pour permettre aux clients de payer, vous devez créer un lien sécurisé qui les dirigera vers une page de paiement. Ce lien inclut le montant du paiement, les informations du client et où notifier votre système du résultat du paiement.

Ce que vous devez faire​

Depuis votre page de paiement, envoyez une requête POST à https://api.papi.mg/clients/payment-form pour demander un lien de paiement à Papi.

Données à envoyer à Papi​

Incluez l'en-tête suivant où <your-application-api-key> est la clé API attribuée à votre application par Papi :

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

Incluez un corps comme celui-ci (pour les paiements 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​

Voici un exemple de code pour générer un lien de paiement en PHP :

<?php
// URL de l'API pour générer un lien de paiement
$apiUrl = "https://api.papi.mg/clients/payment-form";
$apiKey = "Ibonia <your-application-api-key>";

// Données pour le paiement
$data = [
    "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"
];

// Options pour la requête HTTP
$options = [
    "http" => [
        "header" => "Content-Type: application/json\r\nAuthentificationKey: $apiKey\r\n",
        "method" => "POST",
        "content" => json_encode($data),
    ],
];

// Envoyer la requête et obtenir la réponse
$context = stream_context_create($options);
$response = file_get_contents($apiUrl, false, $context);

if ($response !== false) {
    $responseData = json_decode($response, true);
    $paymentLink = $responseData["data"]["url"];
    echo "Lien de paiement : $paymentLink\n";
} else {
    echo "Échec de la génération du lien de paiement.\n";
}
?>

Étape 2 : Rediriger le client vers la page de paiement​

Une fois le lien de paiement généré, votre client doit finaliser le paiement en utilisant ce lien.

Ce que vous devez faire​

  1. Extrayez l'URL de la réponse de l'étape 1.
  2. Redirigez le client vers cette URL.

Données renvoyées par Papi​

{
  "data": {
    "url": "https://api.papi.mg/paymentform/prepayment/...etc..."
  }
}

Exemple​

Voici un exemple montrant comment rediriger le client en PHP :

<?php
// Rediriger vers la page de paiement générée par Papi
header("Location: https://api.papi.mg/paymentform/prepayment/...etc...");
exit();
?>

Étape 3 : Configurer un point de notification​

Après que le client a complété le paiement sur la page de paiement de Papi, Papi doit informer votre système du succès ou de l'échec du paiement. Cela se fait en envoyant des données à un point de notification dans votre application (une URL spéciale sur votre serveur qui reçoit les mises à jour de paiement).

Ce que vous devez faire​

  1. Créez un point de terminaison qui traite la notification de Papi en tant que requête POST.
  2. Enregistrez ce script à l'URL que vous avez donnée à Papi dans l'attribut callbackUrl.

Données renvoyées par Papi​

{
  "description": "Paiement pour la commande #12345",
  "amount": 500.00,
  "transactionId": "abc123def456",
  "status": 200,
  "errorMessage": "",
  "paymentMethod": 2,
  "sender": "customer@example.com"
}
  • status est un code de statut HTTP :
    • 200 si le paiement est un succès.
    • 400 si le paiement est un échec.

Exemple de point de terminaison PHP​

<?php
// Lire les données JSON envoyées par Papi
$data = json_decode(file_get_contents("php://input"), true);

// Extraire les détails importants
$transactionId = $data["transactionId"];
$status = $data["status"];

if ($status == 1) {
    // Paiement réussi
    file_put_contents("log.txt", "Transaction $transactionId : SUCCÈS\n", FILE_APPEND);
} else {
    // Paiement échoué
    file_put_contents("log.txt", "Transaction $transactionId : ÉCHEC\n", FILE_APPEND);
}

http_response_code(200); // Informer Papi que la mise à jour a été reçue
?>

Étape 4 : Créer des pages pour les résultats de paiement​

Après l'affichage par Papi des résultats (succès ou échec), l'utilisateur est redirigé vers votre site. Voici ce que vous pouvez faire :

  1. Utilisez une URL unique pour renvoyer l'utilisateur.
  2. Ou créez des pages distinctes :
    • Une pour les paiements réussis.
    • Une pour les paiements échoués.