Transactions

Une transaction est la source de vérité unique d'un paiement. Vous la créez ; le switch la route vers un fournisseur ; le statut final arrive sur votre callback.

Créer une transaction

http

POST /api/payments/transaction/
Authorization: Bearer <token>
Content-Type: application/json

{
  "merchant_reference": "INV-2026-0001",
  "amount": "100.00",
  "currency": "CDF",
  "customer_number": "0810000000",
  "operation": "debit",
  "service": "<service-id>",
  "callback_url": "https://your-app/payments/callback"
}

merchant_reference est votre référence ; elle doit être unique par marchand.
operation vaut "debit" (encaissement) ou "credit" (décaissement).
provider_code_name est optionnel — omettez-le et le répartiteur de charge choisit le fournisseur ; fournissez "freshpay" / "unipesa" pour en forcer un.
Le statut est contrôlé par le serveur et démarre à Received. L'argent ne bouge jamais de façon synchrone ici — le switch dispatche de manière asynchrone.

La réponse est la transaction créée, incluant la reference canonique de PayRouter et le provider_code_name résolu.

Statuts

Statut	Signification
`Received`	Créée, en file pour dispatch
`Pending`	Acceptée par le fournisseur, en attente du callback
`Success`	Terminée
`Failed`	Rejetée ou échouée
`Cancelled`	Annulée (terminal)

Les états terminaux (Success / Failed / Cancelled) sont immuables.

Lire une transaction

http

GET /api/payments/transaction/                       # vos transactions (paginées)
GET /api/payments/transaction/<reference>/           # une transaction
GET /api/payments/transaction/<reference>/history/   # historique des statuts

La liste prend en charge ?search=, ?ordering=-created_at et des filtres (transaction_status, operation, provider_code_name, service). Chaque ligne inclut des libellés lisibles : currency_abbr, service_name, provider_code_name.

Paiements groupés

Pour les décaissements en masse, regroupez les bénéficiaires et payez-les ensemble :

Endpoint	Objet
`POST /api/payments/payment-groups/`	créer un groupe `{ name }`
`POST /api/payments/payment-request-members/`	ajouter un membre `{ payment_group, name, phone_number, amount, currency }`
`GET /api/payments/payment-requests/?payment_group=<id>`	demandes d'un groupe
`GET /api/payments/payment-transactions/`	historique de paiement par membre

Authentification

Callbacks