API de paiement au Maroc : guide d'intégration technique 2026

Introduction : pourquoi l'approche API-first transforme le paiement au Maroc

Le marché du paiement en ligne au Maroc a atteint une maturité technique qui exige désormais des intégrations robustes, programmatiques et scalables. Les commerçants marocains ne se contentent plus de formulaires de paiement génériques redirigeant vers des pages bancaires. Ils veulent des expériences embarquées, des flux de paiement optimisés et une maîtrise complète du parcours client.

L'approche API-first répond à cette exigence. Au lieu d'intégrer un widget opaque, le développeur interagit directement avec une API REST pour créer des paiements, gérer les remboursements, stocker des cartes de manière sécurisée et recevoir des notifications en temps réel. Cette architecture offre une flexibilité totale : sites web, applications mobiles, ERP, plateformes SaaS ou marketplaces peuvent tous consommer la même API.

Ce guide s'adresse aux développeurs, architectes techniques et CTO qui souhaitent intégrer une solution de paiement au Maroc par API. Nous couvrirons le paysage des APIs disponibles, l'architecture technique, les endpoints principaux, le flux 3D Secure, les webhooks, la tokenisation, l'environnement de test et les bonnes pratiques de sécurité. Si vous évaluez une passerelle de paiement au Maroc, ce guide vous donnera les clés techniques pour faire le bon choix.

Paysage des APIs de paiement au Maroc

Le marché marocain propose plusieurs approches d'intégration de paiement, chacune avec un niveau de contrôle et de complexité différent.

Redirection (hosted payment page)

Le commerçant redirige le client vers une page de paiement hébergée par le prestataire. C'est l'approche historique du CMI au Maroc. Le développeur envoie les paramètres de la transaction via un formulaire POST, le client saisit sa carte sur la page du prestataire, puis est redirigé vers le site marchand avec le résultat. L'avantage est la simplicité et la conformité PCI (le commerçant ne touche jamais les données de carte). L'inconvénient est le manque de contrôle sur l'expérience utilisateur et le taux d'abandon lié à la redirection.

Formulaire embarqué (hosted fields / iframe)

Le prestataire fournit des champs de saisie sécurisés (hosted fields) qui s'intègrent visuellement dans le formulaire du commerçant. Le client ne quitte jamais le site. Les données de carte sont envoyées directement au prestataire via une iframe sécurisée. Le commerçant conserve le contrôle du design tout en restant hors scope PCI DSS pour le stockage des données sensibles.

API directe (server-to-server)

Le commerçant collecte les données de carte côté client (via un SDK JavaScript sécurisé), les tokenise, puis envoie le token à son serveur qui appelle l'API du prestataire. C'est l'approche la plus flexible mais elle exige une conformité PCI SAQ A-EP ou supérieure. Chari Pay propose cette approche avec un SDK client qui tokenise les données avant tout envoi au serveur du commerçant.

Comparatif rapide

Architecture API : principes fondamentaux

Une API de paiement bien conçue repose sur des conventions techniques standardisées. Voici les principes à maîtriser avant de commencer l'intégration.

REST et ressources

Les APIs de paiement modernes suivent le paradigme REST. Chaque entité (paiement, remboursement, client, carte) est une ressource accessible via un endpoint dédié. Les opérations standard utilisent les verbes HTTP : POST pour créer, GET pour lire, PUT/PATCH pour modifier, DELETE pour supprimer.

Authentification

L'authentification repose généralement sur des clés API (API keys). Un couple de clés est fourni : une clé publique (utilisable côté client pour la tokenisation) et une clé secrète (utilisable uniquement côté serveur pour les opérations sensibles). Les clés sont transmises via le header HTTP Authorization: Bearer {secret_key}. Certaines APIs proposent également OAuth 2.0 pour les architectures multi-tenant ou les plateformes marketplace.

Versioning

