API de paiement au Maroc : guide d'integration technique 2026

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

Le marche du paiement en ligne au Maroc a atteint une maturite technique qui exige desormais des integrations robustes, programmatiques et scalables. Les commercants marocains ne se contentent plus de formulaires de paiement generiques redirigeant vers des pages bancaires. Ils veulent des experiences embarquees, des flux de paiement optimises et une maitrise complete du parcours client.

L'approche API-first repond a cette exigence. Au lieu d'integrer un widget opaque, le developpeur interagit directement avec une API REST pour creer des paiements, gerer les remboursements, stocker des cartes de maniere securisee et recevoir des notifications en temps reel. Cette architecture offre une flexibilite totale : sites web, applications mobiles, ERP, plateformes SaaS ou marketplaces peuvent tous consommer la meme API.

Ce guide s'adresse aux developpeurs, architectes techniques et CTO qui souhaitent integrer 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 securite. Si vous evaluez une passerelle de paiement au Maroc, ce guide vous donnera les cles techniques pour faire le bon choix.

Paysage des APIs de paiement au Maroc

Le marche marocain propose plusieurs approches d'integration de paiement, chacune avec un niveau de controle et de complexite different.

Redirection (hosted payment page)

Le commercant redirige le client vers une page de paiement hebergee par le prestataire. C'est l'approche historique du CMI au Maroc. Le developpeur envoie les parametres de la transaction via un formulaire POST, le client saisit sa carte sur la page du prestataire, puis est redirige vers le site marchand avec le resultat. L'avantage est la simplicite et la conformite PCI (le commercant ne touche jamais les donnees de carte). L'inconvenient est le manque de controle sur l'experience utilisateur et le taux d'abandon lie a la redirection.

Formulaire embarque (hosted fields / iframe)

Le prestataire fournit des champs de saisie securises (hosted fields) qui s'integrent visuellement dans le formulaire du commercant. Le client ne quitte jamais le site. Les donnees de carte sont envoyees directement au prestataire via une iframe securisee. Le commercant conserve le controle du design tout en restant hors scope PCI DSS pour le stockage des donnees sensibles.

API directe (server-to-server)

Le commercant collecte les donnees de carte cote client (via un SDK JavaScript securise), les tokenise, puis envoie le token a son serveur qui appelle l'API du prestataire. C'est l'approche la plus flexible mais elle exige une conformite PCI SAQ A-EP ou superieure. Chari Pay propose cette approche avec un SDK client qui tokenise les donnees avant tout envoi au serveur du commercant.

Comparatif rapide

Architecture API : principes fondamentaux

Une API de paiement bien concue repose sur des conventions techniques standardisees. Voici les principes a maitriser avant de commencer l'integration.

REST et ressources

Les APIs de paiement modernes suivent le paradigme REST. Chaque entite (paiement, remboursement, client, carte) est une ressource accessible via un endpoint dedie. Les operations standard utilisent les verbes HTTP : POST pour creer, GET pour lire, PUT/PATCH pour modifier, DELETE pour supprimer.

Authentification

L'authentification repose generalement sur des cles API (API keys). Un couple de cles est fourni : une cle publique (utilisable cote client pour la tokenisation) et une cle secrete (utilisable uniquement cote serveur pour les operations sensibles). Les cles sont transmises via le header HTTP Authorization: Bearer {secret_key}. Certaines APIs proposent egalement OAuth 2.0 pour les architectures multi-tenant ou les plateformes marketplace.

Versioning

Les APIs serieuses utilisent un versioning explicite, soit dans l'URL (/v1/payments), soit dans un header (API-Version: 2026-01). Le versioning garantit que votre integration ne cassera pas lors d'une mise a jour de l'API. Verifiez la politique de deprecation de votre prestataire avant de commencer.

Rate limiting

Les APIs imposent des limites de requetes pour proteger l'infrastructure. Les limites typiques sont de 100 a 1000 requetes par minute selon l'endpoint. Les headers de reponse (X-RateLimit-Remaining, X-RateLimit-Reset) vous permettent de gerer le throttling cote client. Implementez un mecanisme de retry avec backoff exponentiel pour gerer les reponses 429 (Too Many Requests).

Format des reponses

Les reponses sont en JSON. Chaque reponse inclut un code HTTP standard (200 pour succes, 201 pour creation, 400 pour erreur de validation, 401 pour authentification echouee, 404 pour ressource introuvable, 500 pour erreur serveur). Le corps de la reponse contient l'objet cree ou modifie, avec un identifiant unique, un statut et des metadonnees.

Endpoints principaux : le cycle de vie d'un paiement

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

Creer un paiement

L'endpoint POST /v1/payments cree une intention de paiement. Le corps de la requete contient le montant (en centimes), la devise (MAD), une reference unique cote commercant, l'URL de retour client et l'URL de notification webhook. La reponse retourne un objet payment avec un identifiant unique, un statut pending et, selon le mode d'integration, une URL de redirection ou un client_secret pour le SDK JavaScript.

