Aller au contenu
Loudbel
Discutons de votre projet
Services Réalisations À propos Blog Contact

Développement Web · Tutoriels

Intégrer le paiement en ligne CIB et Edahabia sur votre site avec Chargily Pay

Tutoriel complet pour accepter les cartes CIB et Edahabia sur votre site grâce à l’API Chargily Pay V2 : mode test, création d’un checkout, webhook sécurisé et plugin WordPress.

Intégrer le paiement en ligne CIB et Edahabia sur votre site avec Chargily Pay

Encaisser un paiement par carte CIB ou Edahabia directement sur votre site n’est plus réservé aux grandes entreprises. Grâce à des passerelles de paiement dotées d’une API, un développeur peut aujourd’hui ajouter un bouton « Payer en ligne » à un site vitrine, une boutique ou une application web. Dans ce tutoriel, nous expliquons comment intégrer le paiement en ligne en Algérie avec Chargily Pay : le principe, les étapes, un exemple de code en PHP et les bonnes pratiques de sécurité.

Ce tutoriel s’appuie sur la documentation officielle de Chargily Pay (API v2). Vérifiez-la toujours avant une mise en production : les API évoluent.

Comment fonctionne un paiement en ligne via une passerelle

Votre site ne manipule jamais directement les données de carte du client. Le parcours est le suivant :

  1. Le client clique sur « Payer » sur votre site.
  2. Votre serveur demande à la passerelle de créer une session de paiement (un « checkout ») avec le montant.
  3. La passerelle renvoie une URL de paiement ; le client y est redirigé et saisit sa carte CIB ou Edahabia sur la page sécurisée.
  4. Le client revient sur votre site (page de succès ou d’échec).
  5. La passerelle envoie à votre serveur une notification (webhook) qui confirme le statut réel du paiement.

Point essentiel : seul le webhook fait foi. Un client peut atteindre votre page « succès » sans avoir payé ; c’est la notification signée qui doit déclencher la validation de la commande.

Étape 1 : créer votre compte et récupérer vos clés

  1. Créez un compte sur Chargily Pay.
  2. Dans le tableau de bord, ouvrez l’espace développeur pour récupérer vos clés d’API.
  3. Vous disposez de deux environnements distincts, Test et Live, chacun avec sa propre URL et ses propres clés. Le mode Live nécessite la vérification de votre compte.

Les URL de base indiquées dans la documentation sont :

Test : https://pay.chargily.net/test/api/v2
Live : https://pay.chargily.net/api/v2

Stockez la clé secrète dans une variable d’environnement ou un fichier de configuration hors du dossier public, jamais dans le code JavaScript du navigateur.

Étape 2 : créer un checkout côté serveur

La création d’un checkout se fait par une requête POST sur /checkouts. Les paramètres principaux, d’après la référence de l’API :

  • amount et currency (actuellement "dzd"), ou bien une liste items de produits préalablement créés ;
  • success_url (obligatoire) et failure_url ;
  • payment_method : "edahabia", "cib" ou "chargily_app" (le client peut changer sur la page de paiement) ;
  • webhook_endpoint : l’URL de votre serveur qui recevra les notifications ;
  • locale : "fr", "ar" ou "en" ;
  • metadata : pour stocker, par exemple, votre numéro de commande.

Exemple minimal en PHP avec cURL :

<?php
$secret = getenv('CHARGILY_SECRET_KEY');
$base   = 'https://pay.chargily.net/test/api/v2';

$payload = [
  'amount'           => 2500,
  'currency'         => 'dzd',
  'payment_method'   => 'edahabia',
  'success_url'      => 'https://votre-site.dz/paiement/succes',
  'failure_url'      => 'https://votre-site.dz/paiement/echec',
  'webhook_endpoint' => 'https://votre-site.dz/webhook/chargily',
  'locale'           => 'fr',
  'metadata'         => ['order_id' => '1042'],
];

