La carte du client passe-t-elle par notre application ?

Non. Votre serveur enregistre la commande et son montant auprès de la passerelle, puis envoie le client sur la page de paiement hébergée par celle-ci. La carte et le code de confirmation sont saisis là-bas, jamais dans votre application, et c'est ce qui vous évite d'avoir à protéger des données de carte.

Pourquoi la page de succès ne suffit-elle pas à marquer la commande payée ?

Parce que le retour du navigateur est un indice, pas une preuve : il peut arriver avant le débit, après, ou jamais si le client ferme l'onglet, et son adresse peut être forgée. La commande ne devient payée que lorsque votre serveur a lu le statut à la source, par une demande à la passerelle ou par un webhook dont la signature a été vérifiée.

Que se passe-t-il si le même paiement est notifié deux fois ?

Chaque webhook porte un identifiant d'événement que votre serveur mémorise ; la seconde livraison est acquittée par un 200 et n'écrit rien. Côté client, une clé d'idempotence par panier fait qu'un double clic renvoie la même commande au lieu d'en créer une seconde.

Combien coûte le paiement par carte et quand est-on versé ?

Aucune grille officielle n'est publiée, et les guides tiers qui citent des pourcentages se contredisent ; les frais, le délai de versement et les plafonds se demandent par écrit à la banque acquéreuse ou à l'agrégateur, et se vérifient au pilote en comparant le relevé aux commandes. Nous écrivons les chiffres obtenus dans le cahier des charges, pas dans l'article.

SATIM en direct ou un agrégateur ?

Les deux donnent la même architecture : une commande chez vous, une page chez eux, une confirmation à la source. L'agrégateur porte le contrat, la page et la documentation, et facture pour cela ; le branchement direct passe par votre banque et le GIE Monétique. Nous écrivons la machine à états avant de choisir, pour que le choix se fasse sur les frais et le délai, et puisse changer sans réécrire l'application.

Combien de temps pour mettre le paiement en production ?

Dix semaines : une pour le dossier et le choix, deux pour la machine à états en environnement de test, deux pour la confirmation et le webhook, deux pour les tests techniques de la plateforme, une pour le rapprochement et le remboursement, deux de pilote à petits montants. Le délai des tests techniques dépend de la plateforme et se demande par écrit.

Intégrer le paiement en ligne CIB et Edahabia dans votre application en Algérie en 2027 : la page de paiement, la confirmation côté serveur, le webhook, les états d'une commande, le rapprochement et le remboursement

Réponse courte. La carte du client n'entre jamais dans votre application : votre serveur crée une commande en attente avec un montant calculé chez lui, enregistre cette commande auprès de la passerelle, et envoie le client sur la page de paiement de celle-ci. Quand le client revient sur votre site, ce retour est un indice, pas une preuve : votre serveur demande à la passerelle le statut réel, ou reçoit un webhook signé, et c'est seulement là que la commande devient payée. Chaque commande a une clé d'idempotence pour qu'un double clic ou un webhook reçu deux fois ne débite ni ne compte deux fois. Chaque semaine, le relevé de la banque est rapproché des commandes, et un remboursement passe par l'API de la passerelle, jamais par un virement manuel. Dix semaines, dont deux de pilote à petits montants.

Ce guide s'adresse au commerçant ou au gérant qui veut encaisser par carte dans son application ou sa boutique, au fondateur installé en France qui veut vendre en dinars à des clients en Algérie, et au responsable qui doit comparer un devis « intégration du paiement » avec un autre. Il ne redit pas quel modèle économique choisir, décrit dans le guide sur la marketplace et celui sur le SaaS, ni comment on encaisse au comptoir, décrit dans le guide sur la caisse ; il décrit ce qui se construit entre votre application et la passerelle, et il prolonge notre page sur l'ingénierie logicielle.

Ce que les documentations disent

L'entrée est administrative avant d'être technique, et elle est publique. Le portail CIBWEB du GIE Monétique décrit le parcours d'un commerçant : créer un compte et déposer une demande, que le GIE « traite et statue sur son acceptabilité en moins de 24 h » selon ses propres mots ; passer « les tests techniques d'intégration à la plateforme de paiement électronique » ; obtenir une « autorisation d'entrée en exploitation ». Les conditions d'éligibilité qu'il affiche sont l'inscription au registre du commerce ou au registre de l'artisanat et l'inscription au fichier national des e-fournisseurs. Ce que cela impose : on vérifie ces deux inscriptions la première semaine, avant d'écrire une ligne, et le délai de la phase de tests se demande par écrit, parce que le portail ne le donne pas.

