Préparez une page de notification

Pourquoi la notification

Le lien/url de notification (notify_url) est appelé par CinetPay pour vous notifier de l’état d’un paiement. Cette url doit être disponible pour accueillir des requêtes HTTP de type GET et POST et retourner le statut HTTP 200 OK. CinetPay ne postera aucune donnée par GET, le serveur ping votre url afin de s'assurer qu'elle est disponible


Le notify_url doit être le seul mécanisme à implémenter pour synchroniser automatiquement les paiements vers votre site marchand. CinetPay appellera ce lien après chaque update pour vous notifier du changement de statuts pendant le déroulement d'une transaction.


A la fin d’un paiement, CinetPay appelle systématiquement l’url de notification 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é.


l’url de notification n’est pas nécessaire si vous n’avez pas besoin d’avoir le statut des paiements dans votre base de données, car vous avez l’historique de vos paiements dans votre backoffice CinetPay.

Ex : Application de collecte de dons

LES ETAPES POUR CONFIGURER L'URL DE NOTIFICATION

1-RECEVOIR UNE NOTIFICATION

Le serveur exécute une requête de type POST sur votre url de notification contenant :

  • Entête de la requête:

    • x-token : Un token HMAC pour permettre une vérification du côté du partenaire. Pour plus d'information, veuillez consulter la section dédié au token HMAC.

  • Corps de la requête:

    • cpm_site_id: la variable site_id que vous avez envoyé à l’initialisation
    • cpm_trans_id: la variable transaction_id que vous avez envoyé à l’initialisation
    • cpm_trans_date: la date et heure de la transaction | ex: 2000-12-21 19:19:00|
    • cpm_amount: le montant
    • cpm_currency : la devise
    • signature: un token. Il est différent du token généré
    • payment_method : la methode de paiement
    • cel_phone_num : le numero qui a servi a faire le paiement
    • cpm_phone_prefixe : le prefixe du pays
    • cpm_language : la langue utisé dans laquelle le paiement a été fait
    • cpm_version : la version utilisé(V4)
    • cpm_payment_config : le type de paiement(Single)
    • cpm_page_action : le type d'action (Payment)
    • cpm_custom : la variable metadata que vous avez envoyé à l’initialisation
    • cpm_designation : la variable designation que vous avez envoyé à l’initialisation
    • cpm_error_message : le statut de la transaction. En cas d'erreur, vous avez la raison de l'échec

vous devrez recuperez principalement cpm_trans_id et cpm_site_id posté par CinetPay pour la suite de la configuration.

Pour vous assurer de l’intégrité des données que vous traitez, vous devez effectuer certaines vérifications :

  • Votre url de notification doit être une api qui attend un appel en POST et en paramètre le cpm_trans_id (Correspondant à la variable transaction_id)
  • Après l’avoir obtenu, vous devez vérifier dans votre base de données que le statut du paiement concerné est déjà à succès :
    • Si oui alors vous ne faites plus de mise à jour ;
    • Si non vous devez faire un appel à l’api de vérification de transaction pour obtenir le statut de la transaction chez CinetPay et mettre ainsi à jour le statut dans votre base de données.

2-VERIFIER L'ETAT DE LA TRANSACTION

Remarque

  • CinetPay ne vous enverra pas les informations sur le statut de la transaction pour éviter certaine faille de sécurité comme le man in the middle.
  • L’url de notification peut être appelée plusieurs fois.
  • Il faudra toujours effectuer un appel à l’API de « Vérification de transaction » de paiement pour avoir les vraies valeurs du paiement.


Pour connaître le statut d'une transaction, vous devez envoyer les informations suivantes au format JSON.
En utilisant cette url: https://api-checkout.cinetpay.com/v2/payment/check

  • apikey : votre apikey
  • site_id : votre site_id
  • transaction_id : votre transaction_id ou token : Le payment_token obtenu lors de l’initialisation du paiement

pour plus de detail, veuillez consulter la section Vérification de transaction


NB : La confirmation de paiement pour certains opérateurs se fait par notification push , votre système reçoit une première notification avec le statut WAITING_FOR_CUSTOMER. Ce statut décrit le paiement qui est en attente d'une validation de paiement par l'utilisateur. Si vous mettez à jour le paiement comme échec définitivement, cela explique pourquoi les paiements effectués avec ces opérateurs ne sont pas correctement traités par votre système.

3-DELIVRER UN SERVICE

Lorsque le paiement est succès , vous recevrez cette réponse de 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} Ensuite vous devrez délivrer le service. N'oubliez pas de mettre à jour votre base de donnée.

En cas d'échec , vous recevrez cette réponse de 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} Aucun service ne devra être delivré. N'oubliez pas de mettre à jour votre base de donnée.

TESTER SON URL DE NOTIFICATION

{danger.fa-close} Aucune redirection ne doit etre effectuer sur l'url de notification elle doit servir seulement pour les traitements.

Après paiement, vous pouvez tester votre url de notification en utilisant une application de requête http. Pour l'exemple, nous utiliseront PostMan.

Disponible en GET

test-notification


1) Entrer votre url de notification

2) Selectionnez la methode GET, puis cliquer sur "Send"

3) Vous devrez recevoir Status 200 OK(Si cela n'est pas cas, vous trouverez certainement la cause ici )


Disponible en POST

test-notification


1) Entrer votre url de notification

2) Selectionnez la methode POST

3) Selectionnez le content-type x-www-form-urlencoded

4) Renseigner cpm_trans_id et cpm_site_id avec leur valeur respective, puis cliquer sur "Send"

5) Vous devrez recevoir Status :200 OK(Si cela n'est pas cas, vous trouverez certainement la cause ici)

Vous ne recevez pas de notification?

Cela intervient généralement lorsque votre url de notification n'est pas accessible ou mal configuré. Le tableau ci-dessous resume les probables raisons pour lesquelles vous ne recevez pas de notification.

En utilisant une application de requête HTTP comme PostMan, vous pouvez tester votre url de notification.

Mais avant, assurez-vous que votre url de notification soit disponible en GET et POST et accessible par un serveur public.


Si l'erreur obtenue ne se trouve pas dans le tableau ci dessous, écrivez-nous à cette adresse : support.technique@cinetpay.com

Code Cause Solution
Status: 404 votre url n'a pas été trouvé Verifier que l'url saisi est correcte.
Status: 415 Unsupported Media Type Cette erreur indique que le serveur refuse la requête, car le format de la charge utile (payload) n'est pas pris en charge. Assurer vous que le content-type attendu par votre url de notification est au format application/x-www-form-urlencoded
Status : 419 Cette erreur est propre à Laravel et est dû au crsf. Dans Laravel il est obligatoire le jeton à chaque POST Si vous ne voulez pas envoyer le token, désactiver cette vérification ; Mentionnez le nom de votre méthode dans le app/http/middleware/VerifyCsrfToken.php fichier.
Status : 403 not permission Cela se produit lorsque l'URL utilisée pour la requête ne correspond pas à une route définie sur votre API gateway.
Status : 504 Gateway Timeout Cette erreur indique que le serveur, agissant comme passerelle ou proxy, n'a pas obtenu de réponse à temps de la part d'un serveur situé en amont pour la complétion de la requête.