Transactions (API historique)

La création de transactions est réservée à l’environnement de test. Avec une clé live, POST /v1/transactions répond 503 LEGACY_LIVE_TRANSACTION_DISABLED. Pour encaisser en production, utilisez les Payment Sessions ou le Hosted Checkout.

L’API Transactions reste utile pour tester vos traitements : en sandbox, elle simule une issue selon le numéro de téléphone, sans paiement réel. La lecture et la liste restent disponibles pour consulter l’historique.

Tous les endpoints utilisent X-API-Key. Portées : write_transactions pour créer, read_transactions pour lire.

Initier une transaction

POST/v1/transactionsTest uniquementX-API-Key

Champ	Type	Requis	Description
`reference`	string	Oui	Référence unique côté marchand (100 caractères max)
`amount`	integer	Oui	Montant entier en XAF
`currency`	string	Oui	`XAF`
`operator`	string	Oui	`AIRTEL` ou `MOOV`
`phone_number`	string	Oui	Numéro du payeur (20 caractères max)
`description`	string	Non	Description courte (255 caractères max)


curl -X POST https://api.kadryza.app/v1/transactions \
  -H "X-API-Key: $KADRYZA_TEST_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"
  }'

201 Created


{
  "id": "f72807b8-01c9-4283-aa1d-0d6809bf5176",
  "internal_ref": "KADRYZA-20260605-20113722",
  "status": "PENDING",
  "is_test": true,
  "environment": "test",
  "expires_at": "2026-06-05T12:05:00Z"
}

Idempotence : réutiliser la même reference dans le même environnement renvoie la transaction existante, sans en créer une seconde.

Simulation sandbox

Avec une clé de test, aucune opération réelle n’a lieu. Environ deux secondes après la création :

`phone_number` contient	Issue	Webhook
`0001`	FAILED	`transaction.failed`
`0002`	reste PENDING puis TIMEOUT à `expires_at`	`transaction.timeout`
autre chose	SUCCESS	`transaction.success`

Statuts

PENDING, PROCESSING, WAITING_SMS (intermédiaires) ; SUCCESS, FAILED, TIMEOUT (finaux) ; REFUNDED (après remboursement depuis le dashboard).

Récupérer une transaction

GET/v1/transactions/:idX-API-Key


curl https://api.kadryza.app/v1/transactions/f72807b8-01c9-4283-aa1d-0d6809bf5176 \
  -H "X-API-Key: $KADRYZA_TEST_API_KEY"

200 OK


{
  "id": "f72807b8-01c9-4283-aa1d-0d6809bf5176",
  "merchant_id": "fb44caba-6f14-46e7-af28-abd8ed41de81",
  "reference": "order_2026_001",
  "internal_ref": "KADRYZA-20260605-20113722",
  "amount": 5000,
  "currency": "XAF",
  "operator": "AIRTEL",
  "phone_number": "+23566000000",
  "description": "Commande #2026-001",
  "status": "SUCCESS",
  "is_test": true,
  "environment": "test",
  "webhook_sent": false,
  "webhook_attempts": 0,
  "initiated_at": "2026-06-05T12:00:00Z",
  "confirmed_at": "2026-06-05T12:00:02Z",
  "expires_at": "2026-06-05T12:05:00Z",
  "created_at": "2026-06-05T12:00:00Z",
  "updated_at": "2026-06-05T12:00:02Z"
}

Lister les transactions

GET/v1/transactionsX-API-Key

Paramètre	Type	Description
`limit`	integer	Défaut `20`, maximum `1000`
`offset`	integer	Défaut `0`
`status`	string	Un des statuts ci-dessus
`operator`	string	`AIRTEL` ou `MOOV`
`date_from`, `date_to`	string	`AAAA-MM-JJ` ou RFC 3339
`search`	string	Recherche textuelle (référence…)

L’environnement est celui de la clé : une clé de test ne liste que des transactions de test.


curl "https://api.kadryza.app/v1/transactions?limit=50&status=SUCCESS&operator=AIRTEL&date_from=2026-06-01" \
  -H "X-API-Key: $KADRYZA_TEST_API_KEY"

Réponse : { "transactions": [...], "total": 1, "limit": 50, "offset": 0 }.

SDK


const created = await kadryza.transactions.initiate({
  reference: 'order_2026_001',
  amount: 5000,
  currency: 'XAF',
  operator: 'AIRTEL',
  phone_number: '+23566000000'
})
const tx = await kadryza.transactions.get(created.id)
const page = await kadryza.transactions.list({ limit: 20, status: 'SUCCESS' })

Erreurs spécifiques

HTTP	`code`	Cause
400	`INVALID_BODY`, `VALIDATION_ERROR`	Corps illisible ou champ invalide
400	`TRANSACTION_AMOUNT_TOO_LOW`, `TRANSACTION_AMOUNT_TOO_HIGH`	Montant hors des bornes du compte
400	`INVALID_STATUS`, `INVALID_OPERATOR`, `INVALID_DATE_FROM`, `INVALID_DATE_TO`, `INVALID_DATE_RANGE`, `INVALID_SEARCH`	Filtre de liste invalide
403	`DAILY_TRANSACTION_LIMIT_EXCEEDED`	Plafond journalier atteint
404	`NOT_FOUND`	Transaction inconnue pour ce compte et cet environnement
409	`DUPLICATE_REFERENCE`	Création concurrente avec la même référence
503	`LEGACY_LIVE_TRANSACTION_DISABLED`	Création avec une clé live

Erreurs communes : Codes d’erreur.