API de PaiementCinetPay

L’implémentation technique se résume à 3 étapes:

SDK PHP CinetPay

Etape 1

Pré-requis

Vous devez avoir un compte et un service valide sur CinetPay
Sinon, Veuillez Créer votre compte et votre premier service marchand.
Une fois cela fait, vous devez récupérer votre APIKEY et votre SITE ID dans votre interface une fois connecté avant de continuer votre intégration.

Vous êtes prêts ? c'est parti !

Etape 2

Formulaire de paiement

L’appel à la plateforme de paiement est réalisé via l’envoi d’un formulaire posté en https si vous êtes en production. Ce formulaire contient au minimum les paramètres obligatoires listés ci-dessous ainsi qu’une variable signature unique par formulaire attestant de son authenticité.

Signature

Pour calculer la signature, il est nécessaire de poster (Envoyer les données en POST) exactement les informations ci-dessous dans le tableau à cette page. https://api.cinetpay.com/v1/?method=getSignatureByPost Vous obtiendriez en retour une chaine de caractère la signature de votre paiement en cours que vous devez stocker dans la variable « signature » pour la suite ou un JSON en cas d’erreur.

GetSignature

NB : Le montant doit être un multipe de 5, le montant minimum par devise etant de 100 XAF ou XOF, 0.2 USD et 400 CDF
Vous pouvez obliger le client à utiliser un numéro de téléphone pour effectuer, vous devez ajouter deux éléments dans ce tableau :
cel_phone_num : Numéro de téléphone du payeur (ex : 01020304) cpm_phone_prefixe : Le prefix du payeur (ex : 225)

NB: Ces deux champs sont optionnels, sauf pour les services qui ont été informé par CinetPay.

Exemple de réponse bonne : '95db7a68358e8cb8831db947d8abcfef002af755' Exemple de réponse JSON obtenu en cas d’erreur :


{
    "status": {
        "code": "609",
        "message": "AUTH_NOT_FOUND"
    }
}

NB: Quel que soit la réponse obtenue, il faudra décodercette réponse car cetteréponse est considérée comme un JSON.

Création du Formulaire de paiement

L’URL de la page de paiement est : https://secure.cinetpay.com

postForm

Si vous avez obtenu la signature avec ajoutant les champs (cel_phone_num & cpm_phone_prefixe) alors vous devez ajouter ces deux elements dans le formulaire:
cel_phone_num : Numéro de téléphone du payeur (ex : 01020304) cpm_phone_prefixe : Le prefix du payeur (ex : 225)
Vous pouvez activer le mode debug en ajoutant le champs 'debug' avec comme valeur 1

URL de notification

A la fin d’un paiement, la plateforme de paiement appelle systématiquement l’url de notification serveur renseignée dans le back-office marchand pour le service concerné. Cet appel a pour but d’informer le site marchand de l’état du paiement (même si le client ne revient pas sur le site). Le marchand pourra ainsi valider sa commande si le paiement est vérifié et accepté.

Pour le renseigner, veuillez vous connecter avec vos identifiants marchand CinetPay, puis cliquez sur l’onglet « Préférences » et allez à la section « Notification de paiement instantanée ».

Remarque importante

  • Cette URL de notification est toujours appelée via une requête HTTP POST, et ce quel que soit la valeur du paramètre cpm_return_mode.
  • L’url de notification serveur est le seul mécanisme qui doit permettre le lancement des tâches dépendantes du paiement. (Mise à jour du statut de la commande dans votre back office boutique, envoie d’émail, déstockage produit etc …)
  • En cas d’échec de l’appel de l’url de notification serveur, la plateforme de paiement envoie un mail à l’administrateur de la boutique avec la raison de l’échec (erreur http etc …) Vous pourrez alors rejouer l’url serveur depuis le back office de la solution de paiement.
  •  Attention : l’URL de notification serveur peut être appelée plusieurs fois, il est donc nécessaire que votre implémentation prenne cela en considération. NB : Pour ceux qui renseignent les Urls directement dans leurs codes informatiques à travers les variables « notify_url », « return_url » et « cancel_url », ils peuvent ignorer cette configuration.

Une fois ces paramètres reçus par « POST » sur votre Url de notification, vous devez envoyer par POST les trois variables suivantes « apikey », « cpm_site_id » et « cpm_trans_id » à cette Url https://api.cinetpay.com/v1/?method=checkPayStatus afin d’obtenir le statut de votre paiement au format JSON.

Un exemple de réponse reçu ci-dessous :


{
    "transaction": {
        "cpm_site_id": "296911",
        "signature": "4dfbf5b8f40818abffe754b8a8aa04e4d29af25f",
        "cpm_amount": "11",
        "cpm_trans_date": "04092017140045",
        "cpm_trans_id": "50445985950",
        "cpm_custom": "08373459U",
        "cpm_currency": "XOF",
        "cpm_payid": "MP170904.1401.A91088",
        "cpm_payment_date": "2017-09-04",
        "cpm_payment_time": "14:01:35",
        "cpm_error_message": "SUCCES",
        "payment_method": "OM",
        "cpm_phone_prefixe": "225",
        "cel_phone_num": "79557788",
        "cpm_ipn_ack": "Y",
        "created_at": "2017-09-04 14:00:54",
        "updated_at": "2017-09-04 14:01:06",
        "cpm_result": "00",
        "cpm_trans_status": "ACCEPTED",
        "cpm_designation": "Test",
        "buyer_name": ""
    }
}

