CinetPay SDK Android

Step 1

Prerequisites

You need an account and an active service on CinetPay
Otherwise, please Open a merchant account and create a new service.
Once achieved, please login in your backoffice to find your APIKEY and SITE ID in order to proceed to integration.

Are you ready? Let's integrate!

Step 2

If you do not need to process CinetPay's payment notifications you can jump to the step 3.

Notification page

After each payment, CinetPay notifies you with a link that should be processed on the server side. We will use PHP in the example below: Script index.php in http://mondomaine.com/notify/ (the script must be stored in the url directory notify_url) ;

    <?php
    if (isset($_POST['cpm_trans_id'])) {
        // SDK PHP de CinetPay 
        require_once __DIR__ . '/cinetPay.php';
        require_once __DIR__ . '/commande.php';
    
        //La classe commande correspond à votre colonne qui gère les transactions dans votre base de données
        $commande = new Commande();
        try {
            // Initialisation de CinetPay et Identification du paiement
            $id_transaction = $_POST['cpm_trans_id'];
            $apiKey = _VOTRE_APIKEY_;
            $site_id = _VOTRE_SITEID_;
            $plateform = "TEST"; // Valorisé à PROD si vous êtes en production
            $CinetPay = new CinetPay($site_id, $apiKey, $plateform);
            // Reprise exacte des bonnes données chez CinetPay
            $CinetPay->setTransId($id_transaction)->getPayStatus();
            $cpm_site_id = $CinetPay->_cpm_site_id;
            $signature = $CinetPay->_signature;
            $cpm_amount = $CinetPay->_cpm_amount;
            $cpm_trans_id = $CinetPay->_cpm_trans_id;
            $cpm_custom = $CinetPay->_cpm_custom;
            $cpm_currency = $CinetPay->_cpm_currency;
            $cpm_payid = $CinetPay->_cpm_payid;
            $cpm_payment_date = $CinetPay->_cpm_payment_date;
            $cpm_payment_time = $CinetPay->_cpm_payment_time;
            $cpm_error_message = $CinetPay->_cpm_error_message;
            $payment_method = $CinetPay->_payment_method;
            $cpm_phone_prefixe = $CinetPay->_cpm_phone_prefixe;
            $cel_phone_num = $CinetPay->_cel_phone_num;
            $cpm_ipn_ack = $CinetPay->_cpm_ipn_ack;
            $created_at = $CinetPay->_created_at;
            $updated_at = $CinetPay->_updated_at;
            $cpm_result = $CinetPay->_cpm_result;
            $cpm_trans_status = $CinetPay->_cpm_trans_status;
            $cpm_designation = $CinetPay->_cpm_designation;
            $buyer_name = $CinetPay->_buyer_name;
    
            // Recuperation de la ligne de la transaction dans votre base de données
            $commande->setTransId($id_transaction);
            $commande->getCommandeByTransId();
            // Verification de l'etat du traitement de la commande
            if ($commande->getStatut() == '00') {
                // La commande a été déjà traité
                // Arret du script
                die();
            }
            // Dans le cas contrait, on remplit notre ligne des nouvelles données acquise en cas de tentative de paiement sur CinetPay
            $commande->setMethode($payment_method);
            $commande->setPayId($cpm_payid);
            $commande->setBuyerName($buyer_name);
            $commande->setSignature($signature);
            $commande->setPhone($cel_phone_num);
            $commande->setDatePaiement($cpm_payment_date . ' ' . $cpm_payment_time);
    
            // On verifie que le montant payé chez CinetPay correspond à notre montant en base de données pour cette transaction
            if ($commande->getMontant() == $cpm_amount) {
                // C'est OK : On continue le remplissage des nouvelles données
                $commande->setErrorMessage($cpm_error_message);
                $commande->setStatut($cpm_result);
                $commande->setTransStatus($cpm_trans_status);
                if($cpm_result == '00'){
                    //Le paiement est bon
                    // Traitez et delivrez le service au client
                }else{
                    //Le paiement a échoué
                }
            } else {
                //Fraude : montant payé ' . $cpm_amount . ' ne correspond pas au montant de la commande
                $commande->setStatut('-1');
                $commande->setTransStatus('REFUSED');
            }
            // On met à jour notre ligne
            $commande->update();
        } catch (Exception $e) {
            echo "Erreur :" . $e->getMessage();
            // Une erreur s'est produite
        }
    } else {
        // Tentative d'accès direct au lien IPN
    }
    ?>

