Charity Donation App

Reading guide This article is written for backend engineers preparing for system design interviews or building real-world payment-heavy systems.
By the end, you should be able to:

• Explain why a charity donation platform needs an intent-based payment model on top of Stripe PaymentIntents
• Sketch the end-to-end flow from “Click Donate” to eventual stats update
• Reason about idempotency, webhooks, reconciliation, and event-driven analytics under high load (10M+ donations in 3 days)

1. Overview

Summary
A high-volume charity donation platform using Stripe PaymentIntent and an internal intent-based state machine, with RabbitMQ for events and a reconciliation worker to guarantee no duplicate charges, no lost payments, and eventual consistency under load.
Scale assumptions
Total volume
~10M donations
Duration
3-day event
Peak load
hundreds QPS
Design assumptions
horizontal scaling of the Donation API, Stripe handling payment throughput, queue-based decoupling for stats and notifications
Design goals
No duplicate charges
At most one successful charge per donation intent.
Enforced via Stripe idempotency keys and an internal state machine.
No lost payments
Every intent reaches a terminal state (SUCCEEDED or FAILED).
Webhooks plus a reconciliation worker resolve PENDING/UNKNOWN against Stripe.
Eventual consistency
The system converges to a consistent state under failures or delayed webhooks.
State machine, webhooks, and reconciliation worker.
Minimal PCI exposure
Card data never touches our servers.
Client-side tokenization (Stripe Elements); minimal PCI scope.
Near real-time charity statistics
Per-charity totals updated and exposed at high QPS.
Event-driven updates via RabbitMQ and Redis cache.
Functional requirements
Core business flows supported by the system.
Create donation intent
User selects charity, amount, and payment method; system creates an internal intent and a Stripe PaymentIntent.
Returns intent ID and client secret to the client.
Confirm payment
User completes payment on the client (Stripe Elements).
Stripe handles tokenization, 3DS, and authorization; client receives success, failure, or pending.
Webhook handling
System receives Stripe webhooks (payment_intent.succeeded / payment_intent.payment_failed).
Updates intent status; publishes events for stats and notifications.
Charity stats
Per-charity totals (amount, count) updated eventually and exposed via API.
Read path cached (e.g. Redis) for high QPS.
Receipt / notification
User receives a receipt (e.g. email) after successful payment.
Sending is asynchronous and idempotent.
Reconciliation
System periodically resolves intents stuck in PENDING/UNKNOWN by querying Stripe.
Publishes reconciled events so stats and side effects stay consistent.
Multi-charity
Multiple charities supported; each donation tied to a charity.
Stats isolated per charity.
Non-functional requirements
System guarantees under expected and peak load.
No duplicate charges
At most one successful charge per donation intent.
Stripe idempotency keys and internal state machine.
No lost payments
Every intent eventually reaches SUCCEEDED or FAILED.
Webhooks plus reconciliation worker cover missed or delayed webhooks.
Scalability
System handles ~10M donations over 3 days.
Donation API and consumers scale horizontally; payment throughput delegated to Stripe.
Latency
Intent creation and redirect/confirmation stay within acceptable latency.
Heavy work (stats, email) off the hot path.
PCI / security
Card data never touches our servers.
Client-side tokenization (Stripe Elements); minimal PCI scope.
Observability
Monitoring and alerts for success rate, failure rate, UNKNOWN rate, webhook/queue lag, reconciliation backlog.
Availability
Payment and intent creation remain available under expected load.
Dependencies (DB, Stripe, queue) have clear failure modes and mitigations.

2. System Architecture

Core components and their responsibilities in the donation workflow.

Client (Web / iOS / Android)Client
Collects donation details and payment method; confirms payment via Stripe SDK.
No card data on our servers.
Donation API ServiceCore Service
Creates and tracks donation intents; issues Stripe PaymentIntents; handles webhooks; publishes events.
Central orchestration; horizontal scaling.
StripeExternal
Payment provider: PaymentIntents, tokenization, webhooks, idempotency.
Relational DatabaseStorage
Primary source of truth for donation_intents, webhook_events, charity_stats.
Single source of truth; scales with Donation API.
RabbitMQAsync
Message broker / event bus for donation.succeeded and downstream consumers.
Decouples payment path from stats and notifications.
Notification ConsumerAsync
Consumes events; sends receipts (e.g. email) with idempotency.
Reconciliation WorkerAsync
Scans PENDING/UNKNOWN intents; queries Stripe to finalize state.
Publishes reconciled events so stats and side effects stay consistent.
RedisStorage
Stats cache for high-QPS charity totals.
Read path for per-charity totals.