Les APIs sérieuses utilisent un versioning explicite, soit dans l'URL (/v1/payments), soit dans un header (API-Version: 2026-01). Le versioning garantit que votre intégration ne cassera pas lors d'une mise à jour de l'API. Vérifiez la politique de déprécation de votre prestataire avant de commencer.

Rate limiting

Les APIs imposent des limites de requêtes pour protéger l'infrastructure. Les limites typiques sont de 100 à 1000 requêtes par minute selon l'endpoint. Les headers de réponse (X-RateLimit-Remaining, X-RateLimit-Reset) vous permettent de gérer le throttling côté client. Implémentez un mécanisme de retry avec backoff exponentiel pour gérer les réponses 429 (Too Many Requests).

Format des réponses

Les réponses sont en JSON. Chaque réponse inclut un code HTTP standard (200 pour succès, 201 pour création, 400 pour erreur de validation, 401 pour authentification échouée, 404 pour ressource introuvable, 500 pour erreur serveur). Le corps de la réponse contient l'objet créé ou modifié, avec un identifiant unique, un statut et des métadonnées.

Endpoints principaux : le cycle de vie d'un paiement

L'intégration d'une API de paiement s'articule autour de quelques endpoints fondamentaux qui couvrent le cycle de vie complet d'une transaction.

Créer un paiement

L'endpoint POST /v1/payments crée une intention de paiement. Le corps de la requête contient le montant (en centimes), la devise (MAD), une référence unique côté commerçant, l'URL de retour client et l'URL de notification webhook. La réponse retourne un objet payment avec un identifiant unique, un statut pending et, selon le mode d'intégration, une URL de redirection ou un client_secret pour le SDK JavaScript.

Capturer un paiement

Si vous utilisez le mode de capture différée (authorize then capture), l'endpoint POST /v1/payments/{id}/capture déclenche le prélèvement effectif après une autorisation. Ce mode est utile pour les commerçants qui veulent vérifier la disponibilité du stock ou valider une commande avant de débiter le client.

Rembourser un paiement

L'endpoint POST /v1/payments/{id}/refunds crée un remboursement total ou partiel. Le corps de la requête contient le montant à rembourser (optionnel pour un remboursement total). Plusieurs remboursements partiels sont possibles tant que le montant cumulé ne dépasse pas le montant initial. Le délai de crédit sur le compte du client dépend de la banque émettrice (généralement 5 à 10 jours ouvrables au Maroc).

Consulter le statut

L'endpoint GET /v1/payments/{id} retourne l'état complet de la transaction : statut (pending, authorized, captured, refunded, failed), montant, devise, méthode de paiement, horodatage et historique des événements. Utilisez cet endpoint pour la réconciliation et le suivi des transactions dans votre back-office.

Lister les transactions

L'endpoint GET /v1/payments retourne une liste paginée des transactions avec des filtres disponibles : date, statut, montant, référence. La pagination utilise généralement un curseur ou un couple offset/limit. Cet endpoint alimente vos tableaux de bord, vos exports comptables et vos outils de reporting.

Flux 3D Secure : implémentation technique

Le 3D Secure est obligatoire au Maroc pour les paiements par carte en ligne. L'implémentation technique suit un flux en trois étapes.

Étape 1 : initiation

Lors de la création du paiement, l'API détecte automatiquement que la carte nécessite une authentification 3D Secure. La réponse contient un statut requires_action et un objet next_action avec le type redirect_to_3ds et l'URL d'authentification.

Étape 2 : authentification

Le client est redirigé vers la page d'authentification de sa banque (ou une iframe embarquée en 3DS 2.0). Il saisit le code OTP reçu par SMS ou valide par biométrie. En 3D Secure 2.0, l'analyse de risque peut déclencher un flux frictionless (sans intervention du client) pour les transactions à faible risque.

Étape 3 : callback et finalisation

Après l'authentification, le client est redirigé vers votre URL de retour. Simultanément, le webhook notifie votre serveur du résultat. Ne vous fiez jamais uniquement à la redirection client pour valider le paiement. Le webhook est la source de vérité. Vérifiez toujours le statut du paiement via l'endpoint GET avant de confirmer la commande.

