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

# Initier un paiement

> Créer un nouveau paiement (collect)

Initie un paiement (collect) pour recevoir de l'argent d'un client.

### Authentification

```bash theme={null}
X-API-Key: pk_test_xxx:sk_test_xxx
```

### Headers optionnels

| Header              | Description                                              |
| ------------------- | -------------------------------------------------------- |
| `X-Idempotency-Key` | Clé unique pour éviter les doublons (ex: ID de commande) |

## Types de paiement

### Paiement Direct

Le client paie avec un provider spécifique (Wave, Orange Money, etc.).

```bash theme={null}
curl -X POST https://sandbox-api.caurisflux.com/api/v1/payments/initiate \
  -H "X-API-Key: pk_test_xxx:sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: COMMANDE-12345" \
  -d '{
    "type": "direct",
    "provider": "wave",
    "country": "SN",
    "amount": 10000,
    "currency": "XOF",
    "externalReference": "COMMANDE-12345",
    "customerPhone": "+221771234567",
    "customerName": "Amadou Diallo",
    "customerEmail": "amadou@example.com",
    "description": "Achat sur MaBoutique.sn",
    "callbackUrl": "https://votresite.com/webhooks/cauris",
    "returnUrl": "https://votresite.com/paiement/succes",
    "cancelUrl": "https://votresite.com/paiement/annule",
    "metadata": {
      "orderId": "12345",
      "customerType": "premium"
    }
  }'
```

### Paiement Checkout

Le client est redirigé vers la page CaurisFlux pour choisir sa méthode.

```bash theme={null}
curl -X POST https://sandbox-api.caurisflux.com/api/v1/payments/initiate \
  -H "X-API-Key: pk_test_xxx:sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "checkout",
    "amount": 25000,
    "currency": "XOF",
    "externalReference": "PANIER-67890",
    "customerName": "Fatou Sow",
    "customerEmail": "fatou@example.com",
    "description": "Panier #67890 - 3 articles",
    "callbackUrl": "https://votresite.com/webhooks/cauris",
    "returnUrl": "https://votresite.com/commande/67890/merci",
    "cancelUrl": "https://votresite.com/panier"
  }'
```

## Paramètres

### Champs requis

| Champ               | Type   | Description                          |
| ------------------- | ------ | ------------------------------------ |
| `type`              | string | `direct` ou `checkout`               |
| `amount`            | number | Montant du paiement                  |
| `externalReference` | string | Votre référence unique (ID commande) |

### Champs requis pour type "direct"

| Champ           | Type   | Description                                  |
| --------------- | ------ | -------------------------------------------- |
| `provider`      | string | Code du provider (wave, orange\_money, etc.) |
| `country`       | string | Code ISO du pays (SN, CI, ML, etc.)          |
| `customerPhone` | string | Numéro du client (format E.164)              |

### Champs optionnels

| Champ           | Type   | Description                    |
| --------------- | ------ | ------------------------------ |
| `currency`      | string | Devise (défaut: XOF)           |
| `customerName`  | string | Nom du client                  |
| `customerEmail` | string | Email du client                |
| `description`   | string | Description du paiement        |
| `callbackUrl`   | string | URL webhook pour notifications |
| `returnUrl`     | string | Redirection après succès       |
| `cancelUrl`     | string | Redirection après annulation   |
| `metadata`      | object | Données personnalisées (JSON)  |

## Réponse

```json theme={null}
{
  "success": true,
  "data": {
    "transactionId": "TX000007272",
    "status": "pending",
    "type": "collect",
    "amount": 10000,
    "currency": "XOF",
    "paymentMethod": {
      "code": "wave",
      "name": "Wave",
      "logoUrl": "https://s3.denkmako.com/cauris/logos/wave.png"
    },
    "country": "SN",
    "redirectUrl": "https://pay.wave.com/c/sn/~abc123",
    "externalReference": "COMMANDE-12345",
    "expiresAt": "2024-01-15T12:30:00.000Z",
    "createdAt": "2024-01-15T12:00:00.000Z",
    "metadata": {
      "orderId": "12345",
      "customerType": "premium"
    },
    "qrCode": null,
    "deepLinks": {
      "wave": "wave://pay?token=abc123"
    }
  }
}
```

### Champs de réponse

| Champ           | Type   | Description                           |
| --------------- | ------ | ------------------------------------- |
| `transactionId` | string | ID unique de la transaction           |
| `status`        | string | Statut initial (`pending`)            |
| `redirectUrl`   | string | URL de paiement (rediriger le client) |
| `expiresAt`     | string | Date d'expiration                     |
| `deepLinks`     | object | Liens deep pour apps mobiles          |

## Erreurs

```json theme={null}
{
  "statusCode": 400,
  "message": "Le montant doit être supérieur à 100 XOF",
  "error": "Bad Request"
}
```

| Code  | Message                 | Solution                         |
| ----- | ----------------------- | -------------------------------- |
| `400` | Montant invalide        | Vérifiez les limites du provider |
| `400` | Provider non disponible | Utilisez `/payments/providers`   |
| `401` | Non authentifié         | Vérifiez vos clés API            |