Référence SDK

`new Kadryza(config)`


import Kadryza from '@kadryza/sdk'
 
const kadryza = new Kadryza({
  apiKey: process.env.KADRYZA_API_KEY!,
  baseUrl: 'https://api.kadryza.app',
  timeout: 30000
})

Paramètre	Type	Requis	Défaut
`apiKey`	string	Oui	-
`baseUrl`	string	Non	`https://api.kadryza.app`
`timeout`	number	Non	`30000`

Le client HTTP utilise X-API-Key pour l’API publique.

`transactions.initiate(params)`

API historique : test uniquement. Avec une clé live, l’API répond 503 LEGACY_LIVE_TRANSACTION_DISABLED (levée comme KadryzaGatewayUnavailableError). Pour la production, utilisez paymentSessions.create.


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

Retour :


interface InitiateTransactionResponse {
  id: string
  internal_ref: string
  status: TransactionStatus
  is_test: boolean
  environment: 'live' | 'test'
  expires_at: string
}

`transactions.get(id)`


const transaction = await kadryza.transactions.get('a1b2c3d4-e5f6-7890-abcd-ef1234567890')

Retour principal :


interface Transaction {
  id: string
  reference: string
  internal_ref: string
  amount: number
  currency: 'XAF'
  operator: 'AIRTEL' | 'MOOV'
  phone_number: string
  description?: string
  status: TransactionStatus
  is_test?: boolean
  environment?: 'live' | 'test'
  failure_reason?: string
  webhook_sent: boolean
  initiated_at: string
  confirmed_at?: string
  expires_at: string
  created_at: string
  updated_at?: string
}

`transactions.list(params)`


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

Paramètres supportés :

Paramètre	Type
`limit`	number
`offset`	number
`status`	`TransactionStatus`
`operator`	`AIRTEL` ou `MOOV`
`date_from`	string
`date_to`	string
`search`	string

Retour :


interface PaginatedTransactions {
  transactions: Transaction[]
  total: number
  limit: number
  offset: number
}

`paymentSessions.create(params)`

Crée une payment session. merchant_id et l’environnement sont déduits de la clé API : ne les passez pas. Affichez assigned_collection_number à votre client.


const session = await kadryza.paymentSessions.create({
  reference: 'order_2026_001',
  amount: 5000,
  currency: 'XAF',
  operator: 'AIRTEL',
  customer_phone: '+23566000000', // obligatoire en live
  ttl_minutes: 15, // optionnel, 1–60 (défaut 10)
})
 
console.log(session.assigned_collection_number) // ex. "074000001"
console.log(session.status) // "AWAITING_PAYMENT"
console.log(session.environment) // "live" ou "test" selon la clé

`paymentSessions.retrieve(id)`


const session = await kadryza.paymentSessions.retrieve('a1b2c3d4-e5f6-7890-abcd-ef1234567890')

Renvoie KadryzaNotFoundError si la session n’existe pas pour votre compte ou votre environnement.

`paymentSessions.retrieveByReference(reference)`

Retrouve une session par votre référence : le chemin de récupération après une création dont la réponse a été perdue.


const session = await kadryza.paymentSessions.retrieveByReference('order_2026_001')

`paymentSessions.listWebhookDeliveries(id)`

Historique des livraisons webhook d’une session (statut, tentatives, dernier code HTTP), sans URL ni contenu.


const { deliveries } = await kadryza.paymentSessions.listWebhookDeliveries(session.id)

`paymentSessions.cancel(id)`

Annule une session de test encore AWAITING_PAYMENT. Une session live, ou une session déjà conclue, est refusée (409 NOT_CANCELLABLE, levée comme KadryzaDuplicateError).


const cancelled = await kadryza.paymentSessions.cancel(session.id)
console.log(cancelled.status) // "CANCELLED"

`webhooks.create({ url })`


const endpoint = await kadryza.webhooks.create({
  url: 'https://merchant.example.com/webhooks/kadryza'
})

Retour :


interface CreatedWebhookEndpoint {
  id: string
  url: string
  is_active: boolean
  created_at: string
  secret: string
}

Le champ secret est affiché uniquement à la création. Stockez-le immédiatement.

`webhooks.list()`


const endpoints = await kadryza.webhooks.list()

Retour :


interface WebhookEndpoint {
  id: string
  url: string
  is_active: boolean
  created_at: string
}

`webhooks.delete(id)`


await kadryza.webhooks.delete(endpoint.id)

`webhooks.test(id)`


const result = await kadryza.webhooks.test(endpoint.id)

Retour :


interface WebhookTestResult {
  status: string
  message: string
}

`webhooks.verify(params)`


const valid = kadryza.webhooks.verify({
  payload: rawBody,
  signature: request.headers['x-kadryza-signature'],
  secret: process.env.KADRYZA_WEBHOOK_SECRET!
})

`verifyWebhookSignature(params)`


import { verifyWebhookSignature } from '@kadryza/sdk'
 
const valid = verifyWebhookSignature({
  payload: rawBody,
  signature: 'sha256=<hmac_hex>',
  secret: process.env.KADRYZA_WEBHOOK_SECRET!
})

Le format officiel est sha256=<hex>. Le SDK accepte aussi le hex brut pour compatibilité.

Types


type TransactionStatus =
  | 'PENDING'
  | 'PROCESSING'
  | 'WAITING_SMS'
  | 'SUCCESS'
  | 'FAILED'
  | 'TIMEOUT'
  | 'REFUNDED'
 
type PaymentSessionStatus =
  | 'AWAITING_PAYMENT'
  | 'SUCCESS'
  | 'UNDER_REVIEW'
  | 'EXPIRED'
  | 'FAILED'
  | 'CANCELLED'

Événements webhook reconnus : payment_session.succeeded, payment_session.under_review, payment_session.expired, payment_session.failed (réservé), transaction.success, transaction.failed, transaction.timeout, transaction.test.

Erreurs

Les classes d’erreur sont choisies selon le statut HTTP ; pour les statuts 400, 401, 404, 409 et 503, le code exposé est générique (VALIDATION_ERROR, UNAUTHORIZED, NOT_FOUND, DUPLICATE_REFERENCE, GATEWAY_UNAVAILABLE) et ne reprend pas le code détaillé de l’API. Le message d’origine est conservé. Détails : Codes d’erreur.

ℹ️

Le SDK ne couvre pas le Hosted Checkout, l’activation d’un endpoint webhook, les liens de paiement, les remboursements, le solde, les retraits, les factures ni les clés API.