Collect Doc | EKOLOPAY

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)

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

Le client arrive sur le site marchand (votre site), passe la commande pour payer son article
Le site marchand redirige le client vers EKOLOPAY (plateforme de paiement)
EKOLOPAY présente le formulaire de paiement, le client saisit son numéro mobile money et valide
EKOLOPAY traite le paiement, et redirige vers le site marchand
Le site marchand affiche au client un message selon le statut de paiement envoyé par EKOLOPAY

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" }`

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" (facultatif), "label" : "Libellé de la commande", "details" : "Détails de la commande" (facultatif) }`	JSON	Information sur la commande
customer	`{ "uuid" : "UUID du client" (facultatif), "name" : "Nom du client" (facultatif), "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é

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" } } }`

{
  "response" : {
      "API_RESPONSE_CODE" : 200,
      "API_RESPONSE_DATA" : {
           "API_DATA" : {"purchaseToken" : "string"}
      }
  }
}

{
  "response" : {
      "API_RESPONSE_CODE" : 0,
      "API_RESPONSE_DATA" : {
          "clearMessage" : "string"
      }
  }
}

Exemple

PHP
JAVA

### 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...

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}

Appel de votre callback
Une fois l'opération de paiement est à terme, la plateforme 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

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é

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" } } }`

{
    "response" : {
        "API_RESPONSE_CODE" : 200,
        "API_RESPONSE_DATA" : {
            "API_DATA" : {"payment_successful" : "boolean"}
        }
    }
}

{
    "response" : {
        "API_RESPONSE_CODE" : 0,
        "API_RESPONSE_DATA" : {
            "clearMessage" : "string"
        }
    }
}

Exemple

PHP
JAVA

### 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...

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 (Passerelle de facturation en ligne)

Procédure d'intégration

Prérequis d'intégration

Parcours de facturation et vue sur la communication entre les plateformes

Processus d'exécution

Description des API

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