EKOLOPAY Collect API

EKOLOPAY Collect API est l'API est de facturation via Mobile Money

Procédure d'intégration
Prérequis d'intégration

Pour intégrer EkoloPay Collect API 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
  • 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


Description des API
5 endpoints et un callback sont mis à votre disposition pour communiquer avec la plateforme.
API de base : https://ekolopay.com/api/v2/collects

Tout appel aux services de l'API peut renvoyer soit un code status 500 en cas d'erreur ou 200 en cas de succès. Ci-dessous la structure des réponses de la requête selon les cas.

En cas d'erreur
// Http status code : 500
{
    "code" : 0,
    "reason" : string, // Code erreur
    "message" : string // Description du message associé au code erreur
}
En cas de succès
// Http status code : 200
{
    "code" : 200,
    "data" : [] | {} // Données de la réponse
}
NOTEZ BIEN

Pour tout appel aux services de l'API, il est indispensable de toujours :

  • Envoyer les identifiant du client de l'API pour chaque
  • Vérifier la disponibilité du service (erreur si indisponible), au cas où le service serait indisponible, la réponse du serveur est présentée dans le tableau ci-dessous.
Identifiant du client de l'API
Clé Valeur Description Lieu
api_client demo L'identifiant de l'API Paramètre
X-EkoloPay-API-Key 054e9a59-ab57-4e9a-940d-97e6b940d875 La clé secrete de l'API Header
En cas d'erreur d'indisponibilité
// Http status code : 500
{
    "code" : 0,
    "message" : "Service indisponible",
    "reason" : "UNAVAILABLE_SERVICE"
}

Liste exhaustive des endpoints
  1. Vérifier si un compte momo est actif
    GET : /account-holder/{number}/isActive
    QueryParam
    Clé Valeur Type Description
    number 066304925 int Numéro mobile money à vérifier
    Données de la réponse cas de succès 
    {
    "isActive" : bool
}

    ### Http client

#code...

$url = "https://ekolopay.com/api/v2/collects/account-holder/066304925/isActive?api_client=demo";
try {
    $request = HttpClient::create()->request("GET", $url, [
        "headers" => [
            "X-EkoloPay-API-Key" => "054e9a59-ab57-4e9a-940d-97e6b940d875",
        ]
    ]);
    if ($request->getStatusCode() === 200) {
        return $request->toArray();
    }
} catch (Exception $e){}

#code...
  2. Récupérer les informations d'un compte momo
    GET : /account-holder/{number}/info
    QueryParam
    Clé Valeur Type Description
    number 066304925 int Numéro mobile money sur lequel récupérer les information (nom et prénom)
    Données de la réponse cas de succès 
    {
    "firstname" : string,
    "name" : string
}

    ### Http client

#code...

$url = "https://ekolopay.com/api/v2/collects/account-holder/066304925/info?api_client=demo";
try {
    $request = HttpClient::create()->request("GET", $url, [
        "headers" => [
            "X-EkoloPay-API-Key" => "054e9a59-ab57-4e9a-940d-97e6b940d875",
        ]
    ]);
    if ($request->getStatusCode() === 200) {
        return $request->toArray();
    }
} catch (Exception $e){}

#code...
  3. Faire une demande de paiment
    POST : /
    Body : x-www-form-urlencoded
    Clé Valeur Type Description
    amount 150 int Montant
    number 066304925 int Numéro mobile money sur lequel faire une demande de paiement
    Données de la réponse cas de succès 
    {
    "reference" : string
    "amount" : int,
    "currency" : string,
    "status" : string,
    "number" : string
}
    Notez bien
    Dans la réponse de la demande de paiement le champ status est toujours en PENDING. Cependant pour s'assurer du paiement vous devez traiter les cas selon les environnements suivants :

    Toutesfois, il est beaucoup plus judicieux de vérifier (cf 4. Vérifier ou Récupérer un paiement) le paiement au cas où le callback (cf 6. Appel de votre callback) serait appélé avec un retard. 

    ### Http client

#code...

$url = "https://ekolopay.com/api/v2/collects/?api_client=demo";
try {
    $request = HttpClient::create()->request("POST", $url, [
        "headers" => [
            "X-EkoloPay-API-Key" => "054e9a59-ab57-4e9a-940d-97e6b940d875",
        ],
        "body" => [
            "number" => "066304925",
            "amount" => 150,
        ]
    ]);
    if ($request->getStatusCode() === 200) {
        return $request->toArray();
    }
} catch (Exception $e){}

