Sign in Get started

Payments & Money APIs · Capstone

Capstone: Food-Delivery Marketplace Payments

Design charging, payouts, ledger and reconciliation for a three-sided marketplace.

Scenario

A food-delivery platform charges customers (cards, wallets, local methods in 4 countries), pays restaurants weekly and couriers daily, keeps a commission, adds tips (100% to couriers) and handles substitutions that lower the final amount. 300k orders/day, peak at dinner. Refunds are common for missing items; disputes are 0.4% of orders.

Requirements

  • No double charges
  • Correct amounts after substitutions
  • Accurate payouts to restaurants and couriers
  • Auditable money movement

Constraints

  • Use a PSP platform product
  • 4 currencies
  • Finance closes books daily

Deliverables

  1. Design the charging flow and payment states.
  2. Design the ledger, payouts and refunds/disputes handling.
  3. Design reconciliation and controls.

Hints

  • Write the ledger entries for one order end to end, including a tip and a partial refund.
  • Decide who bears each kind of refund before designing APIs.

Draft each deliverable below before revealing the model answer and rubric.

Further reading: Stripe Connect: Charge types

Deliverables

Design the charging flow and payment states.

Model answer

Server-computed quote (prices, fees, tax, tip) → PaymentIntent with manual capture authorized at checkout (idempotency keys: client Idempotency-Key → API; deterministic pay:{order}:{attempt} → PSP) → order state machine (pending_payment → authorized → paid → refunded/disputed). Capture on delivery with partial capture for substitutions; void on cancellation; sweeper for auth expiry. Webhooks verified, deduped, processed async with re-fetch; outbox events to dispatch/fulfilment.

Rubric

Strong answers use manual + partial capture for variable amounts and show idempotency at every hop. Misses: client-supplied amounts; fulfilment on redirect.

Design the ledger, payouts and refunds/disputes handling.

Model answer

Connected accounts for restaurants/couriers (PSP KYC); separate charges and transfers per order (restaurant share, courier fee + 100% tip, platform commission). Double-entry ledger per currency: customer charge → psp_clearing; allocations to restaurant_payable, courier_payable, commission_revenue, tax_payable; fees_expense. Refunds: policy on who bears cost (missing item → restaurant), reversing entries + transfer reversals; disputes: evidence (delivery photos, GPS, receipts), dispute fees booked; don't refund disputed charges. Weekly/daily payouts with reserves.

Rubric

Look for explicit allocation of each component (tips!), who bears refunds, and reversal entries rather than edits.

Design reconciliation and controls.

Model answer

Daily three-way reconciliation: orders/ledger ↔ PSP balance transactions (charges, refunds, fees, transfers) ↔ bank payouts; clearing accounts must net to zero; exception queue with SLAs; backfill job for missed webhooks. Controls: refund limits and approvals, MFA + least privilege for PSP dashboard, restricted API keys, PCI scope minimized with PSP hosted fields/SDKs, fraud velocity rules and risk review with manual capture, dispute-rate monitoring per country.

Rubric

Strong answers make reconciliation daily and automated and include operational controls around refunds and dashboard access.

Open in the app to mark lessons complete, take notes and track your progress.