High-level architecture diagram (click to zoom):

3. Payment Model Overview (Stripe)

Capabilities provided by Stripe

PaymentIntents API
Create and confirm payment intents; single primitive for charge lifecycle.
Client-side tokenization (Stripe Elements)
Collect card details securely without touching our servers.
Webhooks
Real-time events for payment_intent.succeeded and payment_failed.
Idempotency Keys
At-most-once charge per key; we pass a key per donation intent.
Transaction lookup APIs
Query Stripe to resolve PENDING/UNKNOWN and reconcile state.

How this system uses them

Stripe
Stripe Elements
Minimizes PCI exposure; card data never touches our servers.
Stripe PaymentIntent
External payment execution primitive; we create and confirm via API.
Our system
Internal donation_intents table
Business-level intent state anchor; state machine lives here.

High-level idea

Money Flow
Stripe PaymentIntent is the source of truth.
Business Flow
Internal donation_intents table is the state machine.
Webhooks + a reconciliation worker bridge the two worlds and guarantee eventual consistency.

4. End-to-End Payment Flow

4.1 Sequence Diagram

Create Intent
1Client creates donation intent
2Server creates Stripe PaymentIntent
Payment Confirmation
3Client confirms payment
Webhook & Publish
4Stripe sends webhook
5System updates state + publishes event
Reconcile
6Reconciliation worker resolves pending/unknown states

System guarantees
No duplicate charges
Idempotency keys and webhook deduplication ensure at-most-once charge per intent.
No lost payments
Webhooks plus a reconciliation worker cover failures and long-running payments.
Eventual consistency
Stripe and internal state stay in sync via webhooks and reconciliation.

4.2 Detailed Flow (Stripe-based)

Phases
Intent Creation
SYNC
Flow: Client → API → DB → Stripe → Client
Main Flow
Client sends charityId, amount_cents, currency, email (optional request_id for idempotency).
Server validates input; uses Redis SETNX to lock request_id (5–10s) to prevent duplicate intent creation.
Insert row into donation_intents with status = CREATED; obtain intentId.
Create Stripe PaymentIntent with amount, currency, metadata: { intentId }.
Return intentId and client_secret to the client.
Guarantee: At-most-once intent creation
request_id → same intentId + client_secret (idempotent response).
Redis SETNX lock prevents duplicate inserts for the same request_id.
API / Webhook involved
POST/v1/donations/intent
DB writes
donation_intents (intent_id, status=CREATED, charity_id, amount_cents, stripe_payment_intent_id)
Failure & retry
Client retries with same request_id; server returns existing intent.
Stripe PaymentIntent create is retried with backoff.
Payment Confirmation
SYNC
Flow: Client → Stripe (no server in path)
Main Flow
User enters card details in Stripe-hosted fields (PCI-safe); client calls stripe.confirmCardPayment(client_secret).
Stripe handles tokenization, 3DS (SCA), authorization and capture.
Client receives immediate success/failure or "processing" (finalized later via webhook).
No server call in this step; Donation Service does not see card data.
Guarantee: No duplicate confirmations
Stripe deduplicates by PaymentIntent; same confirm returns same result.
Client can send optional request_id for idempotent UI retries.
API / Webhook involved
Stripe.js confirmCardPayment (client-side)
DB writes
None in this phase (state updated in Webhook Processing).
Failure & retry
Client retries confirmCardPayment; Stripe returns same result.
For "processing", wait for webhook; no server retry in this phase.
Webhook Processing
ASYNC
Flow: Stripe → API → DB + RabbitMQ
Main Flow
Stripe sends POST to /v1/webhooks/stripe: payment_intent.succeeded, payment_intent.payment_failed, payment_intent.processing.
Deduplicate by Stripe event_id (store in webhook_events or Redis); Redis SETNX lock per payment_intent (5–10s).
Read intentId from PaymentIntent metadata; update donation_intents to SUCCEEDED or FAILED.
Publish domain event to RabbitMQ (e.g. donation.succeeded) for stats and email consumer.
Guarantee: At-most-once webhook processing
event_id stored; at-most-once processing per event.
Redis lock per payment_intent (5–10s) prevents duplicate handler runs.
API / Webhook involved
POST/v1/webhooks/stripe
payment_intent.succeeded / payment_failed / processing
DB writes
webhook_events (event_id); donation_intents (status); outbox if used.
Failure & retry
Stripe retries webhook with exponential backoff.
Return 200 after processing to avoid duplicate delivery.
Reconciliation / Convergence
RECONCILE
Flow: Worker → Stripe API → DB + RabbitMQ
Main Flow
Reconciliation worker periodically scans donation_intents with status PENDING or UNKNOWN.
Queries Stripe API for each PaymentIntent to get final state (succeeded, failed, expired).
Updates donation_intents to SUCCEEDED / FAILED / EXPIRED; publishes reconciled events to RabbitMQ.
Downstream consumers (stats, email) process events idempotently; DB and Redis converge.
Guarantee: Read-only convergence, no duplicate charges
Worker updates only if internal state still PENDING/UNKNOWN (read-only convergence).
Consumers use event_id or intent_id for dedupe; no duplicate charges from reconciliation.
API / Webhook involved
Stripe API: retrieve PaymentIntent (server-side)
DB writes
donation_intents (status); charity_stats; Redis cache (per-charity totals).
Failure & retry
Worker retries on next run; Stripe API retries with backoff.
Read-only reconciliation; no duplicate charges.
Guarantee mappingWhich phases enforce each guarantee
No duplicate charges
Intent Creation (request_id + Redis lock), Webhook Processing (event_id + Redis lock per payment_intent).
No lost payments
Webhook Processing (Stripe retries); Reconciliation (worker resolves PENDING/UNKNOWN and long-running processing).
Eventual consistency
Webhook Processing (updates DB + publish); Reconciliation (worker converges state); consumers (idempotent stats + Redis).

