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>
3d8bf17b72