EKOLOPAY Collect (Passerelle de facturation en ligne)

EKOLOPAY Collect est une passerelle de facturation des services en ligne via le Mobile Money

Dernière mise à jour le 01 juillet 2023 (cliquer ici pour voir l'historique des mises à jour)
Procédure d'intégration
Prérequis d'intégration

Pour intégrer EkoloPay Collect sur votre site, il est impératif de s’enregistrer en tant que marchand.
Un compte marchand vous sera attribué et vous permettra de :

  • Obtenir un client ID et client secret : Données indispensable pour communiquer avec EKOLOPAY
  • Consulter toutes vos transactions
  • Faire des virements de votre solde vers le compte mobile money de votre choix
Le compte Marchand
Le compte marchand est associé aux informations suivantes :
  • Domain Origin : Le nom de domaine du site internet qui est à l’origine de l’appel des API
  • Redirect URL : Page vers laquelle rediriger le client une fois la transaction effectuée (réussie ou pas)
  • Callback URL : Votre point d’entré API par lequel EKOLOPAY enverra des données sur le statut de la transaction
Une fois votre compte enregistré et validé, vous aurez accès aux clés API :
  • API Client : L’identifiant de votre API
  • Secret key : La clé secrète utilisé pour communiquer avec l’API

Parcours de facturation et vue sur la communication entre les plateformes
schema
  1. Le client arrive sur le site marchand (votre site), passe la commande pour payer son article
  2. Le site marchand redirige le client vers EKOLOPAY (plateforme de paiement)
  3. EKOLOPAY présente le formulaire de paiement, le client saisit son numéro mobile money et valide
  4. EKOLOPAY traite le paiement, et redirige vers le site marchand
  5. Le site marchand affiche au client un message selon le statut de paiement envoyé par EKOLOPAY

Processus d'exécution
ekolopay-sequence

Description des API
3 points d'entré et un callback sont mis à votre disposition pour communiquer avec la plateforme.
API de base : https://ekolopay.com/api/v1/gateway

NOTEZ BIEN

Pour tout appel aux services de l'API, il est indispensable de toujours vérifier la disponibilité du service. Au cas où le service serait indisponible, la réponse du serveur est présentée dans le tableau ci-dessous.

Réponse du serveur
{
    "code" : 0,
    "message" : "Service indisponible",
    "reason" : "UNAVAILABLE_SERVICE"
}


  1. Créer un token d'achat
    Permet de créer un token qui sera associé à la facturation de la commande.
    POST : /purchase-token
    Paramètre de la requette
    Clé Valeur Description
    api_client demo L'identifiant de l'API
    Body : x-www-form-urlencoded
    Clé Valeur Type Description
    amount 150000 int Le montant de la commande
    product
    {
      "amount" : "Montant de la commande",
      "label" : "Libellé de la commande",
      "details" : "Détails de la commande"
    }
    
    
    JSON Information sur la commande
    customer
    {
      "uuid" : "UUID du client",
      "name" : "Nom du client",
      "phone" : "Téléphone du client",
    }
    
    
    JSON Information sur le client
    secret_key 054e9a59-ab57-4e9a-940d-97e6b940d875 string Clé secrète
    Réponse du serveur
    Réussie Echoué
    {
      "response" : {
          "API_RESPONSE_CODE" : 200,
          "API_RESPONSE_DATA" : {
               "API_DATA" : {"purchaseToken" : "string"}
          }
      }
    }
    
    
    {
      "response" : {
          "API_RESPONSE_CODE" : 0,
          "API_RESPONSE_DATA" : {
              "clearMessage" : "string"
          }
      }
    }
    Exemple
    ### Http client
    
    #code...
    
    $product = [
      "label" => "Achat d'un Iphone S",
      "amount" => 150000,
      "details" => "Iphone S, 32 GB, Gris...",
    ];
    $customer = [
        "uuid" => "d34f747e-8876-428c-9466-becf59177bde",
        "name" => "Kanza"
        "phone" => "066304925"
    ];
    $url = "https://ekolopay.com/api/v1/gateway/purchase-token?api_client=demo";
    try {
        $request = HttpClient::create()->request("POST", $url, [
            "body" => [
                "customer" => json_encode($customer),
                "product" => json_encode($product),
                "amount" => 150000,
                "secret_key" => "054e9a59-ab57-4e9a-940d-97e6b940d875"
            ]
        ]);
        if($request->getStatusCode() === 200){
            return $request->toArray()['response'];
        }
    } catch (Exception $e){}
    
    #code...
    ### Http client
    
    #code...
    
    OutputStreamWriter dataOutputStream = null; BufferedReader reader = null; HttpURLConnection uc = null;
    JsonObject customer = new JsonObject();
    customer.addProperty("uuid", "d34f747e-8876-428c-9466-becf59177bde");
    customer.addProperty("name", "Kanza");
    customer.addProperty("phone", "066304925");
    
    JsonObject product = new JsonObject();
    product.addProperty("label", "066304925");
    product.addProperty("amount", 150000);
    product.addProperty("details", "Iphone S, 32 GB, Gris...");
    
    ArrayMap< String, String> parameters = new ArrayMap<>();
    parameters.put("customer", customer.toString());
    parameters.put("product", product.toString());
    parameters.put("amount", 150000);
    parameters.put("secret_key", "054e9a59-ab57-4e9a-940d-97e6b940d875");
    String route = "https://ekolopay.com/api/v1/gateway/purchase-token?api_client=demo";
    
    try {
    
        URL source = new URL(route);
        uc = (HttpURLConnection) source.openConnection();
        uc.setRequestMethod("POST");
        uc.setDoOutput(true);
        dataOutputStream = new OutputStreamWriter(uc.getOutputStream());
    
        List< String> list = new ArrayList<>(parameters.keySet());
        if(uc.getDoOutput() && !list.isEmpty()) {
            StringBuilder params = new StringBuilder();
            for (String key : list) {
                params.append(URLEncoder.encode(key, "UTF-8"));
                params.append("=");
                params.append(URLEncoder.encode(parameters.get(key), "UTF-8"));
                params.append("&");
            }
    
            dataOutputStream.write(params.toString()); dataOutputStream.flush();
        }
    
        if(uc.getResponseCode() == 200){
            String line; BufferedReader reader = new BufferedReader(new InputStreamReader(uc.getInputStream()));
            StringBuilder response = new StringBuilder();
            while ((line = reader.readLine()) != null){ response.append(line); }
            return (new JsonStreamParser(response)).next().getAsJsonObject().get("response");
        }
        return null;
    } catch(Exception e) {}
    
    #code...
    
  2. Rediriger vers la plateforme de paiement
    Une fois le token d'achat créé, vous devez rediriger vers l'URL ci-dessous.
    User-Agent : https://ekolopay.com/purchase-product/{purchaseToken}
  3. Appel de votre callback
    Une fois l'opération de paiement est à terme, la plateforme EKOLOPAY fera un appel sur votre API callback pour envoyer des données sur l'état du paiement. Le tableau ci-dessous présente les données qui seront envoyées sur votre callback.
    POST : https://demosa.com/callback
    Body : x-www-form-urlencoded
    Clé Valeur Type Description
    purchaseToken string Le token d'achat en question
    paymentSuccessful true | false boolean true si le paiement est effectué, sinon false
    status FAILED | REJECTED | TIMEOUT | SUCCESS | SUCCESSFUL string Le statut du paiement
    message string Un text claire lié au statut
    Description des clés (status, message et paymentSuccessful) et la correspondance des valeurs
    status message paymentSuccessful Catégorie
    SUCCESS | SUCCESSFUL Paiement réussi. true Succès
    FAILED Le paiement a échoué. false Echec
    REJECTED Le paiement est rejeté. false Echec
    TIMEOUT Le temps d'attente de paiement est dépassé. false Echec
  4. Vérifier le paiement
    Après appel de votre callback URL, il est idéal de vérifier et de s'assurer que le paiement de la commande a réussi ou pas.
    Cette vérification peut aussi se faire lors de la redirection vers votre Redirect URL(https://demosa.com/payment-status).
    POST : /check-payment
    Paramètre de la requette
    Clé Valeur Description
    api_client demo L'identifiant de l'API
    Body : x-www-form-urlencoded
    Clé Valeur Type Description
    purchaseToken string Le token d'achat
    secret_key 054e9a59-ab57-4e9a-940d-97e6b940d875 string Clé secrète
    Réponse du serveur
    Réussie Echoué
    {
        "response" : {
            "API_RESPONSE_CODE" : 200,
            "API_RESPONSE_DATA" : {
                "API_DATA" : {"payment_successful" : "boolean"}
            }
        }
    }
    
    
    {
        "response" : {
            "API_RESPONSE_CODE" : 0,
            "API_RESPONSE_DATA" : {
                "clearMessage" : "string"
            }
        }
    }
    
    
    Exemple
    ### Http client
    
    #code...
    
    $url = "https://ekolopay.com/api/v1/gateway/check-payment?api_client=demo";
    try {
        $request = HttpClient::create()->request("POST", $url, [
            "body" => [
                "purchaseToken" => "940d4e9aab5797e6055e1259b84a9875",
                "secret_key" => "054e9a59-ab57-4e9a-940d-97e6b940d875"
            ]
        ]);
        if($request->getStatusCode() === 200){
            return $request->toArray()['response'];
        }
    } catch (Exception $e){}
    
    #code...
    ### Http client
    
    #code...
    
    OutputStreamWriter dataOutputStream = null; BufferedReader reader = null; HttpURLConnection uc = null;
    ArrayMap< String, String> parameters = new ArrayMap<>();
    parameters.put("purchaseToken", "940d4e9aab5797e6055e1259b84a9875");
    parameters.put("secret_key", "054e9a59-ab57-4e9a-940d-97e6b940d875");
    
    String route = "https://ekolopay.com/api/v1/gateway/purchase-token?api_client=demo";
    
    try {
    
        URL source = new URL(route);
        uc = (HttpURLConnection) source.openConnection();
        uc.setRequestMethod("POST");
        uc.setDoOutput(true);
        dataOutputStream = new OutputStreamWriter(uc.getOutputStream());
    
        List< String> list = new ArrayList<>(parameters.keySet());
        if(uc.getDoOutput() && !list.isEmpty()) {
            StringBuilder params = new StringBuilder();
            for (String key : list) {
                params.append(URLEncoder.encode(key, "UTF-8"));
                params.append("=");
                params.append(URLEncoder.encode(parameters.get(key), "UTF-8"));
                params.append("&");
            }
    
            dataOutputStream.write(params.toString()); dataOutputStream.flush();
        }
    
        if(uc.getResponseCode() == 200){
            String line; BufferedReader reader = new BufferedReader(new InputStreamReader(uc.getInputStream()));
            StringBuilder response = new StringBuilder();
            while ((line = reader.readLine()) != null){ response.append(line); }
            return (new JsonStreamParser(response)).next().getAsJsonObject().get("response");
        }
        return null;
    } catch(Exception e) {}
    
    #code...
    

Ci-dessous l'historique des mises à jour de la passerelle de facturation et de sa documentation

  • Ajout du paragraphe NOTER BIEN dans la documentation ci-dessus
    • Spécification de la réponse du serveur destinée à la vérification de la disponibilité de la passerelle lors de chaque appel à ses endpoints

Création de la documentation de la passerelle de facturation EKOLOPAY Collect