Webhooks : notifications en temps réel

Les webhooks sont le mécanisme de notification server-to-server qui informe votre application des événements de paiement en temps réel. Ils sont indispensables pour une intégration fiable.

Configuration

Enregistrez une URL de webhook dans votre tableau de bord ou via l'API. L'URL doit être accessible publiquement via HTTPS. Sélectionnez les événements que vous souhaitez recevoir : payment.completed, payment.failed, payment.refunded, payment.disputed.

Vérification de signature

Chaque webhook est signé avec votre clé secrète. Le prestataire inclut une signature dans le header X-Webhook-Signature. Votre serveur doit recalculer la signature HMAC-SHA256 du corps de la requête et la comparer à celle reçue. Ne traitez jamais un webhook sans vérifier la signature - c'est une faille de sécurité critique.

Logique de retry

Si votre serveur ne répond pas avec un code 2xx dans un délai défini (généralement 5 à 30 secondes), le prestataire renvoie le webhook. Les retries suivent un backoff exponentiel : 1 minute, 5 minutes, 30 minutes, 2 heures, 24 heures. Après un nombre maximum de tentatives (généralement 5 à 10), le webhook est marqué comme échoué.

Idempotence

Un même événement peut être envoyé plusieurs fois (retries, doublons réseau). Votre handler doit être idempotent : traitez chaque événement une seule fois en stockant l'identifiant de l'événement et en vérifiant s'il a déjà été traité avant d'exécuter la logique métier. Sans idempotence, vous risquez de valider deux fois une commande ou d'envoyer deux emails de confirmation.

Tokenisation : stocker les cartes en toute sécurité

La tokenisation permet de stocker une référence sécurisée (token) à une carte bancaire sans manipuler les données sensibles. C'est la base des paiements en un clic et des abonnements récurrents.

Créer un token

Le SDK JavaScript côté client collecte les informations de carte et les envoie directement au serveur du prestataire. En retour, il reçoit un token unique (tok_xxxx) qui représente la carte. Ce token est transmis à votre serveur pour créer le paiement. Le commerçant ne voit jamais le numéro de carte complet.

Associer un token à un client

L'endpoint POST /v1/customers/{id}/payment-methods associe un token à un profil client. Le client peut ainsi retrouver ses cartes enregistrées lors de ses prochains achats. L'affichage se limite aux quatre derniers chiffres et au réseau (Visa, Mastercard).

Paiement par token (récurrence)

Pour débiter une carte enregistrée, appelez POST /v1/payments avec le payment_method_id au lieu d'un nouveau token. C'est le mécanisme utilisé pour les abonnements, les facturations récurrentes et les paiements en un clic. Le 3D Secure peut être requis lors du premier paiement mais exempté pour les suivants si la carte a été authentifiée et que le commerçant dispose d'un mandat de prélèvement.

Sandbox et environnement de test

Aucune intégration ne devrait être mise en production sans une phase de test exhaustive. L'environnement sandbox réplique le comportement de l'API de production avec des données fictives.

Accès au sandbox

Le sandbox est généralement accessible via un sous-domaine dédié (sandbox-api.example.com) ou une URL de base différente. Les clés API de test sont distinctes des clés de production. Toutes les transactions en sandbox sont simulées et n'engendrent aucun mouvement financier réel.

Cartes de test

Le prestataire fournit des numéros de carte de test pour simuler différents scénarios :

• Paiement réussi : carte de test standard, retourne un statut captured
• Paiement refusé : carte configurée pour déclencher un refus (fonds insuffisants, carte expirée)
• 3D Secure challenge : carte qui déclenche systématiquement l'authentification 3D Secure
• 3D Secure frictionless : carte qui passe en mode frictionless sans intervention
• Timeout : carte qui simule un délai de réponse dépassé

Scénarios à tester

