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)`

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',
  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 merchant / environnement.

`paymentSessions.cancel(id)`

Annule une session encore AWAITING_PAYMENT (sinon conflit).

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 WebhookEventType =
  | 'transaction.success'
  | 'transaction.failed'
  | 'transaction.timeout'
  | 'transaction.test'

Erreurs

Le SDK expose les erreurs typées existantes du package. Les erreurs API conservent le code retourné par le backend quand il est disponible.

ℹ️

Le SDK ne couvre pas encore payment links, invoices, refunds, balance, settlements, API keys ou reports.

Vue d'ensemble Vue d’ensemble