Environnements et API keys
Comprendre les modes test et production, le format des clés et comment basculer sans risque.
Wajub fait tourner deux environnements isolés derrière une seule API. Même URL de base, mêmes endpoints, mêmes payloads. C'est la clé que vous envoyez qui décide auquel vous vous adressez : changer d'environnement revient à changer d'identifiant, jamais à réécrire du code.
https://api.wajub.comSandbox
La sandbox est l'endroit où vous développez. Les opérateurs Mobile Money y sont simulés par des numéros de test dont les six derniers chiffres décident du résultat, les webhooks se déclenchent exactement comme en production, et aucun argent ne circule jamais. Ses données vivent dans leur propre base, si bien qu'un client, un paiement ou un événement sandbox n'apparaît jamais dans votre compte live.
Les clés sont pk_test.… et sk_test.…, et chaque objet créé dans la sandbox porte test_ dans son id.
Production
La production déplace de l'argent réel. Elle s'ouvre une fois la vérification de votre entreprise approuvée : consultez Activation du compte et KYC pour les documents et les délais.
Les clés sont pk.… et sk.….
Ce que la sandbox ne couvre pas
La sandbox reproduit fidèlement le parcours de paiement, mais cinq fonctionnalités n'existent qu'en live.
Les appeler avec une clé de test renvoie 403 avec This feature is only available in live mode.
| Fonctionnalité | Endpoints | Sandbox |
|---|---|---|
| Liens de paiement | /links | Live uniquement |
| Factures | /invoices | Live uniquement |
| Taxes | /tax et /customers/{id}/tax_ids | Live uniquement |
| Shield | /shield | Live uniquement |
| Paiements, remboursements, transferts, clients, webhooks | Disponible |
Une autre différence joue en sens inverse : la page de paiement sandbox accepte des cartes de test et des cryptomonnaies pour que vous puissiez tester ces parcours de code, alors que la page live ne propose pour l'instant que Mobile Money. Développez avec Mobile Money, sinon vous validerez une intégration qui n'aura rien sur quoi s'exécuter en production.
Types de clés
| Type | Préfixe | Où elle s'exécute | Ce qu'elle peut faire |
|---|---|---|---|
| Publique | pk. / pk_test. | Navigateur, application mobile | Initialiser un paiement. Rien de sensible. |
| Privée | sk. / sk_test. | Votre serveur uniquement | Tout : paiements, remboursements, transferts, solde. |
| Restreinte | rk. / rk_test. | Votre serveur uniquement | Uniquement les scopes que vous lui accordez, une ressource à la fois. |
Une clé se compose d'un préfixe, d'un point, puis de 96 caractères aléatoires. Une clé privée de production fait donc 99 caractères, une clé sandbox 104. Stockez-les en texte, jamais dans une colonne de longueur fixe de 32 ou 64 caractères.
sk_test.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i……
# prefix "sk_test", a dot, then 96 charactersNe commitez jamais une clé privée
Gardez sk.… dans des variables d'environnement ou un gestionnaire de secrets. Si une clé fuite,
révoquez-la depuis Settings → Developer → API Keys dans le Dashboard. La rotation d'une clé génère
immédiatement une nouvelle valeur, et l'ancienne cesse de fonctionner dès la requête suivante.
Limiter ce qu'une clé peut faire
Trois contrôles existent sur chaque clé, et les activer ne coûte rien.
Des scopes, sur les clés restreintes. Une clé restreinte porte une liste explicite de permissions
{resource}.{read|write} : payment.read, payment.write, customer.read,
transfer.write, refund.write, recipient.*, invoice.*, dispute.*, webhook.*, event.*,
link.*, identity.*, settings.*, tax.*, plus balance.read et account.read en lecture seule.
Tout ce qui sort de la liste renvoie 403. Notez ce qui manque à cette liste : il n'existe pas de
balance.write, une clé restreinte ne peut donc jamais sortir des fonds à elle seule.
Une liste d'IP autorisées. Chaque clé accepte une liste d'adresses ou de plages CIDR. Une requête
venant de n'importe où ailleurs est refusée avec 403 IP address not allowed for this API key, quel que
soit le type de clé. Une clé qui ne fonctionne que depuis vos serveurs de production ne vaut rien dans un
dépôt divulgué.
Une date d'expiration. Une clé peut porter expires_at. Passé ce moment, elle n'authentifie plus rien.
Utilisez-la pour un sous-traitant, un script de migration ou toute intégration que vous savez temporaire.
Variables d'environnement
Trois noms suffisent pour une intégration serveur. Gardez-les dans l'environnement plutôt que dans le code, et nommez-les exactement ainsi : les SDKs cherchent ces noms et aucun autre.
WAJUB_API_KEY=sk_test.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i……
WAJUB_WEBHOOK_SECRET=whsec_test_4f8c2b91d7e6a0f35c1dB7nY4hC6dF9j
WAJUB_PUBLIC_KEY=pk_test.mT9xW2kQ7vB4nL6hR1cY8dF3jS5aG0eU2pA……WAJUB_API_KEY est l'identifiant d'authentification. Les SDKs Python et Go la lisent eux-mêmes dans
l'environnement, si bien qu'une configuration vide vous donne un client qui fonctionne. Les SDKs Node et
PHP ne le font pas : ils lèvent une erreur sur une configuration vide et attendent que vous passiez la
valeur. Consultez Configurer votre compte
pour la forme exacte dans chaque langage.
WAJUB_WEBHOOK_SECRET est la seule que les quatre lisent automatiquement. Définissez-la et la
vérification de signature fonctionne sans que vous ayez à passer le secret nulle part.
WAJUB_PUBLIC_KEY n'est lue par aucun SDK. Elle sert à votre propre code frontend, et seulement si votre
navigateur ou votre client mobile initialise lui-même les paiements.
Les valeurs de production ont leur place dans votre gestionnaire de secrets, jamais dans un fichier commité. La configuration la plus sûre sépare les variables de sandbox et de production, pour que la mise en production de votre code n'oblige jamais à modifier une clé à la main.
Passer en production
- Finalisez la vérification de votre entreprise dans le Dashboard. Consultez Activation du compte et KYC pour les documents requis et les délais d'examen.
- Créez des clés de production. Les clés sandbox ne peuvent pas être promues, ce sont des objets distincts.
- Faites pointer vos endpoints de webhook vers leurs URLs de production et copiez le nouveau secret de signature : il diffère selon l'environnement.
- Testez à nouveau les fonctionnalités marquées « Live uniquement » dans le tableau ci-dessus. C'est la première fois que votre code s'exécute avec elles.
- Suivez le guide Passer en live pour la checklist complète.