Capturer un paiement

Si vous utilisez le mode de capture differee (authorize then capture), l'endpoint POST /v1/payments/{id}/capture declenche le prelevement effectif apres une autorisation. Ce mode est utile pour les commercants qui veulent verifier la disponibilite du stock ou valider une commande avant de debiter le client.

Rembourser un paiement

L'endpoint POST /v1/payments/{id}/refunds cree un remboursement total ou partiel. Le corps de la requete contient le montant a rembourser (optionnel pour un remboursement total). Plusieurs remboursements partiels sont possibles tant que le montant cumule ne depasse pas le montant initial. Le delai de credit sur le compte du client depend de la banque emettrice (generalement 5 a 10 jours ouvrables au Maroc).

Consulter le statut

L'endpoint GET /v1/payments/{id} retourne l'etat complet de la transaction : statut (pending, authorized, captured, refunded, failed), montant, devise, methode de paiement, horodatage et historique des evenements. Utilisez cet endpoint pour la reconciliation et le suivi des transactions dans votre back-office.

Lister les transactions

L'endpoint GET /v1/payments retourne une liste paginee des transactions avec des filtres disponibles : date, statut, montant, reference. La pagination utilise generalement 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 : implementation technique

Le 3D Secure est obligatoire au Maroc pour les paiements par carte en ligne. L'implementation technique suit un flux en trois etapes.

Etape 1 : initiation

Lors de la creation du paiement, l'API detecte automatiquement que la carte necessite une authentification 3D Secure. La reponse contient un statut requires_action et un objet next_action avec le type redirect_to_3ds et l'URL d'authentification.

Etape 2 : authentification

Le client est redirige vers la page d'authentification de sa banque (ou une iframe embarquee en 3DS 2.0). Il saisit le code OTP recu par SMS ou valide par biometrie. En 3D Secure 2.0, l'analyse de risque peut declencher un flux frictionless (sans intervention du client) pour les transactions a faible risque.

Etape 3 : callback et finalisation

Apres l'authentification, le client est redirige vers votre URL de retour. Simultanement, le webhook notifie votre serveur du resultat. Ne vous fiez jamais uniquement a la redirection client pour valider le paiement. Le webhook est la source de verite. Verifiez toujours le statut du paiement via l'endpoint GET avant de confirmer la commande.

Webhooks : notifications en temps reel

Les webhooks sont le mecanisme de notification server-to-server qui informe votre application des evenements de paiement en temps reel. Ils sont indispensables pour une integration fiable.

Configuration

Enregistrez une URL de webhook dans votre tableau de bord ou via l'API. L'URL doit etre accessible publiquement via HTTPS. Selectionnez les evenements que vous souhaitez recevoir : payment.completed, payment.failed, payment.refunded, payment.disputed.

Verification de signature

Chaque webhook est signe avec votre cle secrete. Le prestataire inclut une signature dans le header X-Webhook-Signature. Votre serveur doit recalculer la signature HMAC-SHA256 du corps de la requete et la comparer a celle recue. Ne traitez jamais un webhook sans verifier la signature -- c'est une faille de securite critique.

Logique de retry

Si votre serveur ne repond pas avec un code 2xx dans un delai defini (generalement 5 a 30 secondes), le prestataire renvoie le webhook. Les retries suivent un backoff exponentiel : 1 minute, 5 minutes, 30 minutes, 2 heures, 24 heures. Apres un nombre maximum de tentatives (generalement 5 a 10), le webhook est marque comme echoue.

Idempotence

Un meme evenement peut etre envoye plusieurs fois (retries, doublons reseau). Votre handler doit etre idempotent : traitez chaque evenement une seule fois en stockant l'identifiant de l'evenement et en verifiant s'il a deja ete traite avant d'executer la logique metier. Sans idempotence, vous risquez de valider deux fois une commande ou d'envoyer deux emails de confirmation.

Tokenisation : stocker les cartes en toute securite

La tokenisation permet de stocker une reference securisee (token) a une carte bancaire sans manipuler les donnees sensibles. C'est la base des paiements en un clic et des abonnements recurrents.

Creer un token

Le SDK JavaScript cote client collecte les informations de carte et les envoie directement au serveur du prestataire. En retour, il recoit un token unique (tok_xxxx) qui represente la carte. Ce token est transmis a votre serveur pour creer le paiement. Le commercant ne voit jamais le numero de carte complet.

Associer un token a un client

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

Paiement par token (recurrence)

Pour debiter une carte enregistree, appelez POST /v1/payments avec le payment_method_id au lieu d'un nouveau token. C'est le mecanisme utilise pour les abonnements, les facturations recurrentes et les paiements en un clic. Le 3D Secure peut etre requis lors du premier paiement mais exempte pour les suivants si la carte a ete authentifiee et que le commercant dispose d'un mandat de prelevement.

