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

# Introduction

> Encaissez et versez des paiements mobile money au Mali avec l'API Marchand Kori.

L'**API Marchand Kori** permet à votre application d'encaisser des paiements auprès de
vos clients, de verser des fonds, de lancer des payouts et des paiements en masse, de
créer des liens de paiement et de gérer votre équipe — le tout en mobile money
(Orange Money, Wave, Moov).

Tout ce qui est documenté ici s'utilise avec une **clé API marchand**, avec exactement
les permissions (« scopes ») affichées dans l'écran **Clés API** de votre tableau de
bord Kori.

<Note>
  **Tous les montants sont en XOF** (franc CFA ouest-africain), la devise dans laquelle
  les opérateurs mobile money du Mali règlent. Le XOF n'a pas de sous-unité : `5000`
  signifie 5 000 francs — jamais des centimes. Le champ `currency` vaut `XOF` par défaut
  et c'est la seule valeur que l'API renvoie.

  Les minimums diffèrent selon le sens : **100 XOF** pour encaisser un paiement,
  **1 000 XOF** pour en envoyer un (payouts, paiements en masse et `/deposit`). En
  dessous, la requête est rejetée avec un `400` et un message indiquant le minimum.
</Note>

<CardGroup cols={2}>
  <Card title="Démarrage rapide" icon="rocket" href="/fr/quickstart">
    Effectuez votre première requête authentifiée en quelques minutes.
  </Card>

  <Card title="Authentification" icon="key" href="/fr/authentication">
    Échangez votre clé et votre secret contre un token Bearer.
  </Card>

  <Card title="Scopes" icon="shield-check" href="/fr/scopes">
    Comprenez ce que chaque permission d'une clé API autorise.
  </Card>

  <Card title="Référence API" icon="code" href="/fr/api-reference">
    Référence complète des endpoints, avec les schémas de requête et de réponse.
  </Card>
</CardGroup>

## URL de base

<CodeGroup>
  ```bash Production theme={null}
  https://api.kori.ml
  ```

  ```bash Sandbox theme={null}
  https://dev.kori.ml
  ```
</CodeGroup>

Tous les endpoints marchands sont servis sous le chemin `/merchant/api`, par exemple
`https://api.kori.ml/merchant/api/balance`.

## Fonctionnement

<Steps>
  <Step title="Créez une clé API">
    Dans le tableau de bord, ouvrez **Clés API** et créez une clé. Choisissez les scopes
    qu'elle doit porter (par exemple `pay`, `balance`, `webhooks`). Vous recevez une
    **clé** API (`mk_...`) et un **secret** (`ms_...`).
  </Step>

  <Step title="Obtenez un token">
    Appelez [`POST /merchant/api/auth`](/fr/authentication) avec votre clé et votre
    secret pour recevoir un token Bearer de courte durée portant vos scopes.
  </Step>

  <Step title="Appelez l'API">
    Envoyez le token dans `Authorization: Bearer <token>` à chaque requête. Chaque
    endpoint vérifie le scope qu'il exige.
  </Step>

  <Step title="Recevez les webhooks">
    Enregistrez un endpoint [webhook](/fr/webhooks) pour être notifié quand un paiement
    est confirmé, qu'un payout aboutit, et plus encore.
  </Step>
</Steps>

## Format des réponses

Toutes les réponses utilisent la même enveloppe :

```json theme={null}
{
  "success": true,
  "message": "Balance retrieved successfully",
  "request_id": "b2f1c3a0-...",
  "data": { "...": "..." }
}
```

En cas d'erreur, `success` vaut `false` et `message` explique le problème. Voir
[Erreurs](/fr/errors).

<Note>
  **Les encaissements sont asynchrones.** `POST /merchant/api/pay` renvoie un `202` avec
  `status: "pending"` — le client a seulement reçu une demande de confirmation. Ne
  considérez une commande comme payée qu'après le webhook `payment_received`. Voir
  [Webhooks](/fr/webhooks).
</Note>