Prepare a notification page

Why notification

The notification link/url is called by CinetPay to notify you of the status of a payment. This url must be available to accommodate HTTP requests of type GET and POST and return statut HTTP 200 OK . CinetPay will not post any data via GET, the server pings your url to make sure it is available


The notify_url must be the only mechanism to implement to automatically synchronize payments to your merchant site. CinetPay will call this link after each update to notify you of status changes during a transaction.

At the end of a payment, CinetPay systematically calls the notification url for the concerned service. This call aims to inform the merchant site of the payment status (even if the customer does not return to the site). The merchant will then be able to validate the order if the payment is verified and accepted.


The notification url is not necessary if you don't need to have the payment status in your database, as you have the payment history in your CinetPay backoffice.

Ex: Donation collection application.

STEPS TO CONFIGURE THE NOTIFICATION URL

1-RECEIVE A NOTIFICATION

The server executes a POST request containing :

  • Headers:

    • x-token : An HMAC token to allow verification on the partner's side. For more information, please consult the section dedicated to the token HMAC

  • Form values:

    • cpm_site_id: the site_id variable you sent at initialization
    • cpm_trans_id: the transaction_id variable that you sent at initialization
    • cpm_trans_date: the date and time of the transaction
    • cpm_amount: the amount
    • cpm_currency: the currency
    • signature : A token. It is different from the generated token
    • payment_method : the payment method
    • cel_phone_num: the number used to make the payment
    • cpm_phone_prefixe: the country prefix
    • cpm_language: the language in which the payment was made
    • cpm_version: the version used (V4)
    • cpm_payment_config: the type of payment (Single)
    • cpm_page_action : the type of action (Payment)
    • cpm_custom : the metadata you sent at initialization
    • cpm_designation : the designation you sent at initialization
    • cpm_error_message : the status of the transaction. If there is an error, you have the reason for the failure


you will have to collect mainly cpm_trans_id and cpm_site_id posted by CinetPay for the continuation of the configuration.

To ensure the integrity of the data you are processing, you need to perform some checks:

  • Your notification url must be an api that expects a call in POST and as a parameter the cpm_trans_id (corresponding to the transaction_id variable)

  • After getting it, you have to check in your database that the status of the payment concerned is already successful:

    • If yes then you are no longer updating;
    • If not, you must make a call to the transaction verification API to obtain the status of the transaction from CinetPay and thus update the status in your database.

2-VERIFY TRANSACTION STATUS

  • CinetPay will not send you the transaction status information to avoid some loophole security like the man in the middle.
  • The notification url can be called multiple times.
  • You will always have to make a call to the payment "Verification of transaction" API for have the true values of the payment.


To know the status of a transaction, you must send the following information in JSON format. Using this url: https://api-checkout.cinetpay.com/v2/payment/check

  • apikey : your apikey
  • site_id : your site_id
  • transaction_id : your transaction_id or token : The payment_token obtained during the initialization of the payment

for more details, please see the section Transaction verification


NB: Payment confirmation for some operators is via push notification , your system receives an initial notification with the status WAITING_FOR_CUSTOMER. This status describes the payment that is awaiting payment approval by the user. If you update the payment as a definite failure, this explains why payments made with these made with these operators are not properly processed by your system.

3-DELIVERING A SERVICE

When the payment is successful, you will receive this response from CinetPay:

 {
    {
    "code": "00",
    "message": "SUCCES",
    "data": {
        "amount": "100",
        "currency": "XOF",
        "status": "ACCEPTED",
        "payment_method": "OM",
        "description": "Paiement abonnement",
        "metadata": null,
        "operator_id": "MP220915.2257.A76307",
        "payment_date": "2022-09-15 22:57:15",
        "fund_availability_date": "2022-09-17 00:00:00"
    },
    "api_response_id": "1663323067.7677"
}

{primary.fa-info} Then you will have to deliver the service. Don't forget to update your database.

In case of failure, you will receive this answer from CinetPay:

 {
    "code": "627",
    "message": "TRANSACTION_CANCEL",
    "data": {
        "amount": "100",
        "currency": "XOF",
        "status": "REFUSED",
        "payment_method": "MOMO",
        "description": "Test de paiement demo CinetPay",
        "metadata": null,
        "operator_id": null,
        "payment_date": " ",
        "fund_availability_date": "2022-09-08 00:00:00"
    },
    "api_response_id": "1663323224.8402"
}

{warning.fa-close} No services shall be provided. Don't forget to update your database.

TEST YOUR NOTIFICATION URL

After payment, you can test your notification url using an http request application. For the example, we will use PostMan.

Available GET

test-notification


1) Enter your return url

2) Select the GET method, then click on "Send

3) You should receive Status 200 OK(If this is not the case, you will find the cause here )


Available POST

test-notification


1) Enter your notification url

2) Select the POST method

3) Select the content-type x-www-form-urlencoded

1) Enter cpm_trans_id and cpm_site_id with their respective values, then click on "Send".

4) You should receive Status :200 OK(If this is not the case, you will find the cause here )

Not getting a notification?

This usually happens when your notification url is not accessible or misconfigured. The table below summarizes the likely reasons why you are not receiving a notification.

Using an HTTP request app like PostMan you can test your notification url.

But first, make sure your notification url is available in GET and POST and accessible by a public server.


If the error obtained is not in the table below, write to us at this address: support.technique@cinetpay.com

Code Cause Solution
Status: 404 your url was not found Check that the url entered is correct.
Status : 419 This error is unique to Laravel and is due to the crsf. In Laravel it is mandatory the token at each POST If you do not want to send token, deactivate this check; Mention the name of your method in the app/http/middleware/VerifyCsrfToken.php file.
Status : 403 not permission This happens when the URL used for the request does not match a route defined on your API gateway.
Status : 504 Gateway Timeout This error indicates that the server, acting as a gateway or proxy, did not get a response in time from an upstream server to complete the request