Authentification
L’API publique s’authentifie par clé API, envoyée dans l’en-tête
X-API-Key à chaque requête.
curl https://api.kadryza.app/v1/payment-sessions/by-reference?reference=order_2026_001 \
-H "X-API-Key: $KADRYZA_API_KEY"const response = await fetch('https://api.kadryza.app/v1/payment-sessions', {
method: 'POST',
headers: {
'X-API-Key': process.env.KADRYZA_API_KEY!,
'Content-Type': 'application/json'
},
body: JSON.stringify({ reference: 'order_2026_001', amount: 5000, currency: 'XAF', operator: 'AIRTEL' })
})Le SDK envoie la clé automatiquement : new Kadryza({ apiKey }).
⚠️
Une clé API ne doit jamais atteindre un navigateur, une application mobile ou un dépôt de code. Appelez l’API depuis votre serveur uniquement.
Clés API
| Préfixe | Environnement | Effet |
|---|---|---|
kadryza_test_ | Test | Données de test isolées, aucun argent réel |
kadryza_live_ | Live | Paiements réels, après activation du compte |
- Format : préfixe suivi de 32 caractères alphanumériques.
- Créées depuis le dashboard, affichées une seule fois : Kadryza n’en conserve qu’une empreinte.
- La création d’une clé live demande une confirmation récente de votre second facteur d’authentification dans le dashboard.
- Révocables à tout moment ; une clé révoquée répond
401 API_KEY_UNAUTHORIZED.
L’environnement est déterminé par la clé, pas par l’URL : test et live
utilisent https://api.kadryza.app. Voir Test et production.
Conditions d’utilisation
Une clé valide ne suffit pas : le compte doit aussi remplir ces conditions.
| Condition | Erreur sinon |
|---|---|
| E-mail du compte vérifié | 403 EMAIL_NOT_VERIFIED |
| Profil marchand complet (raison sociale, adresse, téléphone, type d’activité) | 403 KYC_REQUIRED |
| Portée adaptée à l’opération | 403 API_KEY_PERMISSION_DENIED |
| Mode live activé par Kadryza (clé live uniquement) | 403 LIVE_MODE_NOT_ALLOWED |
Portées
| Portée | Autorise |
|---|---|
write_transactions | Créer et annuler des Payment Sessions, créer des Hosted Checkouts, créer des transactions |
read_transactions | Lire les Payment Sessions, leur historique de webhooks, les transactions |
manage_webhooks | Gérer les endpoints webhook |
read_stats | Réservée aux statistiques |
Erreurs d’authentification
| HTTP | code | Cause |
|---|---|---|
| 401 | API_KEY_MISSING | En-tête absent |
| 401 | API_KEY_INVALID_FORMAT | Préfixe inconnu (espace ou guillemet en trop ?) |
| 401 | API_KEY_UNAUTHORIZED | Clé inconnue ou révoquée |
Bonnes pratiques
- Stockez les clés dans un gestionnaire de secrets ou des variables d’environnement serveur.
- Une clé par environnement et par service ; révoquez celle d’un service retiré.
- Ne journalisez jamais une clé complète.
- Révoquez immédiatement une clé exposée, puis remplacez-la.
Le dashboard n’utilise pas les clés API
Le dashboard Kadryza authentifie ses utilisateurs par identifiant, mot de passe et second facteur, avec des sessions révocables. Ces sessions ne donnent pas accès à l’API publique, et une clé API ne donne pas accès au dashboard.