How to take a deposit and collect the remaining balance on Stripe

The short answer on Flint

A Flint invoice takes a payment schedule: a deposit due when you issue it and the balance on the due date, or up to 14 installments, by percentage, fixed amount, or whatever remains. The buyer pays each one from the same hosted invoice link, or, with automatic collection, Flint charges their saved card on each due date. Reminders and late fees run per installment, and the deposit, the balance, and any refund stay on one order. Card processing runs on Stripe underneath. The Flint request is below.

What Stripe offers for deposits

Invoice payment plans are the closest match. A plan divides one invoice into installments with their own due dates, such as a fixed-amount deposit followed by the rest, and Stripe sends a reminder for each. Stripe lists these limits:

• The feature is in private preview, requested through a form, with a preview API version.
• Plans don't auto-charge customers with saved payment details; customers return to the payment page for each later payment, and charge_automatically invoices can't use them.
• They can't be applied to subscription invoices.
• On Connect, application fees can't be set on a payment plan invoice.

Partial payments work on open invoices, except subscription invoices that Stripe charges automatically, which are in private preview: you attach a separate PaymentIntent for any amount up to what remains, or enable partial payments in your invoice settings so the customer can type an amount on the hosted invoice page. The customer chooses that amount, so it doesn't enforce a deposit.

Outside invoices, Stripe's guide to saving payment details lists charging a deposit and saving the card to charge the full amount later as a use case. The deposit is a Checkout payment; the balance is a PaymentIntent your server creates later with off_session.

The checkout deposit, in code

Charge the deposit and keep the card:

// 1. Charge the 25% deposit in Checkout and save the card for the balance
const session = await stripe.checkout.sessions.create({
  mode: "payment",
  customer: booking.stripeCustomerId,
  line_items: [{
    price_data: {
      currency: "usd",
      unit_amount: Math.round(booking.totalCents * 0.25),
      product_data: { name: `Deposit: ${booking.title}` },
    },
    quantity: 1,
  }],
  payment_intent_data: { setup_future_usage: "off_session" },
  metadata: { booking_id: booking.id, part: "deposit" },
  success_url: "https://example.com/booked?session_id={CHECKOUT_SESSION_ID}",
});

Then a job of yours charges the balance. Stripe's docs warn that when the conditions for an authentication exemption aren't met, an off-session PaymentIntent can throw an error, so the job needs a path back to the customer:

// 2. Your daily job charges the balance on the job date
for (const booking of await db.bookings.balanceDue(today())) {
  const balance = booking.totalCents - booking.paidCents; // recomputed from your records
  try {
    await stripe.paymentIntents.create(
      {
        amount: balance,
        currency: "usd",
        customer: booking.stripeCustomerId,
        payment_method: booking.savedPaymentMethodId,
        off_session: true,
        confirm: true,
        metadata: { booking_id: booking.id, part: "balance" },
      },
      { idempotencyKey: `balance-${booking.id}-${booking.balanceAttempt}` },
    );
  } catch (err) {
    // Declined, or the bank wants authentication the customer can't give
    // off-session. Email a link to pay on session, and retry on your schedule.
    await db.bookings.markBalanceFailed(booking.id, err.code);
    await sendPayBalanceEmail(booking);
  }
}

That is a bookings table with totals and payments, a scheduler, an email, a page where the customer pays the balance on session, and your own terms and consent for charging a saved card. These are the places it goes wrong:

Where hand-built deposits go wrong