Skip to main content

​
Payment Flow

ColisMove uses Stripe Connect to handle payments securely. Funds are captured immediately and held in platform escrow until delivery is confirmed.

​
Architecture

​
Payment Lifecycle

​
1. Create Checkout Session

POST /v1/api/payments/checkout
{
  "reservationId": 123
}
Returns a Stripe Checkout URL. Redirect the user to this URL to complete payment.

​
2. Payment Confirmation

After successful payment, Stripe sends a webhook (checkout.session.completed) which:
  • Links the PaymentIntent to the reservation
  • Captures the payment immediately
  • Updates reservation status to RESERVATION_PAYEE

​
3. Check Payment Status

GET /v1/api/payments/checkout/{reservationId}/status
Returns: { "status": "PAID", "amount": 2500, "currency": "EUR" }

​
4. Delivery & Payout

When the delivery is confirmed via QR code:
  1. A Stripe Transfer is created to the carrier’s Connected Account
  2. The 15% platform fee is retained
  3. The carrier’s wallet balance is updated

​
5. Receipt

GET /v1/api/invoices/reservation/{reservationId}/receipt
Returns the Stripe-hosted receipt URL for in-app viewing.

​
Stripe Connect Onboarding

Carriers must complete Stripe Connect onboarding before receiving payments: 
POST /v1/api/stripe-connect/onboarding
Returns an onboarding URL where the carrier enters their banking details.
Carriers can check their onboarding status via GET /v1/api/stripe-connect/status. Payments can only be received once chargesEnabled and payoutsEnabled are both true.

​
Wallet & Withdrawals

Carrier earnings accumulate in their ColisMove wallet:
  • View balance: GET /v1/api/user/wallet
  • Request withdrawal: POST /v1/api/withdrawals/request
  • Auto-withdrawal: PUT /v1/api/withdrawals/auto-config