Une API REST pour encaisser au Maroc par carte ou en espèces en agence : une seule base d'URL, une clé qui choisit l'environnement, l'idempotence, des erreurs explicites et des webhooks signés. Le mode test s'ouvre dès votre inscription — gratuit, sans limite de durée, sans validation à attendre : vous intégrez aujourd'hui, sans attendre personne.
Sandbox et production partagent la même adresse : https://api-psp.charipay.ma. C'est la clé envoyée dans l'en-tête X-CHARI-PAY-API-KEY qui décide : chari_sk_test_… opère sur les données de test, chari_sk_live_… sur les données réelles, sans OAuth ni jeton à rafraîchir. Tant que la production n'est pas activée, une clé live reçoit 403 PRODUCTION_ACCESS_NOT_ENABLED. Le jour J, vous changez la clé et le secret de webhook, pas votre code.
Un incident réseau ne doit jamais facturer deux fois. L'en-tête Idempotency-Key couvre le rejeu technique d'une même requête ; le champ externalId, unique par compte et par environnement, couvre la ré-émission métier : si l'objet existe déjà, l'API le renvoie en 200 au lieu de le créer en 201. Les remboursements suivent la même logique avec une refundReference déterministe : 202 à la création, 200 au rejeu. Gardez des Idempotency-Key distinctes entre sandbox et production.
Une enveloppe unique, { "error": { "code", "message" }, "correlationId" }, et un code machine stable : testez le code, jamais le message. Le correlationId accompagne chaque réponse, succès comme erreur ; envoyez un X-Request-Id et il devient votre correlationId, pour suivre un appel de bout en bout. Les statuts HTTP disent le reste : 400, 401, 403, 404, 409, 410, 422, 429.
Les endpoints exposés au public annoncent X-RateLimit-Limit, -Remaining et -Reset, et répondent 429 avec Retry-After en cas de dépassement. Les montants sont en dirhams, en unités majeures (149.90 = 149,90 MAD), les horodatages en ISO-8601 UTC ; les listes se paginent par page et size, et par curseur sur les transactions. Toute URL que vous déclarez doit être en HTTPS.
Une clé par entreprise et par environnement, des permissions (scopes) par module : chaque clé ne reçoit que ce dont elle a besoin. Vous la créez vous-même depuis le portail, après une ré-authentification ; la clé complète ne s'affiche qu'une seule fois et n'est jamais envoyée par e-mail. Deux clés peuvent coexister le temps d'une rotation, sans coupure.
Chaque événement porte X-CHARI-SIGNATURE, un HMAC-SHA256 calculé sur l'horodatage et le corps brut, et X-CHARI-TIMESTAMP en millisecondes : comparez en temps constant et rejetez tout écart de plus de cinq minutes. Dédupliquez sur Chari-Event-Id, stable d'une tentative à l'autre : la livraison est garantie au moins une fois, pas forcément dans l'ordre. Les secrets de signature diffèrent entre sandbox et production.
Tout se règle depuis le portail, sans passer par nous : vous créez vos clés de test et choisissez leurs permissions, déclarez vos URL de réception et la liste des événements que chacune reçoit, envoyez un événement de test, puis relisez chaque livraison avec le code que votre serveur a renvoyé. Une livraison échouée se rejoue en un clic, et la double authentification (TOTP) est disponible pour protéger l'accès.
Vérifiez la signature avant de lire le corps, dédupliquez par identifiant d'événement, répondez 2xx dès que l'événement est enregistré : la plateforme s'occupe du reste. Sans réponse 2xx, elle retente immédiatement, puis après 1 min, 5 min, 30 min et 1 h, ensuite toutes les 6 h, jusqu'à 16 tentatives sur environ 72 heures ; au-delà, la livraison est marquée échouée et se rejoue depuis le portail. Vingt événements sont documentés — paiements, abonnements, remboursements, mouvements du compte de paiement, distribution — et vous choisissez ceux que reçoit chaque endpoint. Pendant une rotation de secret, l'en-tête X-CHARI-SIGNATURE-NEXT porte la signature calculée avec le nouveau secret.
// En-têtes reçusX-CHARI-SIGNATURE: a3f19c… (HMAC-SHA256)X-CHARI-TIMESTAMP: 1756166400000Chari-Event-Id: 9f2c31a4-…Chari-Event-Type: payment.succeeded // Corps — signé tel quel, octet par octet{ … }Le mode test est un environnement complet — clés d'API, liens de paiement, sessions de checkout, abonnements, remboursements, webhooks — ouvert dès votre inscription. Trois champs (nom, e-mail professionnel, entreprise), un lien d'activation reçu par e-mail, le choix de votre mot de passe : vous voilà dans le portail, où vous créez vous-même votre clé de test. Payez ensuite avec la carte de test 4918 9141 0719 5005, CVV 123, n'importe quelle date d'expiration future et le code 3-D Secure 555 : vous voyez le parcours de votre client et recevez le webhook payment.succeeded. Seule cette carte est acceptée en sandbox, et aucun argent réel ne circule. C'est gratuit, sans limite de durée, sans carte bancaire à fournir ni engagement, et aucune validation n'est à attendre : la vérification de votre entreprise (KYB) se fait en parallèle et ne conditionne que le passage en production. Les huit étapes de l'inscription sont aussi documentées en appels d'API, pour qui veut tout automatiser.
La référence complète — 13 modules, 58 endpoints, exemples en curl, JavaScript, Python et PHP — est publiée sur ce site, en accès libre et sans compte. Elle est générée depuis la spécification OpenAPI de l'API ; la collection Postman et la spécification se téléchargent, tout comme un pack pour assistants de code — un fichier Markdown par module, les guides, la carte de test et la spécification.
Inscription sur le portail, activation par e-mail, choix du mot de passe : votre clé de test se crée depuis l'espace développeur et s'affiche une seule fois. Rien à payer, rien à signer, aucun document à fournir à ce stade.
Liens de paiement, checkout hébergé, abonnements, remboursements, webhooks : tout fonctionne en sandbox avec la carte de test. Pour un abonnement, une date de début au jour même ouvre la première échéance immédiatement, et une périodicité quotidienne fait venir la suivante dès le lendemain. Les webhooks partent normalement en sandbox : vérifiez signature, déduplication et réponses 2xx avant le jour J.
Quand vous êtes prêt : vérification KYB (documents d'identité et registre de commerce, avec double validation humaine), proposition chiffrée, mise en service de 6 000 MAD TTC réglée une seule fois, puis activation. Vous remplacez la clé de test par la clé de production, ainsi que le secret de webhook : le reste de votre code ne change pas.
Créez votre compte de test : gratuit, sans limite de durée, sans validation à attendre. Votre clé de test se crée depuis le portail, votre premier paiement passe avec la carte de test — et si vous préférez, parlez-nous d'abord de votre intégration.