> ## 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.

# Démarrage rapide

> Authentifiez-vous et encaissez votre premier paiement.

Ce guide vous mène d'une clé API à un encaissement réel en quatre requêtes.

## Prérequis

* Un compte marchand Kori avec une **clé API** et un **secret** (tableau de bord →
  **Clés API**).
* La clé doit porter les scopes que vous utiliserez ici : `pay` et `balance`.

<Tip>
  Utilisez l'URL de base **Sandbox** `https://dev.kori.ml` pendant vos tests.
</Tip>

## 1. Obtenir un token

Échangez votre clé et votre secret contre un token Bearer. Ne demandez que les scopes
dont vous avez besoin.

```bash theme={null}
curl -X POST https://api.kori.ml/merchant/api/auth \
  -H "X-API-Key: mk_votre_cle_api" \
  -H "X-API-Secret: ms_votre_secret_api" \
  -H "Content-Type: application/json" \
  -d '{ "scopes": ["pay", "balance"], "expires_in_hours": 24 }'
```

```json Réponse theme={null}
{
  "success": true,
  "message": "Authentication successful",
  "data": {
    "token": "eyJhbGciOiJIUzI1Ni...",
    "token_type": "Bearer",
    "scopes": ["pay", "balance"],
    "expires_in": 86400,
    "expires_at": "2026-08-09T12:00:00.000Z"
  }
}
```

Conservez `data.token` : vous l'enverrez à chaque requête suivante.

## 2. Consulter votre solde

```bash theme={null}
curl https://api.kori.ml/merchant/api/balance \
  -H "Authorization: Bearer <token>"
```

## 3. Encaisser un paiement

Le téléphone du client reçoit une demande de confirmation.

```bash theme={null}
curl -X POST https://api.kori.ml/merchant/api/pay \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "payment_method": "OrangeMoney",
    "customer_phone": "+22370000000",
    "reference": "commande_1024",
    "description": "Commande n° 1024"
  }'
```

```json Réponse (202 Accepted) theme={null}
{
  "success": true,
  "message": "Payment initiated. Awaiting customer confirmation.",
  "data": {
    "transaction_id": 88213,
    "reference": "commande_1024",
    "amount": 5000,
    "currency": "XOF",
    "payment_method": "OrangeMoney",
    "status": "pending",
    "payment_url": null
  }
}
```

<Warning>
  `status: "pending"` signifie que la demande a été envoyée, **pas** que le client a payé.
  Ne livrez pas encore la commande.
</Warning>

## 4. Vérifier le statut du paiement

Trois moyens, par ordre de préférence — voir [Statut d'un paiement](/fr/payment-status)
pour le détail.

**Attendez le webhook.** Abonnez-vous à `payment_received` et Kori vous prévient : aucun
polling, et la notification arrive même si le client ferme son navigateur.

**Lisez votre transaction :**

```bash theme={null}
curl https://api.kori.ml/merchant/api/transactions/88213 \
  -H "Authorization: Bearer <token>"
```

**Ou interrogez l'opérateur maintenant**, par `reference` — c'est la réponse faisant
autorité tant que le paiement est en cours, et elle ne demande aucun token : une page de
paiement peut donc l'interroger directement depuis le navigateur.

```bash theme={null}
curl https://api.kori.ml/merchant/api/payment/status/commande_1024
```

```json theme={null}
{ "message": "SUCCESS", "state": "success", "status": true }
```

Quand le statut passe à `success`, les fonds sont crédités sur votre solde et vous pouvez
livrer la commande. Tant qu'il est `pending`, le client n'a simplement pas encore
répondu — ce n'est pas un échec : patientez plutôt que de relancer le paiement.

## Pour aller plus loin

<CardGroup cols={2}>
  <Card title="Scopes" icon="shield-check" href="/fr/scopes">
    Toutes les permissions qu'une clé API peut accorder.
  </Card>

  <Card title="Webhooks" icon="bell" href="/fr/webhooks">
    Soyez notifié quand un paiement est confirmé.
  </Card>

  <Card title="Statut d'un paiement" icon="clock" href="/fr/payment-status">
    En attente, réussi ou échoué — et comment les distinguer.
  </Card>
</CardGroup>