Transactions

Une Transaction représente un paiement effectivement traité par un opérateur. Elle est créée automatiquement par Sangho lors de la réussite d’une Intention de paiement — vous ne pouvez pas en créer directement via l’API.

Les transactions sont le registre comptable de vérité de votre activité. Elles contiennent le montant net collecté, les frais Sangho, les commissions partenaires, et sont la source des Receipts envoyés aux clients.

Transactions en lecture seule

Les transactions ne peuvent pas être créées, modifiées (sauf description et metadata), ni supprimées. Pour annuler les fonds d’une transaction, créez un Refund. Pour contester une transaction, contactez le support Sangho.

Statuts possibles

Statut	Signification	Action possible
`approved`	Approuvée par l'opérateur, en attente de règlement.	Attendre — passage automatique en `completed`.
`pending`	En file d'attente de traitement opérateur.	Attendre le webhook `transaction.succeeded`.
`completed`	Paiement réussi — fonds capturés et disponibles.	Émettre le service/produit. Remboursement possible.
`failed`	Paiement échoué côté opérateur.	Informer le client, proposer une autre méthode.
`refunded`	Remboursement total effectué.	Aucune — transaction clôturée.
`disputed`	Transaction contestée par le client ou l'opérateur.	Contacter le support avec les preuves.
`canceled`	Transaction annulée avant traitement.	Créer une nouvelle Intention de paiement si nécessaire.

Endpoints

Méthode	Endpoint	Description
GET	`/transactions/`	Lister les transactions (paginé, filtrable)
GET	`/transactions/{id}/`	Récupérer une transaction par son ID
PATCH	`/transactions/{id}/`	Modifier description et metadata uniquement
POST	`/transactions/{id}/cancel/`	Annuler une transaction en statut pending

Cette introduction est-elle claire ?

Schéma de l’objet

Response Objet Transaction

Structure complète. Les champs fee et commission sont calculés automatiquement par Sangho selon votre plan tarifaire.

json

{
  "id": "trans_3Nx8mLKZ2eZvKYlo28m",
  "object": "transaction",
  "app": "app_xxxxxxxx",
  "amount": 15000,
  "fee": 350,
  "fee_rate": 0.023,
  "commission": 150,
  "commission_rate": 0.01,
  "net_amount": 14500,
  "currency": "XAF",
  "status": "completed",
  "type": "deposit",
  "description": "Commande #CMD-2026-042",
  "payment_intent": "pay_xxxxxxxxxxxx",
  "customer": "cust_xxxxxxxx",
  "payment_method_type": "mobile_money",
  "operator": "airtel",
  "processed_at": "2026-03-01T10:05:00Z",
  "metadata": {
    "order_id": "CMD-2026-042"
  },
  "livemode": true,
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-01T10:05:00Z"
}

Lister les transactions

Retourne une liste paginée de toutes les transactions de votre App. C’est l’endpoint principal pour les rapports comptables, les réconciliations et les exports.

GET Paramètres de requête (query)

status Optionnel

string query

Filtrer par statut. Plusieurs valeurs séparées par une virgule : status=completed,refunded.

type Optionnel

string query

Filtrer par type de transaction.

Valeurs possibles : deposit (paiement entrant), refund (remboursement), payout (virement sortant), withdraw (retrait), transfer (transfert interne).

payment_method_type Optionnel

string query

Filtrer par méthode de paiement utilisée : mobile_money, bank_card, paypal.

currency Optionnel

string ISO 4217 query

Filtrer par devise.

customer Optionnel

string query

Filtrer par ID ou email Customer. Retourne toutes les transactions liées à ce client.

min_amount Optionnel

integer centimes query

Montant minimum (inclusif) en centimes. Utile pour filtrer les transactions au-dessus d’un seuil.

max_amount Optionnel

integer centimes query

Montant maximum (inclusif) en centimes.

created_after Optionnel

string ISO 8601 query ex : 2026-01-01T00:00:00Z

Date de début de la plage temporelle (inclusif).

created_before Optionnel

string ISO 8601 query ex : 2026-03-31T23:59:59Z

Date de fin de la plage temporelle (inclusif).

search Optionnel

string query

Recherche textuelle sur la description de la transaction. Partielle, insensible à la casse.

ordering Optionnel

string query défaut : -created_at

Tri. Champs disponibles : created_at, amount, net_amount, status.

page Optionnel

integer query défaut : 1

Numéro de page.

page_size Optionnel

integer query défaut : 20

Résultats par page. Maximum : 100.

Pour les exports comptables ou les réconciliations, combinez page_size=100 avec created_after et created_before pour paginer sur une période précise.

Réconciliation mensuelle

Pour exporter toutes les transactions d’un mois, combinez created_after=2026-03-01T00:00:00Z, created_before=2026-03-31T23:59:59Z, status=completed, type=deposit, et paginez avec page_size=100 jusqu’à épuisement des pages.

Les filtres de liste sont-ils suffisamment documentés ?

Lister les transactions

bash

# Transactions complétées du T1 2026
curl "https://api.sangho.com/v1/transactions/?status=completed&type=deposit&created_after=2026-01-01T00:00:00Z&created_before=2026-03-31T23:59:59Z&page_size=100" \
  -H "Authorization: Bearer sk_live_xxxx"

Response 200 OK — Liste paginée

Le champ pagination.count indique le nombre total de transactions correspondant aux filtres, tous utilisables pour les totaux comptables.

json

{
  "object": "list",
  "data": [
    {
      "id": "trans_3Nx8mLKZ2eZvKYlo28m",
      "object": "transaction",
      "amount": 15000,
      "fee": 350,
      "net_amount": 14500,
      "currency": "XAF",
      "status": "completed",
      "type": "deposit",
      "payment_method_type": "mobile_money",
      "customer": "cust_xxxxxxxx",
      "created_at": "2026-03-01T10:05:00Z"
    }
  ],
  "pagination": {
    "count": 347,
    "total_pages": 4,
    "page": 1,
    "page_size": 100,
    "previous": null,
    "next": "https://api.sangho.com/v1/transactions/?page=2&page_size=100&status=completed"
  }
}

Response Récupérer une transaction

GET /transactions/{id}/ retourne l'objet complet avec tous les champs de frais et l'opérateur.

json

{
  "id": "trans_3Nx8mLKZ2eZvKYlo28m",
  "amount": 15000,
  "fee": 350,
  "fee_rate": 0.023,
  "commission": 150,
  "net_amount": 14500,
  "currency": "XAF",
  "status": "completed",
  "type": "deposit",
  "payment_intent": "pay_xxxxxxxxxxxx",
  "customer": "cust_xxxxxxxx",
  "payment_method_type": "mobile_money",
  "operator": "airtel",
  "processed_at": "2026-03-01T10:05:00Z"
}