Sandbox → production : la liste avant de basculer

La sandbox est ouverte immédiatement. 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 — 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. 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.

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.

Ce que la sandbox permet et que la production interdit

Un endpoint force la prochaine échéance d'un abonnement. Il n'existe qu'en sandbox, et c'est ce qui vous permet de dérouler une année d'abonnement en une minute : créez l'abonnement, forcez trois échéances, vérifiez que votre facturation suit, que votre relance fonctionne, 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.

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.

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.