Stripe Integration Technical Documentation

Architecture Overview

Multi-Market Platform

LocallyGrown.net is a multi-tenant platform where each farmers market operates independently with its own Stripe account.

• Architecture: Each market has separate Stripe API keys (publishable and secret)
• Subdomain Routing: Markets are accessed via subdomains (e.g., market1.locallygrown.net)
• Key Storage: Stripe keys are stored in the MySQL database
• Key Selection: Runtime determination based on subdomain/marketId

Stripe Configuration per Market

Each market has Stripe configuration stored securely:

• Publishable Key - Client-side API key for secure tokenization
• Secret Key - Server-side API key (encrypted at rest)
• Approval Status - Whether market is approved for payment processing
• Prepayment Fee - Optional fee percentage for prepayments
• Prepayment Fee Label - Customer-facing fee description

Stripe Client Initialization

Server-Side Initialization

The server-side Stripe client is initialized through a secure service layer that manages API key retrieval and client instantiation.

1. API Key Retrieval

The system retrieves market-specific Stripe API keys from secure storage:

• Development environments can use override configuration for testing
• Production environments retrieve keys from encrypted database storage
• System throws errors if market configuration is missing or invalid

2. Client Creation

Stripe client initialization includes multiple safety mechanisms:

• Payment processing is disabled by default in non-production environments
• Explicit configuration flag required to enable live charges
• Prevents accidental charges during development and testing
• Uses current Stripe API version for compatibility

Client-Side Initialization

Cards are collected using Stripe Elements, a PCI-compliant client-side SDK that handles sensitive card data entirely within Stripe's infrastructure.

Integration Approach:

• Stripe.js library loaded dynamically from official CDN
• Initialized with market-specific publishable key
• Elements created for secure card input collection
• Card data never touches LocallyGrown servers

API Endpoints and Flows

1. SetupIntent Creation (Card Saving Initiation)

Flow:

1. Authenticates user session
2. Applies rate limiting to prevent abuse
3. Verifies payment processing is enabled
4. Creates Stripe SetupIntent via service layer
5. Returns secure client token for card collection

Response Format:

Returns JSON with success status, client secret token, and configuration flags

2. Setup Intent Processing (Server-Side)

The server-side service layer handles SetupIntent creation through the Stripe API.

Implementation Details:

• Creates SetupIntent associated with customer account
• Configured for off-session (future) payment use
• Accepts all major card brands (credit, debit, prepaid)
• Includes market and transaction metadata for tracking

3. Payment Method Attachment

Flow:

1. Authenticates user session
2. Applies rate limiting for card management operations
3. Validates payment method token format
4. Processes card attachment through service layer
5. Returns card display details (brand, last 4 digits)

Service Implementation

The payment service handles the secure attachment of payment methods to customer accounts.

Processing Steps:

1. Token Validation: Verifies payment method token has correct format before processing
2. Existing Customer Handling:
   • Retrieves customer record from Stripe
   • Attaches new payment method
   • Sets as default for future charges
   • Removes outdated payment methods
3. New Customer Creation:
   • Creates Stripe customer with user email
   • Attaches payment method
   • Configures as default
4. Record Update: Updates user record with customer ID and card display information

4. Payment Intent Creation (Charging Cards)

A. Single Order Payment

The payment service processes individual order payments through Stripe's PaymentIntent API with full off-session charge support.

Key Parameters:

• Market-specific configuration
• Customer ID from previous card setup
• Calculated amount in cents
• Descriptive payment label
• Transaction metadata for tracking

B. Grouped Order Payment (Multiple Orders, Single Charge)

For efficiency, the system can combine multiple orders into a single charge using idempotency keys and distributed locking.

Implementation Features:

• Unique idempotency key prevents duplicate charges
• Distributed lock prevents concurrent processing
• Metadata tracks all included order IDs
• Single customer charge for multiple orders

5. Core Payment Intent Function

The core payment processing function implements several critical safety features to ensure payment integrity.

Key Features:

Stripe API Endpoints Used:

• customers.retrieve - Get customer data
• paymentMethods.retrieve - Get payment method details
• paymentMethods.list - List customer's cards
• paymentMethods.detach - Remove old cards
• paymentIntents.create - Create and confirm charge

Card Saving Locations

There are two distinct UI locations where users can save cards:

Common Patterns Across All Locations

Flow:

1. Create SetupIntent server-side → get clientSecret
2. Load Stripe.js from CDN
3. Initialize Stripe with stripePubKey
4. Create Elements with clientSecret
5. Mount individual card field elements
6. User enters card data (stays in Stripe iframe)
7. Call stripe.confirmCardSetup()
8. Receive paymentMethodId
9. Send paymentMethodId to /api/user/save-card
10. Server attaches to customer and updates database

Payment Processing

When Charges Occur

Why After Pickup?

Orders are charged after pickup to allow for final adjustments based on what the customer actually receives:

• Growers may be out of some items
• Quantities might change (3 tomatoes available instead of 5)
• Customers may add items from an "extras table" at pickup
• Out-of-stock items can be removed before charging

Flow:

1. Customer Places Order
   • Order created with paymentMethod: 'Pending Stripe'
   • No charge occurs
   • applyPrepayment: 1 flag set if payment should be processed
2. Grower Packs Order
   • Grower marks items as packed
   • May adjust quantities (missing/undelivered items)
3. Background Worker Processes Payments
   • Automated system detects packed orders flagged for payment
   • Processes individual or grouped order payments through payment service
