Transactions

                    ┌─────────────────────────────────────┐
                    │          Initiation (POST)          │
                    └──────────────┬──────────────────────┘
                                   │
                                   ▼
                          ┌────────────────┐
                          │    PENDING     │
                          │  (en attente)  │
                          └───────┬────────┘
                                  │
                    ┌─────────────┼─────────────┐
                    │             │             │
                    ▼             ▼             ▼
           ┌──────────────┐ ┌──────────┐ ┌───────────┐
           │   SUCCESS    │ │  FAILED  │ │  TIMEOUT  │
           │  (confirmé)  │ │ (refusé) │ │ (expiré)  │
           └──────────────┘ └──────────┘ └───────────┘
                    │             │             │
                    ▼             ▼             ▼
              Webhook envoyé  Webhook envoyé  Webhook envoyé
          transaction.success  transaction.failed  transaction.timeout

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "reference": "order_2025_001",
  "internal_ref": "KADRYZA-A1B2C3D4",
  "amount": 15000,
  "currency": "XAF",
  "operator": "AIRTEL",
  "phone_number": "+23566000000",
  "description": "Abonnement mensuel Premium",
  "status": "PENDING",
  "created_at": "2025-06-15T14:30:00Z",
  "updated_at": "2025-06-15T14:30:00Z",
  "expires_at": "2025-06-15T14:35:00Z"
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Paramètres de requête invalides",
    "status": 400,
    "fields": {
      "amount": "Le montant doit être un entier positif",
      "operator": "Valeurs acceptées : AIRTEL, MOOV"
    }
  }
}

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "reference": "order_2025_001",
  "internal_ref": "KADRYZA-A1B2C3D4",
  "amount": 15000,
  "currency": "XAF",
  "operator": "AIRTEL",
  "phone_number": "+23566000000",
  "description": "Abonnement mensuel Premium",
  "status": "SUCCESS",
  "created_at": "2025-06-15T14:30:00Z",
  "updated_at": "2025-06-15T14:31:12Z",
  "expires_at": "2025-06-15T14:35:00Z"
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Transaction introuvable",
    "status": 404
  }
}

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "reference": "order_2025_001",
      "internal_ref": "KADRYZA-A1B2C3D4",
      "amount": 15000,
      "currency": "XAF",
      "operator": "AIRTEL",
      "phone_number": "+23566000000",
      "status": "SUCCESS",
      "created_at": "2025-06-15T14:30:00Z",
      "updated_at": "2025-06-15T14:31:12Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "reference": "order_2025_002",
      "internal_ref": "KADRYZA-B2C3D4E5",
      "amount": 7500,
      "currency": "XAF",
      "operator": "MOOV",
      "phone_number": "+23599000000",
      "status": "SUCCESS",
      "created_at": "2025-06-16T09:15:00Z",
      "updated_at": "2025-06-16T09:16:30Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 2,
    "total_pages": 1
  }
}

Requête 1 : POST /v1/transactions { "reference": "order_xyz" }
 → 201 Created — Transaction créée avec statut PENDING

Requête 2 : POST /v1/transactions { "reference": "order_xyz" }
 → 409 Conflict — Transaction existante retournée (pas de doublon)

import Kadryza from '@kadryza/sdk'
 
const kadryza = new Kadryza({
  apiKey: process.env.KADRYZA_API_KEY
})
 
async function initierPaiementIdempotent(referenceCommande) {
  // Utiliser la référence de commande comme clé d'idempotence
  // Peu importe combien de fois cette fonction est appelée
  // avec la même référence, une seule transaction sera créée
  const transaction = await kadryza.transactions.initiate({
    reference: referenceCommande,
    amount: 25000,
    currency: 'XAF',
    operator: 'MOOV',
    phone_number: '+23599000000',
    description: 'Commande e-commerce'
  })
 
  return transaction
}
 
// Scénario : l'utilisateur clique 3 fois sur le bouton "Payer"
// ou le réseau timeout et votre système retry automatiquement
const tx1 = await initierPaiementIdempotent('cmd_2025_abc')  // → Crée la transaction
const tx2 = await initierPaiementIdempotent('cmd_2025_abc')  // → Retourne la même transaction
const tx3 = await initierPaiementIdempotent('cmd_2025_abc')  // → Retourne la même transaction
 
console.log(tx1.id === tx2.id)  // true
console.log(tx2.id === tx3.id)  // true
// Une seule transaction existe côté Kadryza

import Kadryza from '@kadryza/sdk'
 
const kadryza = new Kadryza({
  apiKey: process.env.KADRYZA_API_KEY
})
 
// === ÉTAPE 1 : Initier le paiement ===
async function creerPaiement(commande) {
  const transaction = await kadryza.transactions.initiate({
    reference: commande.id,
    amount: commande.total,
    currency: 'XAF',
    operator: commande.operateur,
    phone_number: commande.telephone,
    description: `Commande #${commande.id} — ${commande.articles.length} article(s)`
  })
 
  // Sauvegarder l'ID de transaction dans votre base
  await db.commandes.update(commande.id, {
    kadryza_transaction_id: transaction.id,
    kadryza_internal_ref: transaction.internal_ref,
    statut_paiement: 'EN_ATTENTE',
    paiement_expire_a: transaction.expires_at
  })
 
  return {
    transaction_id: transaction.id,
    internal_ref: transaction.internal_ref,
    expires_at: transaction.expires_at
  }
}
 
// === ÉTAPE 2 : Recevoir le webhook ===
// (Voir /api-reference/webhooks pour l'implémentation complète)
 
// === ÉTAPE 3 : Vérifier le statut (si webhook manqué) ===
async function verifierStatut(transactionId) {
  const transaction = await kadryza.transactions.get(transactionId)
 
  switch (transaction.status) {
    case 'PENDING':
      console.log('⏳ En attente de confirmation du payeur')
      break
    case 'SUCCESS':
      console.log('✅ Paiement confirmé — livrer la commande')
      break
    case 'FAILED':
      console.log('❌ Paiement refusé — proposer un autre moyen de paiement')
      break
    case 'TIMEOUT':
      console.log('⏰ Paiement expiré — proposer de réessayer')
      break
  }
 
  return transaction
}
 
// === Utilisation ===
const commande = {
  id: 'cmd_2025_789',
  total: 32000,
  operateur: 'AIRTEL',
  telephone: '+23566000000',
  articles: [
    { nom: 'Forfait Internet 10Go', prix: 12000 },
    { nom: 'Forfait Appels 500min', prix: 20000 }
  ]
}
 
const resultat = await creerPaiement(commande)
console.log('Transaction créée:', resultat.internal_ref)
console.log('Expire à:', resultat.expires_at)