Le mécanisme technique est celui d'une page de paiement hébergée, documenté par des tiers. La documentation non officielle de la passerelle SATIM que nous avons lue décrit un enregistrement de commande qui renvoie un identifiant et une adresse de page de paiement, un montant « multiplié par 100 » avant l'envoi, un minimum de 50 dinars, une adresse de retour et une adresse d'échec, puis une confirmation côté serveur qui renvoie le statut, un code d'action et un code d'approbation. Elle distingue un environnement de test et un environnement de production. Nous le disons avec prudence : c'est une documentation tierce, et les paramètres exacts se relisent dans le guide d'intégration remis par votre banque ou votre intégrateur. Ce que cela impose : la même architecture quel que soit le fournisseur, une commande chez vous, une page chez eux, une confirmation à la source.

Les agrégateurs documentent la partie que les boutiques oublient : la notification. La documentation d'un agrégateur algérien qui prend en charge CIB et Edahabia décrit un webhook envoyé en HTTPS avec un type d'événement, « checkout.paid » par exemple, une signature HMAC-SHA256 du corps brut de la requête calculée avec votre clé secrète, une réponse 200 attendue de votre serveur, des clés de test préfixées et un champ qui distingue le mode réel du mode test ; elle précise qu'un webhook ne peut pas atteindre un serveur local, d'où un tunnel pendant le développement. Ce que nous n'avons pas trouvé : une grille de frais officielle, un délai de versement publié, une politique de renvoi des webhooks ; les trois se demandent par écrit, et les guides tiers qui citent des pourcentages se contredisent, raison pour laquelle nous n'en citons aucun.

Figure 1 · Six repères tirés des documentations publiques : le portail CIBWEB du GIE Monétique pour l’entrée, la documentation tierce de la passerelle SATIM pour les centimes et le minimum, la documentation d’un agrégateur algérien pour la signature des webhooks. Aucune grille de frais officielle n’est publiée ; elle se demande par écrit à la banque acquéreuse ou à l’agrégateur.

Un paiement, de l'écran du client au relevé de la banque

Le paiement ne se comprend pas sur un schéma d'API mais sur le trajet d'un paiement réel, et sur la station où l'on a le droit de le croire.

Figure 2 · Le paiement traverse trois couloirs, et la seule station qui compte est la cinquième : votre serveur demande à la passerelle le statut réel de la commande. Le retour du navigateur, station quatre, est ce qu’on voit en premier et ce qu’on croit en dernier : un client qui ferme l’onglet après avoir payé n’y passe jamais, et la commande doit quand même devenir payée.

Première station, chez vous : le client valide son panier, votre serveur fige les lignes, calcule le montant, crée la commande en attente avec un numéro et une clé d'idempotence, et enregistre cette commande auprès de la passerelle en lui envoyant le montant ; c'est votre serveur qui dit le montant, jamais l'écran. Deuxième, chez la passerelle : le client est envoyé sur sa page de paiement, qui est la seule à voir la carte. Troisième, sur le téléphone du client : il saisit sa carte CIB ou Edahabia et le code reçu par SMS, selon le parcours de sa banque. Quatrième, le retour : le navigateur revient sur votre adresse de succès avec un identifiant dans l'adresse. C'est l'indice. Il arrive parfois avant le paiement, parfois après, parfois jamais.

Cinquième station, la seule qui compte : votre serveur demande à la passerelle le statut de la commande, ou reçoit le webhook signé, et lit « payé » à la source. C'est la preuve, et c'est ici seulement que la commande change d'état. Sixième : payée, reçu envoyé par WhatsApp et e-mail selon le guide sur les notifications, stock réservé. Puis, un à trois jours plus tard, une ligne apparaît sur le relevé de la banque acquéreuse, nette ou avant commission selon votre contrat, et le rapprochement la relie au numéro de commande ; ce qui ne se relie pas devient une question posée à la banque, pas un écart qu'on découvre à la clôture.

«Le retour du navigateur est ce qu'on voit en premier et ce qu'on croit en dernier.»

Le paiement en ligne dans une application, en cinq couches

Derrière ces six stations, cinq couches, et une seule vous appartient vraiment.

Figure 3 · La couche accentuée est la vôtre : c’est elle qui tient la machine à états et qui décide ce qu’une commande est. L’écran ne décide rien, la passerelle garde la carte, la banque garde l’argent, et la supervision relie les trois chaque semaine.