#code...
  4. Vérifier ou Récupérer un paiement
    GET : /{reference}
    QueryParam
    Clé Valeur Type Description
    reference 054e9a59-ab57-4e9a-940d-97e6b940d875 string La référence du paiement
    Données de la réponse cas de succès 
    {
    "reference" : string,
    "amount" : int,
    "currency" : string,
    "date" : string,
    "isTransactionSuccess" : bool,
    "status" : string,
    "client" : {
        "firstname" : string,
        "name" : string,
        "number" : string
    }
}

    ### Http client

#code...

$url = "https://ekolopay.com/api/v2/collects/054e9a59-ab57-4e9a-940d-97e6b940d875?api_client=demo";
try {
    $request = HttpClient::create()->request("GET", $url, [
        "headers" => [
            "X-EkoloPay-API-Key" => "054e9a59-ab57-4e9a-940d-97e6b940d875",
        ]
    ]);
    if ($request->getStatusCode() === 200) {
        return $request->toArray();
    }
} catch (Exception $e){}

#code...
  5. Liste des paiements
    Ce endpoint permet de lister une collection de paiement.
    Le max de paiement qui peut être retourné est de 500, et par défaut la limite est de 50.
    GET : /
    QueryParam
    Clé Valeur Type Description
    limit 50 int Le nombre max de paiement à retourner
    period today | this_week | this_month | last_month | this_last_twelve_months | this_year | last_year string Une constante qui définie une date de début et de fin.
    Pas besoin de l'utiliser si les paramètres start et end sont déjà utilisés dans la requête.
    start 2023-01-01 11:30 string La date de début, format "Y-m-d H:i:s"
    end 2024-01-01 23:59 string La date de fin, format "Y-m-d H:i:s"
    Notez bien

    Les paramètres start et end sont toujours utilisés ensemble. Dès lors qu'ils sont utilisés, on a plus besoin du paramètre period.
    Le paramètre period sera prioritaire s'il arrivait qu'il soit utilisé avec les deux autres.

    Description de la valeur du paramètre period
    Valeur Description
    today Aujourd'hui
    this_week La semaine en cours
    this_month Le mois en cours
    last_month Le mois dernier
    this_last_twelve_months Les 12 derniers mois
    this_year Cette année
    last_year L'année dernière
    Données de la réponse cas de succès 
    {
    "collections" : [
        {...},
        {
            "reference" : string,
            "amount" : int,
            "currency" : string,
            "date" : string,
            "isTransactionSuccess" : bool,
            "status" : string,
            "client" : {
                "firstname" : string,
                "name" : string,
                "number" : string
            }
        },
        {...}
    ]
    "filters" : {
        "period" : {
            "start" : string,
            "end" : string
        },
        "limit" : int
    }
}

    ### Http client

#code...
/**
* QueryParam pour rechercher selon les clés :
* 1) &period=this_week --> pour une période
* 2) &start=2023-01-01+11%3A30&end=2024-01-01+23%3A59 --> pour (start='2023-01-01 11:30' & end='2024-01-01 23:59')
*/
$url = "https://ekolopay.com/api/v2/collects/?api_client=demo&limit=25";

try {
    $request = HttpClient::create()->request("GET", $url, [
        "headers" => [
            "X-EkoloPay-API-Key" => "054e9a59-ab57-4e9a-940d-97e6b940d875",
        ]
    ]);
    if ($request->getStatusCode() === 200) {
        return $request->toArray();
    }
} catch (Exception $e){}

#code...
  6. 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
    reference 054e9a59-ab57-4e9a-940d-97e6b940d875 string La référence du paiement
    isTransactionSuccess true | false boolean true si le paiement est effectué, sinon false
    status INITIATED | SUCCESSFUL | PENDING | FAILED | REJECTED | TIMEOUT | INSUFFICIENT_FUNDS | OPERATOR_ERROR string Le statut du paiement
    message string Un text clair lié au statut

Description des valeurs du champ status
status Description
INITIATED Session initiée
SUCCESSFUL Paiement réussi
PENDING Le paiement en cours ou en attente de validation
FAILED Le paiement a échoué
REJECTED Le paiement est rejeté
TIMEOUT Le temps d'attente de validation du paiement est dépassé
INSUFFICIENT_FUNDS Le solde de compte est insuffisant
OPERATOR_ERROR Une erreur interne chez l'opérateur de paiement
Valeur possible du couple des champs (status & isTransactionSuccess) et une explication
status isTransactionSuccess Explication
SUCCESSFUL true Le paiement est réussi
INITIATED | PENDING | FAILED | REJECTED | TIMEOUT | INSUFFICIENT_FUNDS | OPERATOR_ERROR false Le paiement n'est pas passé