Payment APICinetPay

The integration is in 3 steps:

SDK PHP CinetPay

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

Payment form

To call our payment gateway you need to submit a https form, when in production. This form includes the compulsory settings provided below, as well as a unique signature field that ensure its authenticity.

Signature

To compute the signature, you need to submit precisely (in POST form) the information provided in the table below on the following page https://api.cinetpay.com/v1/?method=getSignatureByPost You will obtain in response a character string that corresponds to your payment signature. Please store your signature in the field « signature » or in a JSON in the case where an error occurs.

GetSignature

NB: The amount must be a multiple of 5, the minimum amount being 100 FCFA
You can pre-filled the phone number field in order to make it compulsory for a client to use a specific phone number. In order to do this, you will need to add two variables to the above-mentionned table:
cel_phone_num: Client phone number (ex: 01020304) cpm_phone_prefixe : Country prefix (ex: 225)

NB: These fields are optional, except for merchants who expressly required that those fields be used.

Example of good answer: '95db7a68358e8cb8831db947d8abcfef002af755' Example of JSON answer in the case of an error:


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

NB: Whatever the answer receided, you will need to decrypt this answer since it is considered as a JSON.

Creating the payment form

The URL of the payment gateway is: https://secure.cinetpay.com

postForm

If you obtain your signature while adding the fields (cel_phone_num & cpm_phone_prefixe), then you will need to add these two elements to the form:
cel_phone_num: Client phone number (ex: 01020304) cpm_phone_prefixe : Country prefix (ex: 225)
You can activate the debug mode by adding the fields 'debug' with the value 1

URL notification

Once a payment is complete, the gateway systematically calls the url notification server as specified for the service concerned in the merchant's back-office. This call will notify the merchant website with the payment status (even if the client does not come back to the website after completed the payment). The merchant can hence validate the client's order when the payment is verified and accepted.

In order to specify your URL notification, login on your CinetPay account and select « Préférences » in the menu, to access the field « Notification de paiement instantanée ».

Attention

  • This URL notification is always called by a HTTP POST request, whatever the value of the parameter cpm_return_mode is.
  • The server URL notification is the only mecanism that triggers the different tasks linked to a payment. (Order status update, emails sent, update of the product's stock)
  • In the case where the call for the server url notification fails, the payment gateway sends an email to the shop admin with the reason for failure (erreur mistake etc …). You can replay the server url from your CinetPay backoffice.
  •  Attention: the server url notification can be called several time, your integrate must take this into account. NB: This configuration does not apply to websites that encodes URLs directly in their code within the fields « notify_url », « return_url » and « cancel_url ».

Once these parameters are received by « POST » on your URL notification, you need send through POST the following parameters « apikey », « cpm_site_id » et « cpm_trans_id » to the following URL https://api.cinetpay.com/v1/?method=checkPayStatus to obtain the payment status under a JSON form.

Below, an example of answer:


{
    "transaction": {
        "cpm_site_id": "296911",
        "signature": "4dfbf5b8f40818abffe754b8a8aa04e4d29af25f",
        "cpm_amount": "11",
        "cpm_trans_date": "04092017140045",
        "cpm_trans_id": "50445985950",
        "cpm_custom": "08373459U",
        "cpm_currency": "CFA",
        "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": ""
    }
}        

After analyzing the JSON, if the value of the variable « cpm_result » equals « 00 », if the value of the variable « cpm_amount » equals the value of the amount stored in your database, and if the value of the variable « signature » equals the value stored in your database at the payment, then the payment is considered as valid. You can proceed the client's order and deliver the service/product bought.

Transactions list
Liste des transactions

You need to send at least the following two variables through POST, « apikey », « cpm_site_id », to this Url https://api.cinetpay.com/v1/?method=getTransHistory afin d’obtenir le statut de votre paiement au format JSON.
Below an example of answer:


{
    "Transactions": {
        "transaction": [{
                "cpm_site_id": "997744",
                "signature": "d2a3ce8f4e4b58d12ff42810a2391b7c014782f9",
                "cpm_amount": "250",
                "cpm_trans_id": "52422",
                "cpm_custom": "63#42#mpl",
                "cpm_currency": "CFA",
                "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": "CFA",
                "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": ""
            }
        ]
    }
}
            

Shop balance
Solde

You need to send at least the following two variables through POST, « apikey », « cpm_site_id», to this Url https://api.cinetpay.com/v1/?method=getCompteStatus in order to obtain the payment status as a JSON.
Below an example of answer:


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

Payment synchronisation error
  • The server URL notification not informed in the back office «Préférences once logged in»,
  • Server URL notification that linked to the merchant website home page and does not process any command
  • Server URL notification that can't be called because blocked by a file .htaccess
  • erver URL notification blocked by a firewall,
  • Redirection upon arrival that leads to the loss of posted data. The server url always holds the posted data. Not identifying the parameters sent is due to a mistake when integrated on the merchant website side.
  • Posted parameters in the server URL can evolve when new fields are added.

Step 3

Back to the merchant website

The « Back to the merchant website » functionality enables the customer to go back to the merchant website after proceeding to the payment.

You can add different return URLs in the payment gateway:

  • Url in case of success,
  • Url in case of cancellation,
  • url in case of payment rejection, etc
(Please refer to the documentation to take note of the different cases)
In the case where the customer goes back to your homepage, we advise you to analyze the parameters data in order to display the right information to the customer, depending on the context:
Par exemple :
  • Back to your site homepage
  • Back to the order checkout page in case payment rejection, in order to offer an alternative payment method
  • Back to a Thank You note or order summary when the payment was successful
By default, we do not send parameters in the return URL, but you can define in the payment form how to receive parameters thanks to the field cpm_return_mode (valued when building the payment gateway. c.f Step 2). Retour