Module: billing
Version: v0.01
Ownership default: If unclear, billing owns until reassigned.
Provides: Stripe transactions, invoices, and payment reconciliation for the platform.
Includes: charge creation, refunds, webhook updates, invoice generation and PDF download.
Excludes: subscription management, payment method storage, tax calculations, accounting integrations, vendor payouts, non-Stripe payment processors.
¶ 1. Roles and Views
- [MOBILE] KMM Android/iOS app dev
- [FE] Web frontend (React/Tailwind) dev
- [BE-RUST] Axum service dev
- [BE-DB] PostgreSQL/Redis ops
Payment Processing
- Integrates with Stripe API for secure payment flows
- Supports charge creation, refunds, and webhook updates
- Links payments to users, orders, or vendors
Invoicing
- Generates invoices automatically for each completed transaction
- Supports downloadable invoice PDFs for users and admins
- Payment: Create Charge → Webhook Update → Track in Database
- Refund: Admin Initiates → Stripe Refund → Webhook → Database Update
- Invoice: Transaction Complete → Generate Invoice → Store PDF
- Payment UI: Integrate Stripe Elements/SDK for secure card input
- Error handling: Map Stripe error codes to user-friendly messages
- Loading states: Show processing indicators during payment flows
- Receipt display: Show transaction history and downloadable invoices
- Retry logic: Handle temporary payment failures gracefully
- Offline support: Cache transaction status for offline viewing
| Method |
Path |
Purpose |
Auth |
| POST |
/api/billing/charge |
Create a payment charge |
JWT |
| GET |
/api/billing/invoice/:id |
Retrieve invoice details |
JWT |
| POST |
/api/billing/webhook |
Handle Stripe event webhook |
webhook_sig |
{
"error": {
"code": "PAYMENT_FAILED",
"http": 402,
"message": "Your card was declined",
"stripe_code": "card_declined",
"trace_id": "uuid-v4"
}
}
| Key |
Required |
Example |
Notes |
| STRIPE_SECRET_KEY |
yes |
sk_live_... |
Stripe API secret key |
| STRIPE_PUBLISHABLE_KEY |
yes |
pk_live_... |
Frontend Stripe key |
| STRIPE_WEBHOOK_SECRET |
yes |
whsec_... |
Webhook endpoint secret |
| STRIPE_API_VERSION |
yes |
2023-10-16 |
Stripe API version |
| INVOICE_STORAGE_PATH |
yes |
/opt/invoices |
PDF storage directory |
| PAYMENT_TIMEOUT_SECS |
yes |
300 |
Payment intent timeout |
| WEBHOOK_TOLERANCE_SECS |
yes |
300 |
Webhook timestamp tolerance |
- Stripe SDK integration for native payment flows
- Apple Pay/Google Pay support for platform-specific payments
- Secure storage for payment method references (not card data)
- Biometric auth for payment confirmation where supported
- Offline transaction history with sync on reconnect
Acceptance:
- Payment flow completion < 10s
- Apple Pay/Google Pay functional
- Transaction history loads < 2s
- Stripe.js integration for secure tokenization
- Payment form with real-time validation
- Subscription management UI for plan changes
- Transaction dashboard with filtering and search
- Invoice download functionality
- Payment method management for saved cards
Acceptance:
- PCI-DSS compliant (no card data in DOM)
- Lighthouse accessibility ≥ 90
- Payment form validates in real-time
- Axum route handlers for all billing endpoints
- Stripe webhook verification using signature headers
- SeaORM integration for transaction persistence
- PDF generation for invoices using headless browser or library
- Idempotency keys for payment deduplication
- Retry logic for failed webhook processing
Rate limiting:
/api/billing/charge: 10 req/min/user/api/billing/webhook: 1000 req/min (no user limit)
billing_transactions
| Field |
Type |
Description |
| id |
UUID |
Primary key |
| user_id |
UUID |
FK → users.id |
| order_id |
UUID |
FK → orders.id (optional) |
| stripe_id |
String |
Stripe charge ID |
| amount_usd |
Numeric(12,2) |
Payment amount |
| status |
String |
Charge status |
| receipt_url |
String |
Link to Stripe receipt |
| created_at |
DateTimeUtc |
Creation timestamp |
| updated_at |
DateTimeUtc |
Last update timestamp |
billing_events
| Field |
Type |
Description |
| id |
UUID |
Primary key |
| stripe_event_id |
String |
Stripe Event ID |
| event_type |
String |
Webhook event type |
| processed |
bool |
Whether event was processed |
| created_at |
DateTimeUtc |
Event timestamp |
- Rate limiting:
billing_rate:{user_id}:{endpoint} with sliding window
- PCI-DSS compliance: No card data stored locally
- HTTPS required for all payment endpoints
- Webhook signature verification using Stripe-provided secrets
- Idempotency enforcement to prevent duplicate charges
- Admin-only access for refund and sensitive operations
- Audit logging for all financial transactions
- Latency: Payment processing p95 < 2s, invoice generation < 5s
- Availability: 99.95% uptime for payment endpoints
- Scalability: Handle 1000+ concurrent payment requests
- Durability: Zero payment data loss, transaction integrity guaranteed
- Compliance: PCI-DSS Level 1 compliance maintained
- Stripe API client wrapper functions
- Webhook signature verification
- Payment status transitions
- Invoice PDF generation
- End-to-end payment flows with Stripe test mode
- Webhook event processing and retry logic
- Database transaction integrity
- PDF generation and storage
- Apple Pay/Google Pay integration
- Payment method persistence
- Offline transaction history
- Complete payment flow with test cards
- Subscription management workflows
- Invoice download functionality
[MOBILE]
- Native payment flow integration (Stripe SDK)
- Apple Pay/Google Pay implementation
- Transaction history and receipt viewing
[FE]
- Stripe.js payment forms and checkout
- Subscription management dashboard
- Invoice and transaction history UI
[BE-RUST]
- All billing API endpoints with Stripe integration
- Webhook processing with retry logic
- PDF invoice generation service
- Payment reconciliation utilities
[BE-DB]
- Database migrations for all billing tables
- Indexes for transaction queries and reporting
- Redis schema for caching and rate limiting
- All payment flows functional with Stripe test mode
- Webhook processing handles all supported event types
- Invoice generation produces valid PDFs
- Rate limiting prevents payment abuse
- Subscription lifecycle management works end-to-end
- Mobile payments (Apple Pay/Google Pay) functional
- PCI-DSS compliance verified
- Zero financial data loss in failure scenarios
- Breaking API changes require
/api/billing/v2
- Stripe API version updates require full regression testing
- Database schema changes need zero-downtime migration plan
- Deprecation notice ≥ 2 release cycles for client-facing changes
/core - For shared utilities and middleware/auth - For user authentication and JWT validation/profile - For user profile data in invoices/ecommerce - For order integration and product data/storefront - For checkout flow integration/email - For invoice delivery and payment notifications