Documentation

Introduction

Cette page vous aidera à démarrer avec PayExpresse. Vous serez opérationnel en un tour main!

Généralité

Notre page de documentation vous donne toutes les informations dont vous pourriez avoir besoin pour utiliser nos API.

Les SDK pour chaque plateforme sont ajoutés progressivement et mis à jour régulièrement. Ils sont repartis en deux catégories:

  • Les SDK coté client pour Navigateur web, Android et Ios et les SDK coté serveur PHP, RUBY, PYTHON, NODEJS qui permettent d'interagir avec les serveurs PayExpresse.
  • CORS n'est pas activé dans les serveurs PayExpresse, et vos clés API doivent rester confidentielles, d'où la nécessité de passer par un controller coté serveur pour faire une demande de token

Dépôt officiel

Tous les fichiers sont disponibles dans ce dépôt git: https://github.com/payexpresse

L'URL de base

L'URL de base de l'API est:


 URL_BASE :  "https://payexpresse.com/api"
        

Clés API

Une clé d'interface de programmation d'applications (clé API) est un code utilisé par les programmes informatiques qui utilisent nos API.

Pour utiliser l'API de PayExpresse API, vous devez vous inscrire sur la plateforme. Une fois dans le Dashbord, cliquer sur le menu Paramètres, puis sur API pour récupérer vos clés. Vous avez aussi la possibilité de les régénérer.

Toutes les requêtes envoyées par le site marchand vers notre API doivent comporter obligatoirement la clé API et la clé secrète dans les headers de la requête :

   SHELL
  # you can pass the correct header for each request in this way
  curl "api_endpoint_here"
  -H "API_KEY: 1afac858d4fa5ec74e3e3734c3829793eb6bd5f4602c84ac4a5069369812915e"
  -H "API_SECRET: 96bc36c11560f2151c4b43eee310cefabc2e9e9000f7e315c3ca3d279e3f98ac"
        

Paiement

Paiement Avec Redirection

Le Paiement avec Redirection vous permet de rediriger votre client vers notre plateforme afin qu'il puisse achever le processus de paiement.
Le traitement avec redirection est idéal pour les marchands qui désirent déléguer l’hébergement de la page de paiement à PayExpresse. Lors du processus de paiement, le client est redirigé vers une page de PayExpresse pour saisir les informations de paiement.
Les clients peuvent choisir de payer à partir d'une variété d'options de paiement disponibles sur notre plateforme.

Demande de paiement

La demande de paiement définit une expérience utilisateur cohérente entre les méthodes de paiement, les systèmes de paiement, les plateformes et les commerçants.

Pour que le client puisse faire un paiement, le site marchand doit d'abord adresser une demande de paiement à notre API. Celui-ci va lui envoyer un token de 20 octets qui sera l'identifiant de la demande.


    POST "/payment/request-payment"
        
Paramètres Défaut Obligatoire Description
item_name NULL OUI Nom du produit
item_price NULL OUI Prix de la commande
ref_command NULL OUI Une référence de commande générée par le site marchand doit être unique pour chaque demande de paiement.
command_name "" OUI Description de la commande
currency XOF NON L'une de ses devises: ['XOF', 'EUR', 'USD', 'CAD','GBP','MAD']
env prod NON Environnement ['test', 'prod']
ipn_url Paramètre global compte NON URL IPN (voir section IPN pour plus de détails). Si elle n'est pas fournie, on utilisera la valeur définie dans les paramètres globaux du site marchand. Seules les URL en HTTPS sont acceptées.
success_url Paramètre global compte NON URL vers laquelle le client est redirigé après le paiement. Si elle n'est pas fournie, on utilisera la valeur définie dans les paramètres globaux du site marchand.
cancel_url Paramètre global compte NON URL vers laquelle le client est redirigé quand il annule le paiement. Si elle n'est pas fournie, on utilisera la valeur définie dans les paramètres globaux du site marchand.
custom_field NULL NON Donnée additionnelle qui sera envoyée au client vers l'URL IPN. Elle doit être une chaine de caractères encodés en JSON.

> Paiment Coté Serveur