4. Charge Calculation
   • Spot Price: Actual cost based on packed quantities
   • Prepayment Fee: Percentage fee if configured (default 0%)
   • Total: spotPrice + (spotPrice * prepaymentFeePercent / 100)
   Example:

   • Order total: $50.00
   • Prepayment fee: 3%
   • Fee amount: $1.50
   • Total charged: $51.50
5. Stripe Charge
   • Creates PaymentIntent with off_session: true, confirm: true
   • Uses customer's default payment method
   • Includes metadata (orderId, userId)
6. Post-Charge Actions
   • Records prepayment in prepayments table
   • Updates order: paid: 1, prepaymentProcessed: 1, paymentMethod: 'Stripe'
   • Queues payment confirmation email
   • Clears applyPrepayment flag

Minimum Charge Amount

Refund Processing

The system supports two refund methods: account credits (automated) and Stripe card refunds (manual).

Account Credits (Automated):

• Processed through OrderService.processRefunds()
• Credits customer's account balance instantly
• Tracks refund amounts in order item records
• Balance can be used for future orders

Stripe Card Refunds (Manual):

• Must be processed manually via Stripe dashboard
• Market managers initiate refunds directly in Stripe
• Returns money to customer's original card (2-10 business days)
• PaymentService.processRefund() exists but is not currently integrated into workflows

Webhook Integration

Security

Webhook security is implemented using Stripe's signature verification mechanism to ensure authenticity.

Verification Process:

• Validates Stripe signature header is present
• Verifies market context through request headers
• Uses webhook secret for signature validation
• Constructs verified event object from payload

Requirements:

• Valid Stripe signature header
• Market identification
• Active Stripe configuration

Webhook Events Handled

Rate Limiting

Webhook endpoint implements rate limiting to prevent flooding attacks and abuse.

Security Implementation

PCI Compliance

Approach: Stripe Elements (SAQ-A compliance)

Authentication & Authorization

Rate Limiting

Comprehensive rate limiting is applied across all payment-related operations to prevent abuse and ensure system stability.

Protected Operations:

1. Setup Intent Creation: Prevents repeated card save attempts
2. Card Management: Limits add/remove card operations
3. Webhook Processing: Prevents webhook flooding

Card Sync Verification

Purpose: Ensures displayed card information matches the card that will be charged

Verification Process:

1. Before charging, system verifies stored card data matches Stripe's records
2. Queries Stripe for customer's current default payment method
3. Compares local card information with Stripe data
4. If mismatch detected:
   • Attempts automatic synchronization
   • Updates local records with current Stripe data
   • Throws error if synchronization fails

Protection: Prevents charging wrong card after data inconsistencies or race conditions

Environment-Based Safety

Simulation Mode Features:

• Logs payment intents for debugging
• Returns mock transaction IDs
• Updates database records for testing
• Uses test card data

Database Schema

The database schema supports multi-market Stripe integration with secure storage of payment-related information.

User Payment Data

User records store minimal payment information required for processing:

• Stripe Customer Identifier - Links user to Stripe customer account
• Card Display Information - Card brand and last 4 digits for user interface

Market Payment Configuration

Market records store Stripe configuration and settings:

• Publishable Key - Client-side API key (public)
• Secret Key - Server-side API key (encrypted at rest)
• Prepayment Fee - Optional percentage fee configuration
• Fee Display Label - Customer-facing fee description
• Approval Status - Enables/disables payment processing

Order Payment Tracking

Order records track payment status and processing state:

• Payment Trigger Flag - Indicates payment should be processed
• Processing Status - Whether payment completed successfully
• Transaction Reference - Links to payment transaction record
• Error Information - Stores failure details for troubleshooting
• Payment Method Status - Tracks payment state transitions

Payment Transaction Records

Payment transactions are tracked with comprehensive information:

• Amount - Stored in cents (Stripe standard)
• Currency - Payment currency (default: USD)
• Vendor Transaction ID - Stripe PaymentIntent ID for reconciliation
• Payment Method Type - Identifies payment processor
• Card Display Information - Brand and last 4 digits for receipts
• Status Tracking - Paid, refunded, rejected flags
• Refund Information - Refund amount and status
• Audit Trail - Creation and modification timestamps

Error Handling and Retry Logic

Payment Intent Error Handling

The payment service implements comprehensive error handling to gracefully manage various failure scenarios.

Validation Errors

Stripe API Errors

Retry Logic

Idempotency Keys

Grouped payments use unique idempotency keys to prevent duplicate charges on retry.

Purpose:

• Prevents duplicate charges if request retries
• Stripe recognizes duplicate requests by key
• Returns original result for retries within 24 hours

Distributed Locks

Payment processing implements distributed locking to prevent race conditions:

• Prevents concurrent payment processing for same user
• Lock timeout ensures eventual recovery from failures
• Ensures only one payment process at a time per user

Double-Charge Prevention

Order Status Filtering

System filters orders by payment status to prevent reprocessing:

• Only processes orders in pending payment state
• Status transitions are atomic with payment

Status Transition

• Successful payment triggers status change
• Prevents reprocessing if worker runs again
• Status change synchronized with payment confirmation

Testing and Simulation Mode

Simulation Mode

The system supports development and testing through a simulation mode that allows full integration testing without live payment processing.

Simulation Features:

Test Environment

The system includes comprehensive automated testing infrastructure for payment operations.

Test Database:

• Isolated test database separate from development and production
• Transaction-based test isolation with automatic rollback
• Real database operations ensuring production-like behavior

Test Coverage:

• Unit tests for payment service logic
• Integration tests for complete payment flows
• Race condition prevention tests
• Data validation and error handling tests
• Multi-order grouped payment tests

Test Organization:

Tests are organized into focused suites covering payment creation, grouped payments, validation logic, and concurrency scenarios.

System Architecture Overview