Skip to main content

​
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

​
Cycle de vie du paiement

​
1. Créer une session Checkout

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

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

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 : 
POST /v1/api/stripe-connect/onboarding
Renvoie une URL d’onboarding où le transporteur saisit ses informations bancaires.
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.

​
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