Step 3

Library integration

Add the library as relying to your file build.gradle

    dependencies {
        implementation 'com.cinetpay:sdkjs:2.0.0'
    }

Payment gateway configuration

In order to collect payments, you first need to define your Merchant account parameters (API key, website ID, notification URL) and create an interface in between your application and CinetPay. This will enables your app to communicate payment information (amount, currency, transaction ID) to CinetPay.

To do this, please generate a class that inherits from the class CinetPayWebAppInterface.
For instance:

    public class MyCinetPayWebAppInterface extends CinetPayWebAppInterface {

        public MyCinetPayWebAppInterface(Context c, String api_key, int site_id, String notify_url, String trans_id, int amount, String currency, String designation, String custom, boolean should_check_payment) {
            super(c, api_key, site_id, notify_url, trans_id, amount, currency, designation, custom, boolean should_check_payment);
        }
    
        @Override
        @JavascriptInterface
        public void onPaymentCompleted(String payment_info) {
        }
    
        @Override
        @JavascriptInterface
        public void onError(String code, String message) {
        }
    
        @Override
        @JavascriptInterface
        public void terminatePending(String apikey, int cpm_site_id, String cpm_trans_id) {
        }
    
        @Override
        @JavascriptInterface
        public void terminateSuccess(String payment_info) {
        }
    
        @Override
        @JavascriptInterface
        public void terminateFailed(String apikey, int cpm_site_id, String cpm_trans_id) {
        }
    
        @Override
        @JavascriptInterface
        public void checkPayment(String apikey, int cpm_site_id, String cpm_trans_id) {
        }
    }   

This class includes data about processes triggered by particular events:
onPaymentCompleted: Performed when a payment is completed. It processes parameters displayed as a JSON character line that includes all information about the completed payment

The character line is built as follow:

    {
        "cpm_site_id": "",
        "signature": "", 
        "cpm_amount": "", 
        "cpm_trans_date": "", 
        "cpm_trans_id": "", 
        "cpm_custom": "", 
        "cpm_currency": "", 
        "cpm_payid": "", 
        "cpm_payment_date": "", 
        "cpm_payment_time": "", 
        "cpm_error_message": "", 
        "payment_method": "", 
        "cpm_phone_prefixe": "", 
        "cel_phone_num": "", 
        "cpm_ipn_ack": "", 
        "created_at": "", 
        "updated_at": "", 
        "cpm_result": "", 
        "cpm_trans_status": "", 
        "cpm_designation": "", 
        "buyer_name": ""
    }

For more information on the meaning of each parameter, refer to the documentHow to successfuly integrate CinetPay.
onError: Performed when an error occures. It processes the code and the error message.

terminatePending: Performed when the user pushes the Cancel button after initiating a payment without validating it (validation refers here to the fact of entering its confidential code on its smartphone as the last step before completing the payment, when paying with MTN or Moov). The Cancel button is displayed when the user closes CinetPay's payment page. The method takes into account the following parameters: apikey (your API key), cpm_site_id (your website ID), cpm_trans_id (the transaction ID that you defined for this specific payment). These parameters enable you to check for the payment final status since the customer can validate the payment after closing CinetPay's payment page. In order to check this final status, you need to send the following parameters through POST: apikey, cpm_site_id and cpm_trans_id to this URL: https://api.cinetpay.com/v1/?method=checkPayStatus. For further information, please refer to the document: Réussir l'intégration CinetPay.

terminateSuccess: Performed when the user pushes the button End. The button End is displayed when the user select Close in the payment page after completed its payment. It processes parameters displayed as a JSON character line that includes all information about the completed payment, same as in onPaymentCompleted.

