79ab9a3efa
1 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
Adrian Flores Cortes
|
3d8bf17b72 |
docs(payments): Add Developer Guidelines (ST4.2.5)
Comprehensive developer guidelines for payment system development. New Files: - docs/.../OQI-005-payments-stripe/DEVELOPER-GUIDELINES.md (900+ lines) - Complete reference for payment development - PCI-DSS compliance rules (DO's and DON'Ts) - Backend development guidelines - Frontend development guidelines - Testing guidelines (unit + E2E) - Common pitfalls and how to avoid them - Code review checklist - Deployment checklist - Troubleshooting guide - Examples and templates Sections: 1. Overview - Architecture summary, tech stack, compliance level 2. PCI-DSS Compliance Rules - What's allowed vs prohibited 3. Backend Development - File structure, endpoints, webhooks, database 4. Frontend Development - Stripe Elements, checkout flow, error handling 5. Testing Guidelines - Unit tests, E2E tests, component tests 6. Common Pitfalls - 5 common mistakes and how to avoid them 7. Code Review Checklist - Security, quality, Stripe integration 8. Deployment Checklist - Environment, security, testing, monitoring 9. Troubleshooting - Common issues and solutions 10. Examples & Templates - Complete flow examples Key Guidelines: ✅ DO's: - Use Payment Intents (server-side processing) - Use Stripe Elements (client-side tokenization) - Verify webhook signatures - Store only tokens/IDs (pm_xxx, pi_xxx) - Use HTTPS everywhere - Log payment events (without sensitive data) - Write E2E tests for PCI-DSS compliance ❌ DON'Ts: - Accept card data in backend - Store PAN, CVV, or expiry in database - Create native card inputs - Store card data in React state - Skip webhook signature verification - Use HTTP (only HTTPS) - Log sensitive data PCI-DSS Compliance: ✅ ALLOWED: - Store last 4 digits - Store card brand - Store Stripe tokens (pm_xxx, pi_xxx, cus_xxx) - Store customer name ❌ PROHIBITED: - Store full PAN (card number) - Store CVV/CVC - Store expiry date - Store PIN Common Pitfalls: 1. Accepting card data in backend → Block sensitive fields 2. Storing full PAN in database → Use tokens only 3. Native card inputs → Use Stripe CardElement 4. Not verifying webhook signatures → Use constructEvent 5. Logging sensitive data → Filter sensitive fields Code Examples: - Wallet deposit flow (complete end-to-end) - Subscription checkout (Stripe hosted) - Payment Intent creation (backend) - Stripe Elements integration (frontend) - Webhook signature verification - Database schema (safe vs prohibited) Testing Examples: - Unit tests (Stripe service mocked) - E2E tests (PCI-DSS compliance) - Component tests (CardElement rendering) - Integration tests (webhook handling) Deployment Checklist: - Environment variables configured - Stripe webhooks set up - SSL/TLS enabled - Security headers configured - Rate limiting enabled - All tests passing (45+ PCI-DSS tests) - Monitoring and alerts configured Target Audience: - Backend developers (Express.js, TypeScript) - Frontend developers (React, Stripe.js) - DevOps engineers (deployment, monitoring) - Code reviewers (security validation) - New team members (onboarding) Status: BLOCKER-002 (ST4.2) - Developer guidelines complete Task: #5 ST4.2.5 - Actualizar developer guidelines pagos Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> |