L'écran : le panier, le bouton payer, la page d'attente, les pages de succès et d'échec ; il affiche l'état, il ne le décide jamais, et un écran de succès qui dit « payé » parce que l'adresse contient le mot succès est le premier défaut que nous corrigeons. Votre serveur : la commande et sa machine à états, les montants calculés côté serveur, la clé d'idempotence, le journal ; c'est la seule couche qui écrit « payée », et seulement après avoir vérifié à la source. La passerelle : la page de paiement hébergée, l'enregistrement, le statut, le remboursement ; SATIM en direct par votre banque, ou un agrégateur qui porte le contrat et la page ; la carte ne traverse jamais la frontière entre cette couche et la vôtre.

La banque et le réseau : la banque acquéreuse qui vous verse, la banque émettrice du client, le réseau interbancaire, le GIE Monétique qui autorise ; les frais, le délai de versement et le contrat se négocient ici, et aucune ligne de code ne les change. La supervision : le rapprochement relevé ↔ commandes, les commandes en attente depuis trop longtemps, les webhooks rejetés pour signature invalide, les remboursements du mois ; un écran lu chaque semaine, bâti comme le tableau de bord du gérant. Le choix entre SATIM en direct et un agrégateur se fait par écrit la première semaine, avec les frais et le délai de versement de chacun, et il ne change rien aux couches deux et cinq : c'est la raison d'écrire la machine à états avant de brancher qui que ce soit.

Les états d'une commande, et ce qui a le droit de les changer

La machine à états est le cœur de l'intégration, et le dessin qu'on relit avec le client avant la première ligne.

Figure 4 · Sept états, et chaque flèche porte l’événement qui a le droit de la déclencher. Deux choses ne déclenchent rien : le retour du navigateur, qui est barré, et le second exemplaire d’un webhook, qui retombe sur le même état. Ce dessin est la pièce du cahier des charges que nous relisons avec le client avant d’écrire la première ligne.

Sept états. Créée : le panier est figé et le montant calculé. En attente de paiement : la commande est enregistrée chez la passerelle et la page est ouverte. Payée : le statut a été lu à la source. Livrée : le colis a été scanné ou le service rendu. Échouée : la banque a refusé. Expirée : trente minutes sans confirmation, le stock est libéré. Remboursée : total ou partiel, daté, avec le motif. Trois événements font avancer le chemin normal : la validation côté serveur, le statut « payé » lu chez la passerelle, la livraison scannée. Chacun est vérifié par votre serveur, et chacun écrit une ligne de journal avec l'état avant et après, comme le guide sur le journal d'audit le prévoit.

Deux choses ne font rien. Le retour du navigateur sur votre adresse de succès, barré sur le dessin : il affiche l'état en base, il ne le modifie pas, et c'est ce qui rend indifférent l'ordre d'arrivée entre le retour et le webhook. Le second exemplaire d'un webhook : sa signature est vérifiée, son identifiant d'événement est reconnu, votre serveur répond 200 et n'écrit rien. La règle tient en une phrase, écrite dans le cahier des charges : un état ne change que sur un événement vérifié par votre serveur, jamais sur ce que le navigateur du client raconte. Tout le reste, reçu, stock, comptabilité, découle de l'état, et jamais de l'écran.

«Un état ne change que sur un événement vérifié par votre serveur, jamais sur ce que le navigateur du client raconte.»

Six situations réelles, et ce que l'architecture fait

Six situations que nous voyons chaque semaine sur des boutiques qui fonctionnent, et le mécanisme qui règle chacune.

Figure 5 · Aucune de ces six situations n’est rare : les trois premières arrivent chaque semaine sur une boutique qui fonctionne. Toutes se résolvent par la même règle, un état ne change que sur un événement vérifié par le serveur, et par deux mécanismes, la clé d’idempotence et la signature du webhook.

Le client paie puis ferme l'onglet : le retour n'arrive jamais ; le webhook, ou la vérification planifiée des commandes en attente toutes les cinq minutes, passe la commande à payée, et le reçu part sans que le client revienne. Deux clics sur payer : une clé d'idempotence par panier, et le second clic renvoie la même commande et la même page au lieu d'en créer une deuxième ; c'est la mécanique décrite dans le guide sur le mode hors ligne. Le webhook arrive avant le retour : la page de succès lit l'état en base et l'affiche ; l'ordre est indifférent.

Le même webhook arrive deux fois : identifiant mémorisé, seconde livraison acquittée sans écriture ; sans cela, deux reçus, deux lignes comptables et un stock décompté deux fois. Payé, mais le stock a disparu : le dernier article est parti au comptoir pendant le paiement ; remboursement par l'API de la passerelle, état remboursée, message au client, et jamais un virement manuel qu'aucun rapprochement ne retrouvera. La passerelle ne répond plus : le paiement à la livraison ou le virement reste proposé, les commandes en attente expirent proprement et libèrent le stock, et la supervision le signale ; une boutique qui n'a que la carte ne vend rien ce soir-là.

