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

ResponseObjet 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": "pi_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.

GETParamètres de requête (query)

statusOptionnel

stringquery

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

typeOptionnel

stringquery

Filtrer par type de transaction.

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

payment_method_typeOptionnel

stringquery

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

currencyOptionnel

stringISO 4217query

Filtrer par devise.

customerOptionnel

stringquery

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

min_amountOptionnel

integercentimesquery

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

max_amountOptionnel

integercentimesquery

Montant maximum (inclusif) en centimes.

created_afterOptionnel

stringISO 8601queryex :2026-01-01T00:00:00Z

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

created_beforeOptionnel

stringISO 8601queryex :2026-03-31T23:59:59Z

Date de fin de la plage temporelle (inclusif).

searchOptionnel

stringquery

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

orderingOptionnel

stringquerydéfaut :-created_at

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

pageOptionnel

integerquerydéfaut :1

Numéro de page.

page_sizeOptionnel

integerquerydé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.ga/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_prod_xxxx"

Response200 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.ga/v1/transactions/?page=2&page_size=100&status=completed"
  }
}

ResponseRé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": "pi_xxxxxxxxxxxx",
  "customer": "cust_xxxxxxxx",
  "payment_method_type": "mobile_money",
  "operator": "airtel",
  "processed_at": "2026-03-01T10:05:00Z"
}