Après avoir décodé le JSON, si la valeur de la variable « cpm_result » est égale à « 00 » et si la valeur de la variable « cpm_amount » est égale à la valeur du montant stocké dans votre base de données et que finalement la valeur de la variable « signature » est la même que celle que vous avez préalablement stockée en base de données lors de l’achat ou du paiement, alors votre paiement est bon. Vous pouvez délivrer le service à votre client.

Liste des transactions
Liste des transactions

Vous devez envoyer au minimum par POST les deux variables suivantes « apikey », « cpm_site_id à cette Url https://api.cinetpay.com/v1/?method=getTransHistory afin d’obtenir le statut de votre paiement au format JSON.
Un exemple de réponse reçu ci-dessous :


{
    "Transactions": {
        "transaction": [{
                "cpm_site_id": "997744",
                "signature": "d2a3ce8f4e4b58d12ff42810a2391b7c014782f9",
                "cpm_amount": "250",
                "cpm_trans_id": "52422",
                "cpm_custom": "63#42#mpl",
                "cpm_currency": "XOF",
                "cpm_payid": "",
                "cpm_payment_date": "2015-07-05",
                "cpm_payment_time": "10:39:57",
                "cpm_error_message": "OTP_CODE_ERROR",
                "payment_method": "MOMO",
                "cpm_phone_prefixe": "225",
                "cel_phone_num": "06477877",
                "cpm_ipn_ack": "N",
                "created_at": "2015-07-05 10:39:57",
                "updated_at": "2015-07-05 10:39:57",
                "cpm_result": "604",
                "cpm_trans_status": "REFUSED",
                "cpm_designation": "",
                "buyer_name": ""
            },
            {
                "cpm_site_id": "997744",
                "signature": "aef5f497aeeb4f6ff07367649792634938960241",
                "cpm_amount": "25000",
                "cpm_trans_id": "52552255555",
                "cpm_custom": "522#633#mpl",
                "cpm_currency": "XOF",
                "cpm_payid": "",
                "cpm_payment_date": "2015-07-04",
                "cpm_payment_time": "17:47:49",
                "cpm_error_message": "OTP_CODE_ERROR",
                "payment_method": "MOMO",
                "cpm_phone_prefixe": "225",
                "cel_phone_num": "06477877",
                "cpm_ipn_ack": "N",
                "created_at": "2015-07-04 17:47:49",
                "updated_at": "2015-07-04 17:47:49",
                "cpm_result": "604",
                "cpm_trans_status": "REFUSED",
                "cpm_designation": "",
                "buyer_name": ""
            }
        ]
    }
}


Solde de la boutique
Solde

Vous devez envoyer au minimum par POST les deux variables suivantes « apikey », « cpm_site_id à cette Url https://api.cinetpay.com/v1/?method=getCompteStatus afin d’obtenir le statut de votre paiement au format JSON.
Un exemple de réponse reçu ci-dessous :


{
    "user": {
        "compte": {
            "solde": "865.4",
            "credit": "900",
            "debit": "34.6"
        },
        "service": {
            "solde": "33.6",
            "credit": "35",
            "debit": "1.4"
        }
    }
}

Non synchronisation des paiements
  • URL de notification serveur non renseignée dans le back office « Onglet Préférences une fois connecté »,
  • URL de notification serveur qui pointe sur la page d’accueil du site marchand et qui n’exécute aucun traitement,
  • URL de notification serveur qui ne peut être appelée car bloquée par un fichier .htaccess
  • URL de notification serveur bloquée par votre firewall,
  • Redirection à l’arrivée qui entraine la perte des valeurs postées. L’url serveur contient toujours les paramètres postés. Ne pas les trouver est toujours une erreur d’implémentation du côté du site marchand,
  • Les paramètres postés dans l’URL serveur peuvent évoluer par ajout de nouveaux champs.

Etape 3

Retour à la boutique

Le retour à la boutique permet à l’internaute de revenir à la boutique après un clic sur le bouton « Retour boutique » présent sur la page de paiement.

Dans le formulaire de paiement il est possible de renseigner plusieurs URL de retour :

  • Url en cas de succès,
  • Url en cas d'annulation,
  • url en cas de refus, etc
(Se référer à la documentation pour connaître tous les cas possibles)
Il est conseillé dans le cas du retour à la boutique d’analyser le contenu des paramètres en fonction du contexte de retour que vous voulez afficher à votre client :
Par exemple :
  • Retour à l’accueil de votre site
  • Retour sur un refus où vous pouvez proposer un moyen de paiement alternatif
  • Retour sur un message de remerciement ou de synthèse de commande si paiement accepté.
Par défaut nous ne renvoyons aucun paramètre dans l’URL retour à la boutique, mais vous pouvez définir dans le formulaire de paiement comment recevoir les paramètres via le champ cpm_return_mode (valorisé lors de la construction de votre formulaire de paiement. c.f Etape 2). Retour