$ch = curl_init($base . '/checkouts');
curl_setopt_array($ch, [
  CURLOPT_POST           => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => [
    'Authorization: Bearer ' . $secret,
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS     => json_encode($payload),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

// Redirection du client vers la page de paiement sécurisée
header('Location: ' . $response['checkout_url']);
exit;

La réponse contient notamment un identifiant (id), un statut (pending au départ) et l’URL de paiement checkout_url. Enregistrez l’identifiant du checkout avec votre commande : vous en aurez besoin pour faire le lien lors du webhook.

Étape 3 : recevoir et vérifier le webhook

D’après la documentation des webhooks, chaque notification est une requête POST en JSON qui contient un en-tête signature : un HMAC SHA-256 du contenu brut, calculé avec votre clé secrète. Votre endpoint doit :

  1. vérifier la signature ;
  2. lire le type d’événement (type), par exemple checkout.paid ou checkout.failed ;
  3. mettre à jour la commande ;
  4. répondre avec un code HTTP 200.
<?php
$secret    = getenv('CHARGILY_SECRET_KEY');
$payload   = file_get_contents('php://input');      // corps brut
$signature = $_SERVER['HTTP_SIGNATURE'] ?? '';

$computed = hash_hmac('sha256', $payload, $secret);
if (!$signature || !hash_equals($computed, $signature)) {
  http_response_code(403);
  exit;
}

$event    = json_decode($payload, true);
$checkout = $event['data'];

switch ($event['type']) {
  case 'checkout.paid':
    // Marquer la commande liée à $checkout['id'] comme payée
    break;
  case 'checkout.failed':
    // Marquer la commande comme échouée
    break;
}

http_response_code(200);

Deux détails importants : calculez la signature sur le corps brut de la requête (et non sur un JSON décodé puis réencodé), et utilisez une comparaison à temps constant (hash_equals).

Étape 4 : tester en mode Test

  • Utilisez l’URL et les clés du mode Test.
  • Votre webhook doit être accessible depuis Internet : en local, utilisez un outil de tunnel ou déployez sur un serveur de préproduction.
  • Testez les trois scénarios : paiement réussi, paiement échoué, client qui abandonne.
  • Vérifiez qu’un même webhook reçu deux fois ne valide pas deux fois la commande (idempotence).

Et avec WordPress / WooCommerce ?

Si votre boutique tourne sous WooCommerce, inutile de tout coder : Chargily publie une extension WordPress officielle sur GitHub. Il suffit en principe de l’installer, de l’activer et de renseigner vos clés d’API dans ses réglages. Comme toujours, testez en mode Test avant d’ouvrir les paiements réels. Pour bien démarrer votre site, voyez notre tutoriel WordPress professionnel.

Sécurité et conformité : la checklist

  • Clé secrète uniquement côté serveur, jamais dans le navigateur ni sur GitHub.
  • Site entièrement en HTTPS.
  • Validation des commandes uniquement via le webhook signé.
  • Journalisation des notifications reçues pour pouvoir enquêter en cas de litige.
  • Pages légales à jour : conditions générales de vente, politique de remboursement, politique de confidentialité.
  • Respect du cadre du commerce électronique : la loi n° 18-05 du 10 mai 2018 impose des obligations aux e-fournisseurs. Faites valider votre situation par un professionnel.

Les erreurs fréquentes

  • Mélanger Test et Live : une clé Live avec l’URL Test (ou l’inverse) provoque des erreurs d’authentification.
  • Valider la commande sur la page de succès : c’est une faille ; seul le webhook compte.
  • Montant calculé côté navigateur : recalculez toujours le prix côté serveur à partir de votre base de données.
  • Webhook qui répond trop lentement : traitez l’essentiel, répondez 200, et déléguez les tâches lourdes (e-mails, factures) à une file d’attente.

Pour aller plus loin

Le paiement en ligne local fait partie des tendances web 2026 qui changent la donne pour les entreprises algériennes. Si vous chiffrez un projet e-commerce, notre article sur le prix d’un site web en Algérie détaille les postes à prévoir.

Conclusion

Intégrer CIB et Edahabia sur un site se résume à trois briques : créer un checkout côté serveur, rediriger le client, puis valider la commande grâce à un webhook signé. Avec un environnement de test et quelques bonnes pratiques, vous pouvez proposer un vrai parcours d’achat en ligne à vos clients algériens.

Besoin d’une boutique ou d’une application avec paiement en ligne ? Loudbel conçoit et intègre des solutions e-commerce et des plateformes sur-mesure. Découvrez nos services ou contactez-nous.

Image de couverture : Shixart1985 — via Wikimedia Commons, licence CC BY 2.0.

Un projet web ?

Parlons de votre site, de votre application ou de votre automatisation

Loudbel conçoit des sites WordPress, des applications web et des plateformes rapides et bien référencées, pour les entreprises en Algérie et à l’international.

Built with Oxygen