Avant la mise en production, validez chaque scénario : paiement réussi, paiement refusé, remboursement total, remboursement partiel, timeout réseau, webhook reçu, webhook manquant, double soumission, montant invalide, devise incorrecte et expiration de session. Un test rigoureux en sandbox réduit considérablement les incidents en production.

Bonnes pratiques de sécurité

La sécurité n'est pas optionnelle dans le domaine du paiement. Voici les pratiques essentielles à implémenter.

HTTPS obligatoire

Toutes les communications avec l'API doivent transiter via HTTPS avec TLS 1.2 minimum. Refusez toute connexion non chiffrée. Vérifiez les certificats SSL et ne désactivez jamais la validation de certificat dans votre code, même en développement.

Gestion des clés API

Ne stockez jamais vos clés API dans le code source. Utilisez des variables d'environnement ou un gestionnaire de secrets (Vault, AWS Secrets Manager, Azure Key Vault). Différenciez les clés de test et de production. Mettez en place une rotation périodique des clés. Limitez les permissions de chaque clé au strict nécessaire.

Conformité PCI DSS

Le scope PCI dépend de votre mode d'intégration. Avec la tokenisation côté client (hosted fields ou SDK JavaScript), vous êtes en scope SAQ A ou SAQ A-EP, ce qui signifie que les données de carte ne transitent jamais par vos serveurs. Documentez votre mode d'intégration et remplissez le questionnaire d'auto-évaluation correspondant.

Validation des entrées

Validez systématiquement les montants, devises, références et paramètres avant de les envoyer à l'API. Protégez vos endpoints webhook contre les injections. Loguez les erreurs sans exposer les données sensibles (masquez les numéros de carte, ne loguez jamais les clés API).

Exemples de code : flux de paiement simplifié

Voici des exemples pseudocode illustrant un flux de paiement basique et un handler de webhook.

Créer un paiement (Node.js)

const response = await fetch('https://api.charipay.ma/v1/payments', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.CHARIPAY_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 15000,        // 150.00 MAD en centimes
    currency: 'MAD',
    reference: 'ORDER-2026-001',
    return_url: 'https://monsite.ma/paiement/retour',
    webhook_url: 'https://monsite.ma/api/webhooks/paiement',
    payment_method: tokenId,  // token obtenu via le SDK client
  }),
});

const payment = await response.json();

if (payment.status === 'requires_action') {
  // Rediriger le client vers l'URL 3D Secure
  return redirect(payment.next_action.redirect_url);
}

Handler de webhook (Python)

import hmac
import hashlib

@app.route('/api/webhooks/paiement', methods=['POST'])
def handle_webhook():
    payload = request.get_data()
    signature = request.headers.get('X-Webhook-Signature')

    # Vérifier la signature
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        return 'Signature invalide', 401

    event = request.get_json()

    # Vérifier l'idempotence
    if event_already_processed(event['id']):
        return 'OK', 200

    # Traiter l'événement
    if event['type'] == 'payment.completed':
        order = get_order(event['data']['reference'])
        order.mark_as_paid()
        send_confirmation_email(order)

    mark_event_processed(event['id'])
    return 'OK', 200

Ces exemples illustrent les principes fondamentaux. Adaptez-les à votre framework et à votre architecture. Consultez la documentation API de Chari Pay pour les spécifications complètes.

Comment ChariBaaS accélère votre intégration

ChariBaaS, à travers Chari Pay, fournit une infrastructure de paiement conçue pour les développeurs marocains. L'API REST est documentée de manière exhaustive avec des exemples dans plusieurs langages. Le sandbox permet de tester l'ensemble des scénarios sans risque. Les SDKs JavaScript, PHP et Python réduisent le temps d'intégration. Le support technique accompagne les équipes de développement pendant l'intégration et au-delà.

Que vous construisiez un site Shopify, une boutique WooCommerce ou une application sur mesure, l'API Chari Pay offre la flexibilité et la fiabilité nécessaires pour accepter les paiements en ligne et les virements bancaires au Maroc.

Pour démarrer votre intégration, consultez la documentation technique ou contactez notre équipe pour un accompagnement personnalisé.