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
API	`https://api.kadryza.app`

Les environnements test et live partagent la même API et se distinguent par la clé utilisée (kadryza_test_… ou kadryza_live_…).

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 marchand

Le profil et le KYC marchand doivent être complets 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