terminateFailed: Performed when the user selects the button End after an error occured. The End button is displayed when the user closes the CinetPay page. It processes the following parameters: apikey (your API key), cpm_site_id (your website ID), cpm_trans_id (the transaction ID that you defined for this specific payment). These parameters enable you to check for the payment final status. In order to do so, you need to send the following parameters through POST: apikey, cpm_site_id and cpm_trans_id to this URL: https://api.cinetpay.com/v1/?method=checkPayStatus. For more information on possible answers, please consult: Réussir l'intégration CinetPay.

checkPayment: Performed when the user select the button Payment verification. The button is displayed (if you add the parameter should_check_payment to true when generating the class that inherits from CinetPayWebAppInterface) when the user closes the payment page after initiating a payment without validating it (validation refers here to the fact of entering its confidential code on its smartphone as the last step before completing the payment, when paying with MTN or Moo). It processes the following parameters: apikey (your API key), cpm_site_id (your website ID), cpm_trans_id (the transaction ID that you defined for this specific payment). PIn order to check this final status, you need to send the following parameters through POST: apikey, cpm_site_id and cpm_trans_id to this URL: https://api.cinetpay.com/v1/?method=checkPayStatus. For more information on possible answers, please consult: Réussir l'intégration CinetPay.

    try {
        JSONObject paymentInfo = new JSONObject(payment_info);
    
        String cpm_result = paymentInfo.getString("cpm_result");
        String cpm_trans_status = paymentInfo.getString("cpm_trans_status");
        String cpm_error_message = paymentInfo.getString("cpm_error_message");
        String cpm_custom = paymentInfo.getString("cpm_custom");
    
    } catch (JSONException e) { 
        e.printStackTrace(); 
    }

developer.android.element13

Display CinetPay payment page

After defining the payment procedure, you need to redirect the user to CinetPay's payment page. You first need to create an Activity that inherits from CinetPayActivity:

    public class MyCinetPayActivity extends CinetPayActivity {
        @Override
        protected void onCreate(Bundle savedInstanceState) { 
            super.onCreate(savedInstanceState);
        } 
    }

After defining the payment procedure, you need to redirect the user to CinetPay's payment page. You first need to create an Activity that inherits from CinetPayActivity:AndroidManifest.xml:

    <activity android:name=".MyCinetPayActivity" />

Please ensure that you add this to the file

    String api_key = "MY_API_KEY"; // A remplacer par votre clé API 
    int site_id = 0; // A remplacer par votre Site ID
    String notify_url = "";
    String trans_id = String.valueOf(new Date().getTime());
    int amount = 100 ;
    String currency = "CFA";
    String designation = "Achat test"; 
    String custom = "";
    
    Intent intent = new Intent(MainActivity.this,MyCinetPayActivity.class); 
    intent.putExtra(CinetPayActivity.KEY_API_KEY, api_key); 
    intent.putExtra(CinetPayActivity.KEY_SITE_ID, site_id); 
    intent.putExtra(CinetPayActivity.KEY_NOTIFY_URL, notify_url); 
    intent.putExtra(CinetPayActivity.KEY_TRANS_ID, trans_id); 
    intent.putExtra(CinetPayActivity.KEY_AMOUNT, amount); 
    intent.putExtra(CinetPayActivity.KEY_CURRENCY, currency); 
    intent.putExtra(CinetPayActivity.KEY_DESIGNATION, designation);
    intent.putExtra(CinetPayActivity.KEY_CUSTOM, custom);
    startActivity(intent);

    public class MyCinetPayActivity extends CinetPayActivity {
        @Override
        protected void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);
    
            Intent intent = getIntent();
    
            String api_key = intent.getStringExtra(KEY_API_KEY);
            int site_id = intent.getIntExtra(KEY_SITE_ID, 0);
            String notify_url = intent.getStringExtra(KEY_NOTIFY_URL);
            String trans_id = intent.getStringExtra(KEY_TRANS_ID);
            int amount = intent.getIntExtra(KEY_AMOUNT, 0);
            String currency = intent.getStringExtra(KEY_CURRENCY);
            String designation = intent.getStringExtra(KEY_DESIGNATION);
            String custom = intent.getStringExtra(KEY_CUSTOM);
    
            mWebView.addJavascriptInterface(new MyCinetPayWebAppInterface(this, api_key, site_id, notify_url, trans_id, amount, currency, designation, custom, true), "Android");
        }
    }

Example