Référence API

L’API publique Kadryza permet à votre serveur de créer des paiements Mobile Money, de suivre leur statut et de gérer vos endpoints webhook.

En bref

Aspect	Convention
URL de base	`https://api.kadryza.app`
Versionnement	Préfixe de chemin `/v1`
Authentification	En-tête `X-API-Key` (détails)
Environnement	Déduit de la clé : `kadryza_test_…` ou `kadryza_live_…`, même URL
Format	JSON, clés en `snake_case`, `Content-Type: application/json`
Identifiants	UUID ; références humaines `KDRZ-XXXXX` (sessions)
Montants	Entiers en XAF (pas de décimales)
Dates	RFC 3339 en UTC (`2026-06-05T12:30:00Z`)
Statuts, codes d’erreur	`UPPER_SNAKE_CASE`
Événements webhook	`domaine.action` (ex. `payment_session.succeeded`)

Endpoints

Paiements

Méthode	Endpoint	Rôle
`POST`	`/v1/payment-sessions`	Créer une Payment Session	Disponible
`GET`	`/v1/payment-sessions/:id`	Lire une session	Disponible
`GET`	`/v1/payment-sessions/by-reference`	Retrouver une session par votre référence	Disponible
`GET`	`/v1/payment-sessions/:id/webhook-deliveries`	Historique des livraisons webhook d’une session	Disponible
`POST`	`/v1/payment-sessions/:id/cancel`	Annuler une session	Test uniquement
`POST`	`/v1/hosted-checkouts`	Créer un paiement hébergé (le client choisit l’opérateur)	Disponible

Webhooks

Méthode	Endpoint	Rôle
`POST`	`/v1/webhooks`	Créer un endpoint
`GET`	`/v1/webhooks`	Lister les endpoints
`PATCH`	`/v1/webhooks/:id`	Activer ou désactiver
`DELETE`	`/v1/webhooks/:id`	Retirer un endpoint
`POST`	`/v1/webhooks/:id/test`	Envoyer un événement de test signé

Transactions (API historique)

Méthode	Endpoint	Rôle
`POST`	`/v1/transactions`	Initier une transaction	Test uniquement
`GET`	`/v1/transactions/:id`	Lire une transaction	Disponible
`GET`	`/v1/transactions`	Lister les transactions	Disponible

Avec une clé live, POST /v1/transactions répond 503 LEGACY_LIVE_TRANSACTION_DISABLED. Pour encaisser en production, utilisez les Payment Sessions ou le Hosted Checkout.

Les endpoints du dashboard (session utilisateur), du solde, des retraits, des rapports et des clés API ne font pas partie de l’API publique.

Réponses et erreurs

Une réponse réussie renvoie l’objet demandé (200, ou 201 à la création). Une erreur renvoie toujours la même forme :

Erreur


{
  "error": "payment session reference is required",
  "code": "REFERENCE_REQUIRED"
}

Utilisez code dans votre logique ; error est un message lisible qui peut évoluer. Certains codes ajoutent des champs (failed_checks, retry_after_seconds). Liste complète : Codes d’erreur.

Une ressource d’un autre compte ou d’un autre environnement répond 404, jamais 403.

Pagination

GET /v1/transactions accepte limit (défaut 20, maximum 1000) et offset. La réponse porte total, limit et offset :

GET /v1/transactions?limit=20&offset=0


{
  "transactions": [],
  "total": 0,
  "limit": 20,
  "offset": 0
}

Filtres : status, operator, date_from, date_to (RFC 3339 ou AAAA-MM-JJ) et search. L’environnement est celui de la clé.

Limites de débit

Portée	Limite
Endpoints de l’API publique, par compte	100 requêtes par minute
Création, modification, suppression, test d’endpoints webhook	20 par 5 minutes

Chaque réponse limitée porte X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset (timestamp Unix). Au-delà, l’API répond 429 RATE_LIMIT_EXCEEDED avec Retry-After et retry_after_seconds. Attendez ce délai avant de réessayer.

Une limite complémentaire par adresse IP s’applique en amont de l’API.

Idempotence

Paiements : votre reference est unique par environnement. Une seconde création avec la même référence est refusée (409) pour les sessions, ou renvoie l’objet existant pour un Hosted Checkout identique. En cas de doute après une coupure réseau, relisez avec GET /v1/payment-sessions/by-reference.
Webhooks : dédupliquez sur event_id (en-tête X-Kadryza-Event-ID).

Suivi en temps réel

La page de paiement hébergée suit les sessions par un flux SSE public. Côté serveur, préférez les webhooks au polling.