Vu ailleurs : les pages de paiement hébergées, les webhooks signés, et ce qui se transpose

Trois sources disent l'essentiel. Le portail du GIE Monétique dit que l'entrée est une demande, des tests techniques et une autorisation ; ce qui se transpose, c'est que le dossier se dépose la première semaine, parallèlement au code en environnement de test. La documentation tierce de la passerelle SATIM décrit une commande enregistrée côté serveur, une page hébergée et une confirmation à la source ; ce qui se transpose, c'est que votre serveur ne voit jamais la carte et ne croit jamais le navigateur. La documentation d'un agrégateur décrit un webhook signé, acquitté par un 200 et impossible à recevoir en local ; ce qui se transpose, c'est la vérification de la signature sur le corps brut, la mémoire des événements reçus, et un tunnel pendant le développement.

Ce que ces sources ne disent pas : les frais, le délai de versement, la politique de renvoi des webhooks, et le comportement exact de la page de paiement sur le téléphone de vos clients ; les deux premiers se demandent par écrit, les deux derniers se mesurent au pilote.

Les règles d'une intégration de paiement qu'on peut mettre en production

Six règles, écrites la première semaine. Le montant est calculé côté serveur, jamais lu depuis l'écran ni depuis l'adresse de retour. Le retour du navigateur n'est qu'un indice ; seul le statut lu à la source ou un webhook signé change l'état. Une clé d'idempotence par commande, et un identifiant mémorisé par webhook : rien n'est débité ni compté deux fois. Une commande en attente expire et libère le stock. Le relevé est rapproché des commandes chaque semaine, et chaque écart est une question posée. Un remboursement passe par l'API et laisse un état, un motif et une date.

Une septième règle porte sur le devis : « intégration du paiement CIB/Edahabia » n'est pas une exigence, c'est une phrase ; l'exigence s'écrit « machine à états de la commande avec sept états et les événements autorisés ; montants côté serveur ; enregistrement de la commande chez la passerelle et page hébergée ; confirmation du statut à la source ; webhook avec signature vérifiée sur le corps brut et identifiants mémorisés ; clé d'idempotence par panier ; expiration des commandes en attente ; rapprochement relevé ↔ commandes avec liste des écarts ; remboursement par API ; environnement de test, tests techniques de la plateforme, pilote à petits montants », et elle se vérifie comme le guide sur le cahier des charges le recommande. Un devis qui chiffre « le bouton de paiement » a chiffré l'écran, c'est-à-dire la couche qui ne décide rien.

Six entreprises, et ce que leur paiement a de particulier

Six entreprises que nous équipons souvent, et pour chacune la particularité que la machine à états doit porter.

La billetterie, décrite dans le guide dédié. Le billet n'existe qu'à l'état payée ; l'expiration libère les places en quelques minutes, pas en heures.
La salle de sport et son abonnement, décrits dans le guide dédié. Chaque échéance est une commande ; l'accès suit l'état, et le renouvellement propose la page de paiement par WhatsApp.
Le promoteur qui vend sur plan à la diaspora, décrit dans le guide dédié. Des tranches datées, chacune une commande, et un reçu qui porte le numéro du lot ; les plafonds de carte se vérifient avec la banque avant d'annoncer le paiement en ligne.
L'agence Omra, décrite dans le guide dédié. Le paiement par tranches, l'état du dossier qui suit les états des paiements, et un remboursement partiel qui garde le motif.
La plateforme de cours, décrite dans le guide dédié. Le parent en France paie en dinars pour l'élève en Algérie ; la commande porte les deux identités, et le reçu part aux deux.
Le commerce piloté depuis la France, décrit dans le guide dédié. Le fondateur voit chaque matin les commandes payées, en attente trop longtemps et remboursées, et le rapprochement du relevé le vendredi.

Le calendrier 2027

Le calendrier est celui d'un paiement en ligne mis en production en dix semaines, dont les deux premières d'attente administrative se recouvrent avec le code.

Figure 6 · Dix semaines, dont les deux premières d’attente administrative se recouvrent avec le code en environnement de test. La machine à états est écrite avant le branchement à la passerelle ; c’est elle qu’on teste avec des webhooks simulés, et c’est elle qui ne change pas quand on change de passerelle.

