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

# Sandbox

> Testez tout le cycle de vie d'un paiement sans mouvement d'argent — les résultats sont choisis par le numéro de téléphone.

Le sandbox est un déploiement séparé, avec sa propre base de données et ses propres
identifiants. Rien de ce que vous y faites ne touche l'argent, les marchands ou les
soldes réels.

```bash Sandbox theme={null}
https://sandbox.kori.ml
```

Créez un compte sur `sandbox.kori.ml` pour obtenir des clés API de sandbox. Elles ne sont
pas interchangeables avec les clés de production, et aucun des deux environnements ne voit
les données de l'autre.

## Ce n'est pas une simulation de façade

Un paiement de sandbox emprunte le même chemin qu'un paiement réel. Seul l'opérateur
mobile money est simulé ; tout ce qui vient après est le code de production. L'endpoint de
statut, le règlement, votre solde, le webhook `payment_received` avec une vraie signature,
le réconciliateur et l'expiration au bout de 24 heures se comportent exactement comme en
production.

Cela vaut aussi pour le temps : **un paiement ne se règle pas instantanément.** Il reste
`pending` quelques secondes, de sorte qu'un code supposant une réponse immédiate échoue
ici plutôt qu'en production.

## Choisir le résultat

Le résultat est déterminé par le **numéro de téléphone du client**. Votre corps de requête
est strictement identique à celui que vous enverrez en production : aucun champ réservé
aux tests à penser à retirer.

| Numéro            | Résultat                        | Ce que cela permet de tester                                       |
| ----------------- | ------------------------------- | ------------------------------------------------------------------ |
| `+22370000000`    | Réussit après quelques secondes | Le cas nominal : règlement, crédit, `payment_received`             |
| `+22370000001`    | Échoue                          | Un refus de l'opérateur, ou un client qui annule                   |
| `+22370000002`    | N'est jamais confirmé           | Reste `pending`, puis `expired` après 24 h — un paiement abandonné |
| `+22370000003`    | L'opérateur ne répond jamais    | Le cas du timeout, qui n'est **pas** un échec                      |
| Tout autre numéro | Réussit                         | Tests courants                                                     |

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

La réponse est un `202` avec `status: "pending"`, exactement comme en production.
Quelques secondes plus tard, le paiement se résout en `failed` — et si vous avez
enregistré un webhook, vous recevez l'événement.

<Tip>
  `GET /merchant/api/sandbox/test-numbers` renvoie ce tableau en JSON, avec le délai de
  règlement en vigueur.
</Tip>

## Quoi tester avec chaque numéro

Utilisez les numéros spéciaux pour prouver que votre intégration résiste aux cas
difficiles à reproduire en production :

* **`...0002` (jamais confirmé)** — votre commande reste-t-elle en attente au lieu d'être
  marquée comme échouée ? C'est le bug d'intégration le plus fréquent.
* **`...0003` (timeout)** — réessayez-vous au lieu de traiter cela comme un refus ? Un
  timeout signifie que la réponse est inconnue, et le paiement peut encore aboutir.
* **`...0001` (échec)** — laissez-vous le client réessayer, et évitez-vous un double débit
  lorsqu'il le fait ?

## Le checkout hébergé de Wave

En production, les paiements Wave renvoient un `payment_url` : le client valide sur la
page de Wave. Dans le sandbox, cette URL pointe vers une page de substitution qui rejoue
la même redirection, ce qui rend testable l'aller-retour vers votre `return_url` (avec
`?ref=`). Le résultat reste déterminé par le numéro de téléphone : valider sur la page ne
change rien.

## Payouts

Les comptes marchands de sandbox sont crédités d'un solde de test, vous pouvez donc créer
des payouts immédiatement. Les mêmes numéros s'appliquent : versez vers `+22370000001`
pour voir un échec recréditer le solde.

<Note>
  Les minimums s'appliquent dans le sandbox comme en production : **100 XOF** pour
  encaisser, **1 000 XOF** pour envoyer. Voir [Introduction](/fr/introduction).
</Note>