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

# Flux de paiement

> Flux de paiement Stripe Connect avec entiercement et reversement aux transporteurs

# Flux de paiement

ColisMove utilise **Stripe Connect** pour gérer les paiements en toute sécurité. Les fonds sont capturés immédiatement et conservés en entiercement (escrow) sur la plateforme jusqu'à la confirmation de livraison.

## Architecture

```mermaid theme={null}
flowchart LR
    Sender -->|Pays| Stripe
    Stripe -->|Holds in escrow| Platform[ColisMove Platform]
    Platform -->|On delivery| Transfer[Stripe Transfer]
    Transfer -->|85%| Carrier[Carrier Account]
    Transfer -->|15%| Fee[Platform Fee]
```

## Cycle de vie du paiement

### 1. Créer une session Checkout

```bash theme={null}
POST /v1/api/payments/checkout
{
  "reservationId": 123
}
```

Renvoie une URL Stripe Checkout. Rediriger l'utilisateur vers cette URL pour finaliser le paiement.

### 2. Confirmation du paiement

Après un paiement réussi, Stripe envoie un webhook (`checkout.session.completed`) qui :

* Lie le PaymentIntent à la réservation
* Capture le paiement immédiatement
* Met à jour le statut de la réservation à `RESERVATION_PAYEE`

### 3. Vérifier le statut du paiement

```bash theme={null}
GET /v1/api/payments/checkout/{reservationId}/status
```

Renvoie : `{ "status": "PAID", "amount": 2500, "currency": "EUR" }`

### 4. Livraison & reversement

Lorsque la livraison est confirmée via QR code :

1. Un Stripe Transfer est créé vers le Connected Account du transporteur
2. La commission plateforme de 15 % est retenue
3. Le solde du portefeuille du transporteur est mis à jour

### 5. Reçu

```bash theme={null}
GET /v1/api/invoices/reservation/{reservationId}/receipt
```

Renvoie l'URL du reçu hébergé par Stripe pour affichage dans l'application.

## Onboarding Stripe Connect

Les transporteurs doivent finaliser leur onboarding Stripe Connect avant de pouvoir recevoir des paiements :

```bash theme={null}
POST /v1/api/stripe-connect/onboarding
```

Renvoie une URL d'onboarding où le transporteur saisit ses informations bancaires.

<Info>
  Les transporteurs peuvent vérifier leur statut d'onboarding via `GET /v1/api/stripe-connect/status`. Les paiements ne peuvent être reçus qu'une fois `chargesEnabled` et `payoutsEnabled` tous deux à `true`.
</Info>

## Portefeuille & retraits

Les gains du transporteur s'accumulent dans son portefeuille ColisMove :

* **Consulter le solde** : `GET /v1/api/user/wallet`
* **Demander un retrait** : `POST /v1/api/withdrawals/request`
* **Retrait automatique** : `PUT /v1/api/withdrawals/auto-config`