CORS n'est pas activé dans les serveurs PayExpresse, et vos clés API doivent rester confidentielles, d’où la nécessité de passer par un Controller coté serveur pour faire une demande de token.

Votre application devrait disposer d'un Controller Web qui se chargera de faire la demande de token aux serveurs de PayExpresse.

NODE JS


    let paymentRequestUrl = "https://payexpresse.com/api/payment/request-payment";
    let fetch = require('node-fetch');// http client
    let params = {
    item_name:"Iphone 7",
    item_price:"560000",
    currency:"XOF",
    ref_command:"HBZZYZVUZZZV",
    command_name:"Paiement Iphone 7 Gold via PayExpresse",
    env:"test",
    ipn_url:"https://domaine.com/ipn",
    success_url:"https://domaine.com/success",
    cancel_url:"https://domaine.com/cancel",
    custom_field:JSON.stringify({
       custom_fiel1:"value_1",
       custom_fiel2:"value_2",
    })
    };

    let headers = {
    Accept: "application/json",
    'Content-Type': "application/json",
    API_KEY:"1afac858d4fa5ec74e3e3734c3829793eb6bd5f4602c84ac4a5069369812915e",
    API_SECRET:"96bc36c11560f2151c4b43eee310cefabc2e9e9000f7e315c3ca3d279e3f98ac",
    };

    fetch(paymentRequestUrl, {
    method:'POST',
    body:JSON.stringify(params),
    headers: headers
    })
    .then(function (response) {
    return response.json()
    })
    .then(function (jsonResponse) {
    console.log(jsonResponse)
    /*
    {
        "success":1,
        "redirect_url":"https://preview.payexpresse.com/payment/checkout/98b1c97af00c8b2a92f2",
      token:"98b1c97af00c8b2a92f2"}

    */
    })

PHP


    function post($url, $data = [], $header = [])
    {
        $strPostField = http_build_query($data);

        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
        curl_setopt($ch, CURLOPT_POSTFIELDS, $strPostField);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
        curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
        curl_setopt($ch, CURLOPT_HTTPHEADER, array_merge($header, [
            'Content-Type: application/x-www-form-urlencoded;charset=utf-8',
            'Content-Length: ' . mb_strlen($strPostField)
        ]));

        return curl_exec($ch);
    }

    $postFields = array(
            "item_name"    =>$res['name'],
        "item_price"   => $total,
        "currency"     => "xof",
        "ref_command"  =>  $ref_commande,
        "command_name" =>  $commande,
        "env"          =>  $environnement,
        "success_url"  =>  $success_url,
        "ipn_url"		   =>  $ipn_url,
        "cancel_url"   =>  $success_url,
        "custom_field" =>   $customfield
    );

    $result = post('https://payexpress.com/api/payment/request-payment', $postfields, [
        "API_KEY: ".$api_key,
        "API_SECRET: ".$api_secret
    ]);

    $jsonResponse = json_decode($result, true);

    require 'PayExpresse.php';

    $item = ....;//object
    const BASE_URL  = 'https://sample.domaine.com';
    $jsonResponse = (new PayExpresse($apiKey, $apiSecret))->setQuery([
            'item_name' => $item->name,
            'item_price' => $item->price,
            'command_name' => "Paiement {$item->name} Gold via PayExpresse",
        ])->setCustomeField([
            'item_id' => $id,
            'time_command' => time(),
            'ip_user' => $_SERVER['REMOTE_ADDR'],
            'lang' => $_SERVER['HTTP_ACCEPT_LANGUAGE']
        ])
            ->setTestMode(true)
            ->setCurrency($item->currency)
            ->setRefCommand(uniqid())
            ->setNotificationUrl([
                'ipn_url' => BASE_URL.'/ipn.php', //only https
                'success_url' => BASE_URL.'/index.php?state=success&id='.$id,
                'cancel_url' =>   BASE_URL.'/index.php?state=cancel&id='.$id
            ])->send();

Si tous les paramètres ont été correctement fournis, l'API PayExpresse renverra la réponse suivante :

    {
    "success": 1,
    "token": "XJJDKS8S8SHNS2",
    "redirect_url": "https://payexpresse.com/payment/checkout/XJJDKS8S8SHNS2",
    }