5. Payment State Machine

Visual flow
PENDING→PROCESSING→SUCCEEDED/FAILED
State definitions
PENDING
Intent created; payment not yet attempted.
Created when client requests an intent with charityId, amount, and optional request_id. Redis SETNX lock for idempotency.
PROCESSING
Payment in progress; waiting for Stripe and webhook.
Intent stays here until Stripe confirms success, failure, or timeout. Webhook or reconciliation will transition to final state.
SUCCEEDED
Payment succeeded. Final state.
Stats and side effects (e.g. notifications) are driven by events. No further transitions allowed.
FAILED
Payment failed or expired. Final state.
failure_reason is recorded. No further charge attempts.
Transition table
Initial state
Event
Target state
Action
PENDING
Client confirms payment
PROCESSING
Call Stripe; create/update PaymentIntent
PROCESSING
Webhook: payment_intent.succeeded
SUCCEEDED
Update intent; publish donation.succeeded
PROCESSING
Webhook: payment_intent.payment_failed
FAILED
Update intent; set failure_reason
PROCESSING
Reconciliation (timeout)
FAILED
Resolve via Stripe API
LOGIC HIGHLIGHTING
Transition guard
Only when current state is PROCESSING (or UNKNOWN for reconciliation) do we accept a webhook update to SUCCEEDED. Use WHERE status IN ('PROCESSING', 'UNKNOWN') and atomic update so only one transition wins.
Idempotency
Same request_id returns the same intent_id and client_secret. Redis SETNX lock prevents duplicate intent creation. Once in SUCCEEDED or FAILED, no further charge is possible.
Concurrency handling
Webhook and reconciliation may both try to update the same intent. Use atomic updates and publish events after DB commit for eventual consistency.

Pending/Unknown intents
Reconciliation Worker
Query Stripe API
Stripe response
Update donation_intents
Publish reconciled event
Final
SUCCEEDEDFAILEDEXPIRED

Principle
When Stripe returns `processing`, do **not** mark the intent as failed. Use **exponential backoff** to reschedule checks and a **final TTL** (e.g. 24h); only then mark as **EXPIRED** if still unresolved.

