Démarrage rapide

Créer une Payment Session

Depuis votre serveur, jamais depuis le navigateur :

curl -X POST https://api.kadryza.app/v1/payment-sessions \
  -H "X-API-Key: $KADRYZA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order_2026_001",
    "amount": 5000,
    "currency": "XAF",
    "operator": "AIRTEL",
    "customer_phone": "+23566000000",
    "ttl_minutes": 15
  }'

import Kadryza from '@kadryza/sdk'
 
const kadryza = new Kadryza({ apiKey: process.env.KADRYZA_API_KEY! })
 
const session = await kadryza.paymentSessions.create({
  reference: 'order_2026_001',
  amount: 5000,
  currency: 'XAF',
  operator: 'AIRTEL',
  customer_phone: '+23566000000',
  ttl_minutes: 15
})

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "reference": "order_2026_001",
  "ticket": "KDRZ-8F3K2",
  "amount": 5000,
  "currency": "XAF",
  "operator": "AIRTEL",
  "status": "AWAITING_PAYMENT",
  "environment": "test",
  "assigned_collection_number": "074000001",
  "expires_at": "2026-06-05T12:45:00Z",
  "created_at": "2026-06-05T12:30:00Z",
  "instructions": "Envoyez 5000 XAF vers le numéro 074000001 (AIRTEL), puis conservez la référence KDRZ-8F3K2. La session expire si le paiement n'est pas reçu à temps.",
  "checkout_url": "https://checkout.kadryza.com/pay/payment-sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

reference est votre identifiant de commande : réutiliser la même référence dans le même environnement renvoie 409 DUPLICATE_REFERENCE (retrouvez la session avec GET /v1/payment-sessions/by-reference).

Présenter le paiement

Deux options, au choix :

• Votre interface : affichez amount, operator, assigned_collection_number (le numéro vers lequel le client envoie l’argent), ticket et un compte à rebours jusqu’à expires_at ;
• La page hébergée : redirigez vers checkout_url. Elle suit le paiement en temps réel. Acceptez que son domaine soit checkout.kadryza.com ou checkout.kadryza.app.

Enregistrer votre endpoint webhook

curl -X POST https://api.kadryza.app/v1/webhooks \
  -H "X-API-Key: $KADRYZA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://merchant.example.com/webhooks/kadryza" }'

La réponse contient secret (64 caractères hexadécimaux), affiché une seule fois. Stockez-le côté serveur. L’URL doit résoudre vers une adresse publique ; HTTPS est obligatoire pour les livraisons live. Vérifiez la connectivité avec POST /v1/webhooks/:id/test.

Recevoir et vérifier les webhooks

Chaque livraison est signée : X-Kadryza-Signature: sha256=<hmac_hex>, HMAC-SHA256 du corps brut avec votre secret. Répondez 2xx rapidement et traitez en arrière-plan.

import { verifyWebhookSignature, parseKadryzaWebhookPayload, getWebhookIdempotencyKey } from '@kadryza/sdk'
 
const valid = verifyWebhookSignature({
  payload: rawBody, // corps brut, non re-sérialisé
  signature: req.headers['x-kadryza-signature'],
  secret: process.env.KADRYZA_WEBHOOK_SECRET!
})
if (!valid) return res.status(401).end()
 
const event = parseKadryzaWebhookPayload(rawBody)
const key = getWebhookIdempotencyKey(event) // event_id pour les Payment Sessions

Détails : Webhooks, Vérifier les webhooks.

Suivre sans webhook (complément)

GET /v1/payment-sessions/:id renvoie l’état courant. Limitez-vous à une requête toutes les 5 secondes pendant AWAITING_PAYMENT, et arrêtez dès que le statut change.

Passer en production

Suivez la checklist go-live, puis remplacez la clé de test par votre clé kadryza_live_…, côté serveur uniquement.