# Conventions

Ce qui vaut partout : la base, les montants, les identifiants, les pages.
Une API REST en JSON, sous `https://api.payiz.app/v1`. Les montants sont entiers, les identifiants préfixés, et chaque erreur se lit.

- **Base** : `https://api.payiz.app/v1`.
- **Authentification** : `Authorization: Bearer sk_live_…`, toujours depuis votre serveur.
- **Montants entiers, dans l’unité mineure** de la devise, toujours avec la devise : `{ "amount": 5000, "currency": "XOF" }` vaut 5 000 F CFA — le franc CFA n’a pas de centimes, le naira en a deux.
- **Identifiants préfixés** : `pay_` un paiement, `tnt_` une demande envoyée au payeur, `rem_` un remboursement, `ret_` un retrait, `lnk_` un lien, `ben_` un bénéficiaire, `evt_` un événement, `req_` un appel.
- **Opérateurs en codes** : `operator` vaut un code court et stable, propre au pays — `mtn`, `moov`, `orange`. [GET /v1/payment_methods](https://docs.payiz.app/api/moyens/lister) les donne, avec leurs logos et leurs bornes.
- **Dates en secondes** depuis 1970, à l’entrée comme à la sortie.
- **Pagination** par curseur : `limit` (100 au plus) et `starting_after`, l’identifiant de la dernière ligne lue. Chaque liste rend `data` et `has_more`, du plus récent au plus ancien.
- **Mode test** : une clé `sk_test_` ne déplace aucun argent et parle au [simulateur](https://docs.payiz.app/simulateur). Chaque objet rendu porte `livemode`.

## Le contrat, en entier

La spécification OpenAPI 3.1 se lit sans clé, et s’importe dans vos outils : [https://api.payiz.app/v1/openapi.json](https://api.payiz.app/v1/openapi.json). C’est elle qui écrit cette page.

## /v1 ne casse pas

On ajoute des champs, on n’en retire pas, et on ne change pas le sens de ce qui existe. Ignorez les champs que vous ne connaissez pas. Une rupture ouvrirait un `/v2` — elle serait annoncée dans le [journal des changements](https://docs.payiz.app/changements), datée.