Paiment Coté Client

SDK Web


        
Présentation Mode
PayExpresse.OPEN_IN_POPUP
PayExpresse.OPEN_IN_NEW_TAB
PayExpresse.OPEN_IN_SAME_TAB
PayExpresse.DO_NOTHING

La méthode .send peut prendre un objet pour redéfinir le thème de la page de paiement.

.send({
            pageBackgroundRadianStart:'#0178bc',
            pageBackgroundRadianEnd:'#00bdda',
            pageTextPrimaryColor:'#333',
            paymentFormBackground:'#fff',
            navControlNextBackgroundRadianStart:'#608d93',
            navControlNextBackgroundRadianEnd:'#28314e',
            navControlCancelBackgroundRadianStar:'#28314e',
            navControlCancelBackgroundRadianEnd:'#608d93',
            navControlTextColor:'#fff',
            paymentListItemTextColor:'#555',
            paymentListItemSelectedBackground:'#eee',
            commingIconBackgroundRadianStart:'#0178bc',
            commingIconBackgroundRadianEnd:'#00bdda',
            commingIconTextColor:'#fff',
            formInputBackgroundColor:'#eff1f2',
            formInputBorderTopColor:'#e3e7eb',
            formInputBorderLeftColor:'#7c7c7c',
            totalIconBackgroundRadianStart:'#0178bc',
            totalIconBackgroundRadianEnd:'#00bdda',
            formLabelTextColor:'#292b2c',
            alertDialogTextColor:'#333',
            alertDialogConfirmButtonBackgroundColor:'#0178bc',
            alertDialogConfirmButtonTextColor:'#fff'
        });

Paiment mobile

Android

Vous devez tout d'abord inclure la librairie PayExpresse disponible sous format .aar dans votre projet.
La librairie est disponible ici :

    LINK : "https://github.com/sidsonAidson/payexpresse-sdk/raw/master/PayExpress-Android-Sdk/payexpresse-sdk-release.aar"

Ensuite vous devez importer ces deux classes dans votre activité.

    import sdk.payexpresse.com.PCallback;
    import sdk.payexpresse.com.PayExpresse;

Ensuite, il reste plus qu’à invoquer la classe.

    Button button = (Button) this.findViewById(R.id.buy);
        button.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View v) {
                Log.i("click", "click on button");
                HashMap params = new HashMap<>();
                params.put("item_id", 2);
                new PayExpresse(MainActivity.this)
                        .setRequestTokenUrl("https://sample.payexpresse.com/paiement.php")
                        .setParams(params)
                        .setCallback(new PCallback() {
                            @Override
                            public void onResult(Result result) {
                                if(result == Result.SUCCESS)
                                {
                                    Toast.makeText(MainActivity.this, "Payment Perform", Toast.LENGTH_SHORT).show();
                                }
                                else if(result == Result.CANCEL)
                                {
                                    Toast.makeText(MainActivity.this, "You canceled the payment", Toast.LENGTH_SHORT).show();
                                }
                                else if(result == Result.ERROR)
                                {
                                    Toast.makeText(MainActivity.this, "Error during payment", Toast.LENGTH_SHORT).show();
                                }
                            }
                        })
                        .send();
            }
        });

IPN

Cette section est relative à tout ce qui concerne les notifications de paiement.

Fonctionnement

Lorsqu'un client finalise un paiement ou qu'un paiement est annulé, PayExpresse envoie une notification à votre serveur à l'URL IPN que vous avez indiquée.

Cette notification comporte toutes les informations pertinentes de paiement de votre client que vous avez transmises lors de la demande de token de paiement ainsi que le type d'évènement.

À la réception d’une notification, votre serveur devra vérifier si la requête provient bien de PayExpresse en comparant le hash en sha256 de sa clé API et clé secrète avec les deux clés que nous lui avons envoyées dans la requête.

Voici la liste des paramètres de la notification :

