Stripe Connect Split Payments with NestJS: A Real Marketplace Guide

const paymentIntent = await this.stripe.paymentIntents.create({
  amount: 5000,               // $50.00 total, in cents
  currency: 'usd',
  application_fee_amount: 750, // $7.50 platform commission
  transfer_data: {
    destination: driver.stripeAccountId,
  },
});

That is the entire split. The customer pays $50, the platform keeps $7.50, and $42.50 lands in the driver's connected account. No cron jobs, no manual transfers, no spreadsheet.

One thing that bit me early: always calculate the fee in cents on the server. I originally computed the commission on the client and sent it with the request. A curious user with dev tools open could have set their own commission. Everything money-related must live server side.

Step 3: Webhooks are the source of truth

A payment is not done when the API call returns. Cards get declined, banks reverse transactions, 3D Secure challenges expire. The only reliable record is the webhook stream, so my NestJS webhook controller is small but strict:

@Post('webhook')
async handleWebhook(@Req() req: RawBodyRequest<Request>) {
  const event = this.stripe.webhooks.constructEvent(
    req.rawBody,
    req.headers['stripe-signature'],
    process.env.STRIPE_WEBHOOK_SECRET,
  );

  switch (event.type) {
    case 'payment_intent.succeeded':
      await this.jobs.markPaid(event.data.object.metadata.jobId);
      break;
    case 'payment_intent.payment_failed':
      await this.jobs.markFailed(event.data.object.metadata.jobId);
      break;
    case 'account.updated':
      await this.drivers.syncAccountStatus(event.data.object);
      break;
  }
  return { received: true };
}

Two practical notes. First, NestJS parses JSON bodies by default, which breaks Stripe's signature check; you need the raw body (rawBody: true in NestFactory.create). Second, make every handler idempotent, because Stripe retries webhooks. Marking an already-paid job as paid again must be a no-op.

Step 4: Withdrawals and payout timing

Express accounts get automatic payouts on a rolling schedule by default, and for most drivers that is what they want. JobsiteX also offers an "instant withdraw" button that triggers an instant payout for a small fee where the driver's bank supports it:

await this.stripe.payouts.create(
  { amount: balance.available, currency: 'usd', method: 'instant' },
  { stripeAccount: driver.stripeAccountId },
);

What I would tell past me

• Start in test mode with Stripe's test connected accounts; you can simulate the entire onboarding and payout cycle without real money.
• Store Stripe IDs (customer, account, payment intent) on your own tables from day one. Debugging without them is painful.
• Put every amount in integer cents everywhere. Floating point money bugs are real and they are embarrassing.
• Read the fee documentation carefully: Stripe's processing fee comes out of the platform's side with destination charges, so price your commission with that in mind.

Stripe Connect took me about a week to integrate properly, and it removed an entire category of work: no payout scripts, no compliance headaches, no holding funds. If you are building any kind of marketplace with NestJS, it is the approach I would pick again.

See more of my work

Have a project that needs payments done right? Contact me and let's talk about it.