Sandbox et environnement de test

Aucune integration ne devrait etre mise en production sans une phase de test exhaustive. L'environnement sandbox replique le comportement de l'API de production avec des donnees fictives.

Acces au sandbox

Le sandbox est generalement accessible via un sous-domaine dedie (sandbox-api.example.com) ou une URL de base differente. Les cles API de test sont distinctes des cles de production. Toutes les transactions en sandbox sont simulees et n'engendrent aucun mouvement financier reel.

Cartes de test

Le prestataire fournit des numeros de carte de test pour simuler differents scenarios :

• Paiement reussi : carte de test standard, retourne un statut captured
• Paiement refuse : carte configuree pour declencher un refus (fonds insuffisants, carte expiree)
• 3D Secure challenge : carte qui declenche systematiquement l'authentification 3D Secure
• 3D Secure frictionless : carte qui passe en mode frictionless sans intervention
• Timeout : carte qui simule un delai de reponse depasse

Scenarios a tester

Avant la mise en production, validez chaque scenario : paiement reussi, paiement refuse, remboursement total, remboursement partiel, timeout reseau, webhook recu, webhook manquant, double soumission, montant invalide, devise incorrecte et expiration de session. Un test rigoureux en sandbox reduit considerablement les incidents en production.

Bonnes pratiques de securite

La securite n'est pas optionnelle dans le domaine du paiement. Voici les pratiques essentielles a implementer.

HTTPS obligatoire

Toutes les communications avec l'API doivent transiter via HTTPS avec TLS 1.2 minimum. Refusez toute connexion non chiffree. Verifiez les certificats SSL et ne desactivez jamais la validation de certificat dans votre code, meme en developpement.

Gestion des cles API

Ne stockez jamais vos cles API dans le code source. Utilisez des variables d'environnement ou un gestionnaire de secrets (Vault, AWS Secrets Manager, Azure Key Vault). Differenciez les cles de test et de production. Mettez en place une rotation periodique des cles. Limitez les permissions de chaque cle au strict necessaire.

Conformite PCI DSS

Le scope PCI depend de votre mode d'integration. Avec la tokenisation cote client (hosted fields ou SDK JavaScript), vous etes en scope SAQ A ou SAQ A-EP, ce qui signifie que les donnees de carte ne transitent jamais par vos serveurs. Documentez votre mode d'integration et remplissez le questionnaire d'auto-evaluation correspondant.

Validation des entrees

Validez systematiquement les montants, devises, references et parametres avant de les envoyer a l'API. Protegez vos endpoints webhook contre les injections. Loguez les erreurs sans exposer les donnees sensibles (masquez les numeros de carte, ne loguez jamais les cles API).

Exemples de code : flux de paiement simplifie

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

Creer 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')

    # Verifier 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()

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

    # Traiter l'evenement
    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 a votre framework et a votre architecture. Consultez la documentation API de Chari Pay pour les specifications completes.

Comment ChariBaaS accelere votre integration

ChariBaaS, a travers Chari Pay, fournit une infrastructure de paiement concue pour les developpeurs marocains. L'API REST est documentee de maniere exhaustive avec des exemples dans plusieurs langages. Le sandbox permet de tester l'ensemble des scenarios sans risque. Les SDKs JavaScript, PHP et Python reduisent le temps d'integration. Le support technique accompagne les equipes de developpement pendant l'integration et au-dela.

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

Pour demarrer votre integration, consultez la documentation technique ou contactez notre equipe pour un accompagnement personnalise.

FAQ

Quelles APIs de paiement sont disponibles au Maroc ?

Principales APIs : Chari Pay (REST API moderne, sandbox, documentation complete), CMI (API e-commerce, redirection), Payzone (API multi-canal). Chari Pay offre l'API la plus complete avec endpoints pour paiements, remboursements, tokenisation, recurrence et webhooks.

Comment tester une integration de paiement au Maroc ?

Utilisez l'environnement sandbox du fournisseur. Chari Pay fournit un sandbox complet avec cartes de test, simulation 3D Secure, et webhooks de test. Testez tous les scenarios : paiement reussi, refuse, 3D Secure, remboursement, et timeout.

Les webhooks sont-ils necessaires pour une integration paiement ?

Oui, les webhooks sont essentiels. Ils vous notifient en temps reel du resultat des transactions (succes, echec, remboursement). Ne vous fiez jamais uniquement a la redirection client -- le webhook est la source de verite cote serveur.

Combien de temps prend une integration API de paiement au Maroc ?

Avec une API moderne comme Chari Pay : 2-5 jours pour une integration basique (paiement simple), 1-2 semaines pour une integration complete (recurrence, tokenisation, webhooks). La documentation et le sandbox accelerent considerablement le processus.