# Les chiffres d’une période

`GET https://api.payiz.app/v1/reports/summary`

Demande une clé secrète qui porte le geste « Rapports · lire ».

Rend les chiffres d’une période : ce que vos clients ont payé, les frais, le net, les remboursements, les paiements réussis et le taux de réussite. Ce sont les mêmes que la page Rapports de votre espace, au franc près.

Un paiement compte le jour de sa réussite, à l’heure du pays de l’espace. Une monnaie à la fois.

## Ce qu'on met dans l'adresse

| Champ | Type | Requis | Ce que c'est |
| --- | --- | --- | --- |
| `from` | texte | oui | Le premier jour, au format AAAA-MM-JJ. |
| `to` | texte | oui | Le dernier jour, compris. |
| `currency` | texte | — | Sans précision : la monnaie de l’espace. |
| `compare` | « previous » · « previous_year » · « none » | — | Par défaut « previous » : la période d’avant, de même longueur. Ses chiffres reviennent dans « previous ». |
| `channel` | « link » · « page » · « invoice » · « request » · « api » | — | Par où les clients ont payé. Plusieurs : séparés par des virgules. |
| `operator` | texte | — | Le code public d’un opérateur, par exemple « mtn ». Avec « country » pour un seul pays. |
| `country` | texte | — | Le pays du payeur, en ISO 3166 à trois lettres. |
| `metadata[clé]` | texte | — | Les paiements dont la métadonnée vaut cette valeur, par exemple metadata[order_id]=cmd-42. |

## Ce qu'on reçoit

`200` · un objet `report_summary`

| Champ | Type | Requis | Ce que c'est |
| --- | --- | --- | --- |
| `object` | « report_summary » | — | Le genre de l’objet rendu : il ne change jamais. |
| `from` | texte | — | Le premier jour couvert. |
| `to` | texte | — | Le dernier jour couvert. |
| `timezone` | texte | — | Le fuseau du pays de l’espace, celui des jours. |
| `currency` | texte | — | Le code ISO 4217, en majuscules. |
| `amount_paid` | entier | — | Ce que vos clients ont payé, frais du payeur compris. |
| `fee` | entier | — | La commission de Payiz. |
| `net` | entier | — | Ce qui vous revient, commission prise. |
| `refunded` | entier | — | Ce qui a été rendu aux payeurs sur la période. |
| `payments_succeeded` | entier | — | Les paiements réussis. |
| `payments_concluded` | entier | — | Les paiements qui ont eu au moins une demande terminée. |
| `success_rate` | nombre ou null | — | Réussis sur conclus, entre 0 et 1. Null sans paiement conclu. |
| `previous` | objet ou null | — | Les mêmes chiffres sur la période de comparaison. Null avec « compare=none ». |
| `livemode` | vrai ou faux | — | Faux en mode test : aucun argent ne circule. |

## La demande

```bash
curl -G https://api.payiz.app/v1/reports/summary \
  -H "Authorization: Bearer sk_test_…" \
  -d from=2026-09-01 \
  -d to=2026-09-30
```

## La réponse

```json
{
  "object": "report_summary",
  "from": "2026-09-01",
  "to": "2026-09-30",
  "timezone": "Africa/Porto-Novo",
  "currency": "XOF",
  "amount_paid": 514000,
  "fee": 14622,
  "net": 499378,
  "refunded": 20500,
  "payments_succeeded": 39,
  "payments_concluded": 47,
  "success_rate": 0.8298,
  "previous": {
    "from": "2026-08-01",
    "to": "2026-08-31",
    "amount_paid": 10000,
    "fee": 350,
    "net": 9650,
    "refunded": 0,
    "payments_succeeded": 2,
    "payments_concluded": 2,
    "success_rate": 1
  },
  "livemode": false
}
```