Paramètres Description
type_event Le type d'évènement qui a déclenché la requête vers l'URL IPN. L'une de ses valeurs possible. ['sale_complete', 'sale_canceled']
client_phone Le numéro de téléphone du client
payment_method La méthode de paiement ['Carte Bancaire', 'PayPal', 'Orange Money', 'Joni Joni', 'Wari','Poste Cash']
item_name Nom du produit
item_price Prix de la commande
ref_command La référence de commande générée par le site marchand.
command_name Description de la commande
currency L'une de ses devises: ['XOF', 'EUR', 'USD', 'CAD','GBP','MAD']
env Environnement ['test', 'prod']
custom_field Donnée additionnelle envoyée aux serveurs de PayExpresse lors de la demande de token
token Le token de paiement
api_key_sha256 La clé API du site marchand hachée avec l'algorithme sha256
api_secret_sha256 La clé secrète du site marchand hachée avec l'algorithme sha256

Utilisation de la Notification de Paiement

NODEJS/EXPRESSEJS

    function SHA256Encrypt(password) {
        let crypto = require('crypto');
        let sha256 = crypto.createHash('sha256');
        sha256.update(password);
        return sha256.digest('hex');
    }

    app.post('/my-ipn', (req, res) => {
        let type_event = req.body.type_event;
        let custom_field = JSON.parse(req.body.custom_field);
        let ref_command = req.body.ref_command;
        let item_name = req.body.item_name;
        let item_price = req.body.item_price;
        let devise = req.body.devise;
        let command_name = req.body.command_name;
        let env = req.body.env;
        let token = req.body.token;
        let api_key_sha256 = req.body.api_key_sha256;
        let api_secret_sha256 = req.body.api_secret_sha256;

        let my_api_key = process.env['API_KEY'];
        let my_api_secret = process.env['API_SECRET'];

        if(SHA256Encrypt(my_api_secret) === api_secret_sha256 && SHA256Encrypt(my_api_key) === api_key_sha256)
        {
            //from PayExpresse
        }
        else{
            //not from PayExpresse
        }
    });

PHP/LARAVEL

    Route::post('/my-ipn', function () {
        $type_event = Input::get('type_event');
        $custom_field = json_decode(Input::get('custom_field'), true);
        $ref_command = Input::get('ref_command');
        $item_name = Input::get('item_name');
        $item_price = Input::get('item_price');
        $devise = Input::get('devise');
        $command_name = Input::get('command_name');
        $env = Input::get('env');
        $token = Input::get('token');
        $api_key_sha256 = Input::get('api_key_sha256');
        $api_secret_sha256 = Input::get('api_secret_sha256');

        $my_api_key = env('API_KEY');
        $my_api_secret = env('API_SECRET');

        if(hash('sha256', $my_api_secret) === $api_secret_sha256 && hash('sha256', $my_api_key) === $api_key_sha256)
        {
            //from PayExpresse
        }
        else{
            //not from PayExpresse
        }
    });

PYTHON/DJANGO

    import hashlib
    def ipn(request):
    if request.method == "POST":
    inputtxt = request.POST['getrow']
    api_key_sha256 = request.POST['api_key_sha256'];
    api_secret_sha256 = request.POST['api_secret_sha256']
    my_api_secret_sha256 = hashlib.sha256(b'here my api secret').hexdigest()
    my_api_key_sha256 = hashlib.sha256(b'here my api key').hexdigest()
    if my_api_key_sha256 == api_key_sha256 and my_api_secret_sha256 == api_secret_sha256:
      # from payexpress

	return HttpResponse(...)

PHP

    function get($name)
    {
        return !empty($_POST[$name]) ? $_POST[$name] : '';
    }

    $type_event = get('type_event');
    $custom_field = json_decode(get('custom_field'), true);
    $ref_command = get('ref_command');
    $item_name = get('item_name');
    $item_price = get('item_price');
    $devise = get('devise');
    $command_name = get('command_name');
    $env = get('env');
    $token = get('token');
    $api_key_sha256 = get('api_key_sha256');
    $api_secret_sha256 = get('api_secret_sha256');
    $my_api_key = env('API_KEY');
    $my_api_secret = env('API_SECRET');
    if (hash('sha256', $my_api_secret) === $api_secret_sha256 && hash('sha256', $my_api_key) === $api_key_sha256) {
        //from PayExpresse}else{    //not from PayExpresse}
    }