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

# Démarrage rapide

> Créez votre premier paiement avec l API CaurisFlux

Ce guide vous accompagne dans la création de votre premier paiement, de la configuration initiale à la réception du webhook de confirmation.

## 1. Obtenir vos clés API

<Steps>
  <Step title="Créer un compte">
    Inscrivez-vous sur [dash-app.caurisflux.com](https://dash-app.caurisflux.com)
  </Step>

  <Step title="Accéder aux clés API">
    Dans le Dashboard, allez dans **Paramètres > Clés API**
  </Step>

  <Step title="Copier les clés de test">
    Vous trouverez deux types de clés :

    * `pk_test_*` : Clé publique
    * `sk_test_*` : Clé secrète (côté serveur uniquement)
  </Step>
</Steps>

<Warning>
  Ne partagez jamais vos clés secrètes (`sk_*`). Elles donnent un accès complet à votre compte.
</Warning>

## 2. Comprendre les environnements

| Environnement  | Préfixe des clés        | URL de base                                 | Usage                  |
| -------------- | ----------------------- | ------------------------------------------- | ---------------------- |
| **Sandbox**    | `pk_test_` / `sk_test_` | `https://sandbox-api.caurisflux.com/api/v1` | Développement et tests |
| **Production** | `pk_live_` / `sk_live_` | `https://prod-api.caurisflux.com/api/v1`    | Transactions réelles   |

En sandbox, les paiements sont simulés. Aucun mouvement de fonds n'est effectué.

## 3. Récupérer les méthodes de paiement disponibles

Avant d'initier un paiement, récupérez les méthodes disponibles pour le pays via `GET /payments/providers?country=SN&currency=XOF`.

**Informations retournées par provider :**

* `name` : Nom du provider (Wave, Orange Money, etc.)
* `providerCode` : Code à utiliser dans l'API
* `minAmount` / `maxAmount` : Limites de montant
* `currencies` : Devises supportées

## 4. Créer un paiement

### Option A : Paiement Direct (Mobile Money)

Utilisez cette méthode quand vous connaissez le provider choisi par le client.

**Endpoint** : `POST /payments/initiate`

**Paramètres requis :**

* `type` : `direct`
* `provider` : Code du provider (wave, orange\_money, etc.)
* `country` : Code pays (SN, CI, etc.)
* `amount` : Montant en centimes
* `currency` : Devise (XOF, XAF)
* `customerPhone` : Numéro du client
* `callbackUrl` : URL de votre webhook
* `returnUrl` : URL de redirection après paiement

**Réponse :**

* `transactionId` : Identifiant unique de la transaction
* `status` : Statut initial (`pending`)
* `redirectUrl` : URL où rediriger le client

### Option B : Paiement Checkout (Page hébergée)

Le client sera redirigé vers la page CaurisFlux pour choisir sa méthode de paiement.

**Paramètres :**

* `type` : `checkout`
* Pas besoin de spécifier le `provider`

## 5. Rediriger le client

Redirigez l'utilisateur vers l'URL `redirectUrl` retournée par l'API.

Le client sera redirigé vers une page de paiement où il pourra :

1. Confirmer le montant
2. Valider le paiement via son application Mobile Money
3. Être redirigé vers votre `returnUrl` après paiement

## 6. Recevoir la confirmation par webhook

La redirection vers `returnUrl` ne garantit pas que le paiement est réussi. Vous devez configurer un webhook pour recevoir la confirmation.

### Configurer le webhook

1. Dans le Dashboard, allez dans **Paramètres > Webhooks**
2. Cliquez sur **Ajouter un endpoint**
3. Entrez l'URL de votre serveur (ex: `https://votresite.com/webhooks/cauris`)
4. Sélectionnez les événements à recevoir
5. Copiez le **Webhook Secret** généré

### Traiter le webhook

1. **Vérifier la signature** avec le header `x-cauris-signature`
2. **Traiter l'événement** selon le type (`payment.completed`, `payment.failed`)
3. **Répondre rapidement** avec un status 200

### Événements principaux

| Événement           | Description                            |
| ------------------- | -------------------------------------- |
| `payment.completed` | Paiement confirmé et réussi            |
| `payment.failed`    | Paiement échoué                        |
| `payment.expired`   | Paiement expiré (non complété à temps) |

## 7. Vérifier le statut d'un paiement

Vous pouvez vérifier le statut via `GET /payments/status/:transactionId`.

## 8. Tester avec des numéros de simulation

En sandbox, utilisez ces numéros pour simuler différents scénarios :

| Numéro          | Résultat                   |
| --------------- | -------------------------- |
| `+221770000001` | Paiement réussi            |
| `+221770000010` | Solde insuffisant          |
| `+221770000011` | Transaction refusée        |
| `+221770000020` | Reste en attente (timeout) |

## Flux complet

1. **Client passe commande** sur votre site
2. **Votre serveur appelle** `POST /payments/initiate`
3. **CaurisFlux retourne** l'URL de redirection
4. **Client est redirigé** vers la page de paiement
5. **Client valide** avec son PIN Mobile Money
6. **CaurisFlux envoie** le webhook de confirmation
7. **Votre serveur met à jour** la commande
8. **Client est redirigé** vers votre page de succès

## Prochaines étapes

<CardGroup cols={2}>
  <Card title="Authentification" icon="key" href="/guides/authentication">
    Clés API et sécurisation des appels
  </Card>

  <Card title="Payouts" icon="money-bill-transfer" href="/guides/payouts">
    Décaissements Mobile Money et virements
  </Card>

  <Card title="Mode test" icon="flask" href="/guides/testing">
    Tous les numéros et cartes de test
  </Card>

  <Card title="Webhooks" icon="webhook" href="/guides/webhooks">
    Configuration avancée des webhooks
  </Card>
</CardGroup>