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. Elle ne partage aucune donnée avec le mode live, 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 propose toujours une carte de test pour que vous puissiez tester ce parcours de code, alors que la page live ne propose que les canaux couverts par vos prestataires actifs. Une carte n'y apparaît qu'une fois un prestataire qui accepte les cartes activé sur votre compte. Développez d'abord avec Mobile Money.
Types de clés
| Type | Préfixe | Où elle s'exécute | Ce qu'elle peut faire |
|---|---|---|---|
| Publique | pk. / pk_test. | Navigateur, application mobile | Créer un paiement depuis la page. La détenir n'est pas une autorisation : voir les endpoints qui l'acceptent. |
| 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 d'une longue partie secrète aléatoire. Stockez les clés en texte, jamais dans une colonne de longueur fixe de 32 ou 64 caractères.
sk_test.xxxxxxxxxxxxxxxx…
# prefix "sk_test", a dot, then the random secretNe 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.*, tax.*, plus balance.read et account.read en lecture seule.
Tout ce qui sort de la liste renvoie 403. Il n'existe pas de balance.write, mais transfer.write
suffit pour envoyer des payouts avec POST /transfers : ne l'accordez qu'à une clé dont le rôle est de
payer quelqu'un.
Une liste d'IP autorisées. Chaque clé accepte une liste d'adresses IPv4 ou IPv6 exactes, ou de
plages CIDR de l'une ou l'autre famille, comme 203.0.113.0/24 ou 2001:db8::/32. Vous la saisissez
à la création de la clé, et vous pouvez la modifier ensuite, quel que soit le type de clé. 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.
Vous la fixez à la création de la clé, vous la changez ou la retirez ensuite, quel que soit le type
de clé, et elle s'affiche à côté de la clé dans la liste. Modifier autre chose sur une clé laisse
son expiration telle qu'elle était.
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.xxxxxxxxxxxxxxxx…
WAJUB_WEBHOOK_SECRET=whsec_test_xxxxxxxxxxxxxxxx
WAJUB_PUBLIC_KEY=pk_test.xxxxxxxxxxxxxxxx…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.