Démarrage rapide

Ce guide montre l’intégration minimale serveur à serveur avec l’API publique Kadryza.

⚠️

Utilisez une clé kadryza_test_... pendant le développement. Une clé kadryza_live_... déclenche les flux de production.

URLs

Environnement	URL
Production API	`https://api.kadryza.app` — domaine officiel prévu
Staging/Test temporaire	`https://api-kadryza.spencerai.tech`

spencerai.tech est temporaire et ne représente pas le domaine officiel public Kadryza.

1. Installer le SDK

npm install @kadryza/sdk

import Kadryza from '@kadryza/sdk'
 
const kadryza = new Kadryza({
  apiKey: process.env.KADRYZA_API_KEY!
})

Le SDK envoie la clé via le header public officiel X-API-Key.

2. Initier une transaction

const transaction = await kadryza.transactions.initiate({
  reference: 'order_2026_001',
  amount: 5000,
  currency: 'XAF',
  operator: 'AIRTEL',
  phone_number: '+23566000000',
  description: 'Commande #2026-001'
})
 
console.log(transaction.id)
console.log(transaction.status)
console.log(transaction.environment)

Équivalent cURL :

curl -X POST https://api.kadryza.app/v1/transactions \
  -H "X-API-Key: $KADRYZA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order_2026_001",
    "amount": 5000,
    "currency": "XAF",
    "operator": "AIRTEL",
    "phone_number": "+23566000000",
    "description": "Commande #2026-001"
  }'

Réponse :

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "internal_ref": "KADRYZA-A1B2C3D4",
  "status": "PENDING",
  "is_test": true,
  "environment": "test",
  "expires_at": "2026-06-05T12:30:00Z"
}

3. Consulter une transaction

const tx = await kadryza.transactions.get(transaction.id)
console.log(tx.status)

curl https://api.kadryza.app/v1/transactions/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: $KADRYZA_API_KEY"

4. Lister les transactions

const result = await kadryza.transactions.list({
  limit: 20,
  offset: 0,
  status: 'SUCCESS',
  operator: 'AIRTEL',
  date_from: '2026-06-01',
  date_to: '2026-06-30',
  search: 'order_'
})
 
console.log(result.transactions)
console.log(result.total)

Les filtres disponibles dans le SDK sont limit, offset, status, operator, date_from, date_to et search.

5. Configurer un webhook

const endpoint = await kadryza.webhooks.create({
  url: 'https://merchant.example.com/webhooks/kadryza'
})
 
console.log(endpoint.secret) // affiché uniquement à la création

Vérifiez ensuite la signature :

import { verifyWebhookSignature } from '@kadryza/sdk'
 
const valid = verifyWebhookSignature({
  payload: rawBody,
  signature: req.headers['x-kadryza-signature'],
  secret: process.env.KADRYZA_WEBHOOK_SECRET!
})

Le header reçu est :

X-Kadryza-Signature: sha256=<hmac_hex>

6. Go-live

Compléter le compte merchant

Le profil/KYC merchant doit être complet avant l’usage réel de l’API.

Tester en sandbox

Créez au moins une transaction avec une clé kadryza_test_... et vérifiez le webhook.

Passer à la clé live

Remplacez la clé test par une clé kadryza_live_... côté serveur uniquement.

Surveiller les webhooks

Votre endpoint doit répondre en HTTP 2xx. Kadryza réessaie les livraisons échouées avec backoff.

Authentification