Skip to main content

Stripe + Donation Platform Documentation

This folder contains comprehensive documentation for the Stripe integration and donation platform used by Aleteia.

Documentation Structure​

1. Overview​

Introduction to the donation platform, key features, architecture components, payment flows, and configuration.

Topics covered:

  • Payment methods (Card, SEPA, P24, PayPal)
  • Donation types (single, recurring)
  • Multi-currency support
  • Campaign tracking
  • Security features
  • Email notifications
  • Reporting & analytics

2. User Flows​

Step-by-step user experience documentation for different donation scenarios.

Flows documented:

  • Single card donation with Payment Intent
  • Recurring donation with Setup Intent and Subscription
  • SEPA Direct Debit flow
  • Przelewy24 (P24) payment flow
  • Failed payment handling
  • Subscription cancellation
  • Error scenarios and recovery

3. Technical Integration​

Detailed technical information about the Stripe API integration.

Topics covered:

  • Stripe API objects (Customer, PaymentIntent, SetupIntent, Plan, Subscription, etc.)
  • API endpoints and request/response formats
  • Payment Intent vs Setup Intent
  • Request validation and error handling
  • Currency handling and conversion
  • Payment Intent expiration logic
  • Security features (idempotency, rate limiting, reCAPTCHA)
  • Frontend integration examples

4. Webhooks​

Complete guide to Stripe webhook event processing.

Topics covered:

  • Webhook endpoint configuration and security
  • Events processed: charge.succeeded, charge.failed, customer.subscription.created, customer.subscription.deleted, payment_intent.created
  • Event processing flow (controller → background job → database)
  • Notification storage and audit trail
  • Error handling and retry logic
  • Webhook testing (local development and test suite)
  • Event data structures
  • Monitoring and troubleshooting

5. Email Notifications​

Documentation for all automated email communications.

Emails documented:

  • Donor emails:
    • Thank you email (after successful donation)
    • Charge failed email (recurring payment failure)
    • Subscription canceled email
  • Staff emails:
    • Charge failed staff notification
    • Fraud alert notification (high priority)
  • Email infrastructure (SendGrid, localization, templates)
  • Subscription management links with authentication tokens
  • Email testing and monitoring

6. Admin Features​

Administrative tools for managing donations and viewing reports.

Topics covered:

  • Avo admin interface (Donors, Transactions, Subscriptions, Notifications, Campaigns)
  • Transaction reports and statistics
  • API endpoints for reports and campaign data
  • Donation wall (recent donations display)
  • Background jobs for reporting
  • Slack notifications
  • Data export (CSV, JSON)
  • Monitoring metrics and dashboards

7. Error Handling​

Comprehensive error scenarios, logging, monitoring, and recovery procedures.

Topics covered:

  • Error categories (user input, payment, webhook, fraud, subscription, database, configuration)
  • Logging strategy (log levels, structured logging, sensitive data filtering)
  • Error tracking with Rollbar
  • Monitoring and metrics (APM, custom metrics, health checks, uptime monitoring)
  • Recovery procedures (replaying webhooks, fixing inconsistent data, handling failed jobs)
  • Alerting strategy (critical, high, medium, low priority)
  • Troubleshooting guide

Testing​

Stripe Test Cards​

Use these test cards for development and staging:

Successful Payments:

  • Visa: 4242 4242 4242 4242
  • Mastercard: 5555 5555 5555 4444
  • Amex: 3782 822463 10005

3D Secure Authentication:

  • Requires Auth: 4000 0027 6000 3184

Failed Payments:

  • Card Declined: 4000 0000 0000 0002
  • Insufficient Funds: 4000 0000 0000 9995

SEPA Test IBANs:

  • Successful: DE89370400440532013000
  • Failed: DE62370400440532013001

All test cards require:

  • Any future expiry date (e.g., 12/34)
  • Any 3-digit CVC (e.g., 123)
  • Any billing postal code (e.g., 12345)

Key Concepts​

Payment Flow Types​

Payment Intent Flow (Single Donations)

  1. User enters details
  2. Frontend creates Payment Intent
  3. User confirms payment with Stripe Elements
  4. Backend receives charge.succeeded webhook
  5. Transaction recorded, email sent

Setup Intent + Subscription Flow (Recurring Donations)

  1. User enters details, selects monthly
  2. Frontend creates Setup Intent
  3. User confirms payment method
  4. Frontend creates Subscription with payment method
  5. Backend receives customer.subscription.created and charge.succeeded webhooks
  6. Subscription and transaction recorded

Metadata Structure​

All Stripe objects include metadata for tracking:

{
  "locale": "it",
  "campaign": "Spring2018",
  "campaign_id": 123,
  "recaptcha_score": 0.9,
  "user_ip": "192.168.1.1",
  "user_city": "Rome",
  "user_country": "IT",
  "user_location": "41.9028,12.4964"
}

Security Layers​

  1. reCAPTCHA v3 - Bot protection (feature flag controlled)
  2. Stripe Signature Verification - Webhook authenticity
  3. HTTP Basic Auth - Additional webhook security
  4. Idempotency Keys - Prevent duplicate charges
  5. Rate Limiting - Fraud detection (max 3 failures per intent)
  6. Payment Intent Expiration - Auto-cancel after 30 minutes