> ## Documentation Index
> Fetch the complete documentation index at: https://docs.saspay.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Transactions

> Historique unifié des paiements et retraits : détail, tentatives, changements de statut, export CSV et facture PDF.

Toutes les routes de ce groupe nécessitent le header `Authorization: Bearer sk_...`. Une `Transaction` est créée par [softpay](/api-reference/payments/softpay), [checkout hébergé](/api-reference/payments/checkout-create) ou [payout](/api-reference/payouts/initialize) — il n'existe pas de création directe de transaction via ce groupe, lecture seule uniquement.

## Vue d'ensemble

```
Transaction
├── champs de base (montants, devise, statut, merchant, customer, country, network...)
├── attempts[]       ← une ligne par tentative de routage gateway (priorité, succès/échec)
└── status_logs[]     ← historique append-only des transitions de statut (from → to, qui a déclenché)
```

* [Lister ses transactions](/api-reference/transactions/list)
* [Détail d'une transaction](/api-reference/transactions/get)
* [Export CSV](/api-reference/transactions/export)
* [Facture PDF](/api-reference/transactions/invoice)
* [Lister les tentatives](/api-reference/transactions/attempts-list)
* [Détail d'une tentative](/api-reference/transactions/attempts-get)
* [Lister les changements de statut](/api-reference/transactions/status-logs-list)
* [Détail d'un changement de statut](/api-reference/transactions/status-logs-get)

## `flow_direction` : payin ou payout

| `transaction_type` | `flow_direction` | Origine                                                                                                   |
| ------------------ | ---------------- | --------------------------------------------------------------------------------------------------------- |
| `PAIEMENT`         | `INBOUND`        | [softpay](/api-reference/payments/softpay) ou [checkout hébergé](/api-reference/payments/checkout-create) |
| `RECHARGE`         | `INBOUND`        | Recharge de solde                                                                                         |
| `RETRAIT`          | `OUTBOUND`       | [payout](/api-reference/payouts/initialize)                                                               |
| `TRANSFERT`        | `OUTBOUND`       | Transfert interwallet (voir [Wallet](/api-reference/wallet))                                              |

`flow_direction` est toujours dérivé de `transaction_type`, jamais saisi directement — c'est un champ en lecture seule.

<Note>
  `status: "CANCELLED"` existe dans le modèle de données mais n'est actuellement atteint par aucun flux — en pratique, seuls `PENDING`, `SUCCESS` et `FAILED` apparaissent.
</Note>

## Pagination : curseur, pas de `count`

`GET /transactions/`, `GET /transaction-attempts/` et `GET /transaction-status-logs/` utilisent une pagination par curseur (`page_size=50` par défaut, `200` maximum via `?page_size=`) :

```json theme={null}
{
  "next": "https://api.saspay.me/api/v1/transactions/?cursor=cD0yMDI2LTA4LTEy",
  "previous": null,
  "results": [ ]
}
```

<Warning>
  Pas de champ `count` sur ces trois endpoints (contrairement à la plupart des autres listes de l'API, qui utilisent une pagination par numéro de page classique avec `count`) — table la plus volumineuse de la plateforme, un `COUNT(*)` par page serait coûteux. Naviguez avec `next`/`previous`, pas avec un numéro de page.
</Warning>

## Filtrer et rechercher

`GET /transactions/` accepte :

* **Filtres exacts** : `status`, `transaction_type`, `currency`, `flow_direction`, `country`, `network`, `merchant`
* **Plage de dates** : `created_at__gte`, `created_at__lte`
* **Recherche libre** (`?search=`) : référence, référence gateway, nom/email/téléphone client, slug de lien de paiement, slug de session checkout

`GET /transaction-attempts/` filtre par `status`, `gateway`, `transaction`. `GET /transaction-status-logs/` filtre par `to_status`, `triggered_by`, `transaction`.

## Export et facture : marge interne jamais exposée

`gateway_fee` et `platform_fee` (la marge interne de la plateforme) sont visibles sur les endpoints JSON classiques (liste, détail) — vous les voyez déjà comme marchand. Ils **disparaissent totalement** des deux documents destinés à être partagés en dehors de l'API :

| Document                                           | `gateway_fee` / `platform_fee`                                             |
| -------------------------------------------------- | -------------------------------------------------------------------------- |
| `GET /transactions/` , `GET /transactions/{id}/`   | Visibles                                                                   |
| [Export CSV](/api-reference/transactions/export)   | Visibles (usage interne/comptable marchand)                                |
| [Facture PDF](/api-reference/transactions/invoice) | **Jamais** — uniquement `requested_amount`, `client_fee`, `debited_amount` |

<Warning>
  La facture PDF n'est disponible que pour un paiement entrant réussi (`flow_direction: "INBOUND"` et `status: "SUCCESS"`) — jamais pour un payout, jamais pour une transaction encore `PENDING` ou `FAILED`.
</Warning>