Sandbox → production : la liste avant de basculer

La sandbox est ouverte immédiatement : Commencer en mode test ne demande aucune validation, et l'accès reste gratuit, sans limite de durée. La production s'active sur votre compte après vérification de votre entreprise. Entre les deux, il n'y a qu'une clé à changer — une seule base, deux clés : les URL, les payloads et les codes d'erreur sont identiques.

C'est justement parce que la bascule est si simple qu'elle mérite une liste. Elle prolonge le guide Démarrer de la documentation API ; voici celle que nous parcourons avec les intégrateurs.

Ce qui doit être vrai avant

Votre traitement de webhooks vérifie la signature. Sur le corps brut, avant tout parsing. Si vous ne l'avez pas testé avec un événement de test, vous ne l'avez pas testé.

Votre traitement de webhooks est idempotent. Une même notification peut arriver deux fois. Si votre code expédie une commande à chaque réception, cela finira par se voir.

Vos créations envoient une clé d'idempotence. Dérivée de votre propre référence de commande, pas d'un tirage aléatoire.

Vous journalisez le `correlationId`. Il est renvoyé sur chaque réponse, succès compris. C'est ce que le support vous demandera, et c'est ce qui transforme une enquête d'une journée en une recherche de trente secondes.

Vos clés sont dans un coffre. Pas dans le dépôt, pas dans un fichier de configuration versionné, pas dans le message d'un canal d'équipe. Les règles complètes sont dans protéger ses clés d'API.

Vous avez testé autre chose que le cas nominal. Au minimum : un paiement refusé, un remboursement, un remboursement partiel, et un webhook auquel votre serveur répond une erreur — pour voir ce qui se passe quand nous rejouons.

Dérouler un abonnement en sandbox

Pour la facturation récurrente, n'attendez pas le calendrier réel : raccourcissez-le. Créez en sandbox un abonnement avec une startDate du jour et la périodicité DAILY : le premier lien de paiement est créé immédiatement, vous le payez avec la carte de test, et une nouvelle échéance s'ouvre chaque jour. En trois jours, vous avez vu trois échéances : vérifiez que votre facturation suit, que votre traitement d'une échéance laissée impayée fonctionne — votre client reçoit alors un rappel par e-mail chaque jour, avec le même lien —, et que la résiliation s'enregistre.

Faites-le. C'est le seul moyen de découvrir un bug de facturation récurrente avant qu'il ne touche un vrai client. Les autres scénarios à dérouler avant la bascule sont réunis dans tester un paiement en mode test.

Le jour J

Vous changez la clé. C'est tout.

Si la production n'est pas encore activée sur votre compte, la clé de production reçoit un 403 explicite avec le code PRODUCTION_ACCESS_NOT_ENABLED — ce n'est pas un bug d'intégration, c'est une étape administrative : la vérification de l'entreprise et la mise en service, réglée une fois au passage en production.

Gardez la clé de test active : vous en aurez besoin pour vos environnements de recette, et il est bien plus sain de tester une évolution en sandbox que « prudemment » en production.

Les trois oublis classiques

Le secret de webhook. La sandbox et la production signent avec des secrets différents. L'intégration qui bascule la clé d'API mais garde l'ancien secret rejette silencieusement toutes les notifications de production — les paiements passent, les commandes ne partent pas, et l'incident ressemble à tout sauf à sa cause.

Les montants de test dans le code. Un amount: 100 laissé d'un test, une remise de démonstration, un plafond artificiel : relisez tout ce qui touche au montant avec la question « d'où vient ce nombre ? ». En production, chaque nombre doit venir de votre base, jamais d'un fichier.

Les e-mails et URLs de développement. L'adresse de notification qui pointe encore vers l'e-mail du développeur, l'URL de retour vers localhost : la sandbox pardonne, la production expose. Une recherche de localhost, test@ et .dev dans la configuration prend deux minutes.

Séparer les environnements, durablement

Le passage en production n'est pas une migration, c'est une séparation : la sandbox continue d'exister, et c'est votre meilleur outil pour la suite.

Gardez un environnement de votre application branché en permanence sur la sandbox. C'est là que se testent la prochaine fonctionnalité, la montée de version, le nouveau webhook — avec des données fictives et des paiements sans conséquence. Les équipes qui suppriment leur intégration sandbox le jour du lancement se retrouvent trois mois plus tard à tester une modification de leur tunnel de paiement... en production, sur de vraies cartes.

Concrètement : deux jeux de variables d'environnement, jamais mélangés dans un même fichier ; des clés nommées par environnement dans votre gestionnaire de secrets ; et l'interdiction technique — pas seulement culturelle — d'appeler l'API de production depuis un poste de développement.

La semaine suivante

Regardez trois choses tous les jours pendant une semaine :

• le journal des livraisons de webhooks — un endpoint qui accumule les échecs finit suspendu ;
• le rapprochement quotidien — si vos totaux ne tombent pas dès la première semaine, ils ne tomberont pas mieux au bout d'un mois ;
• les paiements en attente qui expirent — un taux élevé signale un problème de parcours, pas de banque.

Un encaissement qui fonctionne se reconnaît à ceci : plus personne n'en parle.

Prochaine étape

Si vous n'avez pas encore de compte de test, Commencer en mode test prend trois champs — nom, e-mail professionnel, entreprise — puis un mot de passe choisi depuis le lien d'activation reçu par e-mail. Créez votre clé de test depuis le portail, déroulez cette liste avec la carte de test, et ne pensez à la vérification de l'entreprise qu'au moment de passer en production. Le guide API de paiement au Maroc reprend l'intégration de bout en bout.