JavaCopy
1public void reconcileProcessingIntent(DonationIntent intent, PaymentIntent stripeIntent) {
2    // Check if the intent is still processing
3    // See Stripe docs: https://stripe.com/docs/payments/payment-intents/lifecycle
4    if ("processing".equals(stripeIntent.getStatus())) {
5        System.out.println("Processing intent " + intent.getId());
6
7        // TODO: Calculate the next retry time with exponential backoff
8        // e.g. 5m, 15m, 1h, 4h...
9        Instant nextCheckTime = calculateNextRetry(intent.getRetryCount());
10
11        // Check if we've exceeded the maximum TTL (e.g. 24 hours)
12        boolean isExpired = intent.getCreatedAt()
13            .plus(Duration.ofHours(MAX_TTL_HOURS))
14            .isBefore(Instant.now());
15
16        if (isExpired) {
17            // TODO: Mark as EXPIRED or verify one last time
18            donationIntentRepository.updateStatus(intent.getId(), IntentStatus.EXPIRED);
19        } else {
20            // Update the intent with the new retry time and status
21            donationIntentRepository.update(intent.getId(), UpdateIntent.builder()
22                .nextReconcileAt(nextCheckTime)
23                .retryCount(intent.getRetryCount() + 1)
24                .lastStripeStatus("processing")
25                .build());
26        }
27    }
28}

SQLCopy
1WHERE status IN ('PAYMENT_PENDING', 'UNKNOWN') AND next_reconcile_at <= NOW()

SQLCopy
1-- Read then write: another request can overwrite your update
2SELECT total_amount_cents FROM charity_stats WHERE charity_id = 1;
3-- application: new_total = old + 50
4UPDATE charity_stats SET total_amount_cents = 150 WHERE charity_id = 1;

SQLCopy
1UPDATE charity_stats
2SET total_amount_cents = total_amount_cents + :amount_cents,
3    donation_count = donation_count + 1,
4    updated_at = NOW()
5WHERE charity_id = :charity_id;

TABLE
donation_intents
Copy SQL
One row per user donation intent, used as the durable business anchor for Stripe PaymentIntents.
intent_idUUIDPK
Internal business identifier for the donation intent (also used in URLs and logs).
stripe_payment_intent_idVARCHAR(255)FK
Foreign reference to the Stripe PaymentIntent (`pi_...`).
emailVARCHAR(255)
Donor email address, used for receipts and communication.
charity_idVARCHAR(255)FK
Identifier of the target charity receiving this donation.
amount_centsINTEGER
Donation amount in the smallest currency unit (e.g. cents).
statusVARCHAR(32)
High-level state (CREATED, PAYMENT_PENDING, SUCCEEDED, FAILED, UNKNOWN, EXPIRED).
failure_reasonVARCHAR(255)NULL
Optional machine-readable failure reason when the payment does not succeed.
retry_countINTEGER
Number of reconciliation attempts for this intent (used when Stripe returns processing).
next_reconcile_atTIMESTAMPNULL
When the reconciliation worker should re-check this intent (exponential backoff).
last_stripe_statusVARCHAR(255)NULL
Last status returned from Stripe (e.g. processing) for debugging and backoff logic.
created_atTIMESTAMP
When the intent row was first created.
updated_atTIMESTAMP
Last time the intent row was updated.

TABLE
webhook_events
Copy SQL
Stores Stripe webhook deliveries for idempotent processing and auditability.
stripe_event_idVARCHAR(255)PK
Unique Stripe event id, used to deduplicate webhook deliveries.
intent_idUUIDFK
Foreign key back to `donation_intents.intent_id`.
received_atTIMESTAMP
When this webhook was first received by the system.

TABLE
charity_stats
Copy SQL
Aggregated donation statistics per charity for fast reads.
charity_idVARCHAR(255)PK
Identifier of the charity (matches the primary key in the charities table).
total_amount_centsINTEGER
Total donated amount for this charity in cents.
donation_countINTEGER
Number of successful donations recorded for this charity.
updated_atTIMESTAMP
Last time the aggregated stats row was updated.

Direct Charge Without Internal Intent
Rejected
Why:
Hard to reconcile against Stripe without an internal durable anchor
No single place to reason about business-level state
Synchronous Stats Update
Rejected
Why:
Slows down the confirmation endpoint
Couples the hot payment path to aggregation and reporting
No Reconciliation Worker
Rejected
Why:
Webhooks are not guaranteed to be delivered
Timeouts and network partitions are inevitable; you need an explicit repair loop