Skip to main content

Stripe + Donation Platform Overview

Introduction​

The Reports application includes a comprehensive donation platform that enables Aleteia to accept both one-time and recurring donations from supporters worldwide. The platform is built on top of Stripe's payment infrastructure and supports multiple payment methods, currencies, and donation campaigns.

Key Features​

Payment Methods​

  • Credit/Debit Cards: Via Stripe Payment Elements (supports 3D Secure authentication)
  • SEPA Direct Debit: For European bank transfers (EUR only)
  • Przelewy24 (P24): Polish payment method (when enabled via feature flag)
  • PayPal: Alternative payment processor (legacy integration)

Donation Types​

  • Single Donations: One-time payments of any amount ≥ €1.00
  • Recurring Donations: Monthly subscriptions with automatic billing

Multi-Currency Support​

  • Default Currencies: EUR, USD
  • Optional Currencies (via feature flags): BRL, PLN, MXN, COP, ARS
  • Automatic currency conversion for reporting (all amounts normalized to EUR)

Campaign Tracking​

  • Donations can be associated with specific campaigns (e.g., "Spring2018")
  • Campaign metadata tracked in Stripe for reporting and analytics
  • Each campaign has a target amount and tracks progress

Architecture Components​

Backend (Ruby on Rails)​

Models​

  • Donations::Request: Represents a donation request with validation and Stripe API interaction
  • Donations::Donor: User who makes donations, linked to Stripe Customer
  • Donations::Transaction: Completed payment record
  • Donations::Notification: Webhook event log from Stripe/PayPal
  • Donations::Subscription: Recurring donation subscription record
  • Donations::Campaign: Campaign definition with target amounts

Controllers​

  • Donations::StripeController: Handles Stripe API interactions
    • Payment Intent creation
    • Checkout Session creation
    • Webhook event processing
    • Subscription management

Background Jobs (Sidekiq)​

  • ProcessStripeEventJob: Processes incoming webhook events
  • ProcessStripeTokenJob: Handles legacy token-based charges
  • ExpirePaymentIntentJob: Cancels abandoned payment intents after 30 minutes
  • CancelStripeSubscriptionJob: Cancels subscriptions in Stripe
  • AssociateTransactionWithCampaignJob: Links transactions to campaigns
  • UpdateDonorLocaleJob: Updates customer locale preferences

Frontend (React + TypeScript)​

Main Components​

  • DonationsApp: Root component managing the entire donation flow
  • DonationsForm: Form handling user input (email, amount, currency)
  • AmountSelector: UI for selecting donation amounts
  • PaymentMethodSelector: Switch between card, SEPA, P24
  • Payment Button Components:
    • CardPaymentButton: Credit/debit card payments
    • SepaButton: SEPA Direct Debit payments
    • PaypalButton: PayPal integration

State Management​

  • Redux Toolkit for global state
  • Redux Thunk for async operations
  • Integration with Google Tag Manager for analytics

Payment Flow Overview​

Single Donation Flow​

  1. User enters email and selects amount/currency
  2. User clicks payment button (card/SEPA/P24)
  3. Frontend creates Payment Intent via API
  4. User completes payment authentication (3D Secure if required)
  5. Stripe confirms payment and sends webhook
  6. Backend processes charge.succeeded event
  7. Transaction record created, thank you email sent

Recurring Donation Flow​

  1. User enters email and selects monthly amount
  2. User chooses payment method
  3. For cards: Setup Intent created, user confirms
  4. For SEPA: Setup Intent + payment method confirmation
  5. Backend creates Subscription in Stripe
  6. Stripe sends customer.subscription.created webhook
  7. Subscription record created in database
  8. Monthly charges processed automatically by Stripe
  9. Each charge triggers charge.succeeded webhook

Security Features​

Payment Security​

  • 3D Secure (SCA) authentication for European cards
  • PCI compliance via Stripe hosted elements
  • No card data touches application servers
  • Idempotency keys prevent duplicate charges

Fraud Prevention​

  • reCAPTCHA v3 integration (feature flag controlled)
  • Failed payment attempt tracking (max 3 attempts per intent)
  • Automatic payment intent cancellation on fraud detection
  • Staff notifications for suspicious activity

Webhook Security​

  • Stripe signature verification
  • HTTP Basic authentication for webhook endpoint
  • Event replay prevention via unique event IDs

Email Notifications​

Donor Emails​

  • Thank You Email: Sent after successful donation
  • Charge Failed Email: Sent when payment fails
  • Subscription Canceled Email: Sent when recurring donation is canceled

Staff Emails​

  • Charge Failed Notification: Alerts staff to payment issues
  • Fraud Alert: High-priority notification for suspicious activity

All emails are localized based on donor's preferred language.

Reporting & Analytics​

Transaction Reports​

  • Daily/monthly/yearly transaction summaries
  • Grand totals by currency with automatic conversion
  • Campaign-specific revenue tracking
  • Abandoned session tracking

Real-Time Features​

  • Live donation wall showing recent donations
  • Slack notifications for new donations (configurable)
  • Google Tag Manager integration for web analytics

Configuration​

Required Secrets​

  • STRIPE_PUBLISHABLE_KEY: Public API key
  • STRIPE_SECRET_KEY: Secret API key
  • STRIPE_SIGNING_SECRET_V2: Webhook signature verification key
  • STRIPE_WEBHOOK_SECRET_V2: HTTP Basic auth password for webhook endpoint

Settings (via Setting model)​

  • donations_success_redirect_url: Where to redirect after successful payment
  • donations_failure_redirect_url: Where to redirect after failed payment
  • donations_slack_webhook_url: Slack integration URL
  • target_amount: Global donation target
  • recaptcha_minimum_score: Minimum score for reCAPTCHA validation

Feature Flags (Flipper)​

  • RECAPTCHA: Enable reCAPTCHA protection
  • SEPA: Enable SEPA Direct Debit
  • P24: Enable Przelewy24 payment method
  • CURRENCY_ENABLED: Enable specific optional currencies
  • CHARGE_FAILED_NOTIFICATIONS: Enable staff email alerts
  • PROFILE_LINK_IFRAME: Use iframe for donor profile links

Supported Locales​

The donation platform supports multiple languages:

  • Arabic (ar) - maps to Stripe default
  • Spanish (es)
  • English (en)
  • French (fr)
  • Italian (it)
  • Portuguese (pt)
  • Polish (pl)
  • Slovenian (si) - maps to Stripe default

All UI text, emails, and Stripe checkout sessions are localized.

Monitoring & Logging​

Logging​

  • Structured logging via SemanticLogger
  • All Stripe API calls logged with request/response details
  • Webhook events logged with full payload
  • Failed payment attempts tracked with error codes

Error Tracking​

  • Rollbar integration for exception tracking
  • Stripe error codes captured and logged
  • Staff notifications for critical errors

Metrics​

  • Stripe event processing metrics
  • Payment success/failure rates
  • Webhook processing latency
  • Currency conversion rates tracking