La semaine 0 à 1 dépose le dossier et tranche le choix : compte CIBWEB, registre et e-fournisseur vérifiés, SATIM en direct par la banque ou agrégateur, décidé par écrit avec les frais et le délai de versement. Les semaines 1 à 3 écrivent la machine à états en environnement de test : commande, montants côté serveur, clé d'idempotence, pages de succès et d'échec, avec des webhooks simulés ; rien n'est encore branché à la vraie passerelle, et c'est voulu. Les semaines 3 à 5 branchent la confirmation et le webhook : statut lu à la source, signature vérifiée, identifiants mémorisés, vérification planifiée des commandes en attente.

Les semaines 5 à 7 passent les tests techniques de la plateforme et obtiennent l'autorisation ; leur durée dépend de la plateforme et se demande par écrit. La semaine 7 à 8 construit le rapprochement et le remboursement. Les semaines 8 à 10 sont le pilote à petits montants : paiements réels de l'équipe puis de dix clients, chaque écart lu chaque jour, puis la décision d'ouvrir à tous. Chaque lot est démontré comme le guide sur la livraison le décrit, et les serveurs sont placés selon le guide sur l'hébergement : la page de paiement est chez la passerelle, mais votre machine à états doit répondre vite au webhook, d'où elle est.

Ce qui fait échouer une intégration de paiement

Les intégrations que nous reprenons ont presque toujours échoué pour l'une de ces raisons.

Croire le retour du navigateur. La commande passe à payée parce que l'adresse contient « succès » ; des commandes payées sans débit, des débits sans commande.
Le montant lu depuis l'écran. Un paramètre modifié dans le navigateur, et un article à 8 500 dinars payé 85.
Pas de clé d'idempotence. Un double clic, deux commandes ; une coupure, deux débits.
Pas de vérification de signature. N'importe qui peut envoyer un faux webhook « payé » à votre serveur.
Pas d'expiration. Des commandes en attente depuis des jours, un stock bloqué, un entrepôt qui ne comprend pas.
Pas de rapprochement. L'écart entre le relevé et les ventes se découvre à la clôture, trois mois trop tard.
Le remboursement par virement manuel. Introuvable dans le rapprochement, oublié dans la comptabilité, et le client rappelle.

Questions fréquentes

Les questions que nous recevons de commerçants, de fondateurs et de responsables informatiques.

La carte du client passe-t-elle par notre application ?: Non. Votre serveur enregistre la commande et son montant auprès de la passerelle, puis envoie le client sur la page de paiement hébergée par celle-ci. La carte et le code de confirmation sont saisis là-bas, jamais dans votre application, et c'est ce qui vous évite d'avoir à protéger des données de carte.
Pourquoi la page de succès ne suffit-elle pas à marquer la commande payée ?: Parce que le retour du navigateur est un indice, pas une preuve : il peut arriver avant le débit, après, ou jamais si le client ferme l'onglet, et son adresse peut être forgée. La commande ne devient payée que lorsque votre serveur a lu le statut à la source, par une demande à la passerelle ou par un webhook dont la signature a été vérifiée.
Que se passe-t-il si le même paiement est notifié deux fois ?: Chaque webhook porte un identifiant d'événement que votre serveur mémorise ; la seconde livraison est acquittée par un 200 et n'écrit rien. Côté client, une clé d'idempotence par panier fait qu'un double clic renvoie la même commande au lieu d'en créer une seconde.
Combien coûte le paiement par carte et quand est-on versé ?: Aucune grille officielle n'est publiée, et les guides tiers qui citent des pourcentages se contredisent ; les frais, le délai de versement et les plafonds se demandent par écrit à la banque acquéreuse ou à l'agrégateur, et se vérifient au pilote en comparant le relevé aux commandes. Nous écrivons les chiffres obtenus dans le cahier des charges, pas dans l'article.
SATIM en direct ou un agrégateur ?: Les deux donnent la même architecture : une commande chez vous, une page chez eux, une confirmation à la source. L'agrégateur porte le contrat, la page et la documentation, et facture pour cela ; le branchement direct passe par votre banque et le GIE Monétique. Nous écrivons la machine à états avant de choisir, pour que le choix se fasse sur les frais et le délai, et puisse changer sans réécrire l'application.
Combien de temps pour mettre le paiement en production ?: Dix semaines : une pour le dossier et le choix, deux pour la machine à états en environnement de test, deux pour la confirmation et le webhook, deux pour les tests techniques de la plateforme, une pour le rapprochement et le remboursement, deux de pilote à petits montants. Le délai des tests techniques dépend de la plateforme et se demande par écrit.