Payment Integration

Purpose

When to Use

• Integrating Stripe, PayPal, or other payment gateways
• Implementing checkout and payment flows
• Building subscription billing systems
• Ensuring PCI-DSS compliance
• Handling payment webhooks
• Implementing payment retry logic
• Setting up multi-currency payments
• Building invoicing systems

Quick Start

• Integrating payment gateways (Stripe, PayPal, Adyen)
• Building checkout or subscription flows
• Designing PCI-compliant payment systems
• Implementing webhook handlers for payments
• Setting up recurring billing

• General ledger/accounting systems → use

  /fintech-engineer

• API design without payment focus → use

  /api-designer

• Frontend checkout UI only → use

  /frontend-design

• Security audit → use

  /security-auditor

Decision Framework

Payment Use Case?
├── One-time Purchase
│   └── Stripe Checkout / PayPal Buttons
├── Subscription
│   └── Stripe Billing / Recurly
├── Marketplace/Split Payments
│   └── Stripe Connect / PayPal Commerce
├── Enterprise/B2B
│   └── Invoicing with NET terms
└── Global Payments
    └── Adyen / Multi-gateway strategy

Core Workflows

1. Stripe Integration

1. Set up Stripe account and API keys
2. Create products and prices
3. Implement Checkout Session or Elements
4. Handle payment confirmation
5. Set up webhook endpoint
6. Process webhook events (succeeded, failed)

2. Subscription Billing

1. Define subscription plans and pricing
2. Create customer in payment provider
3. Implement subscription creation flow
4. Handle trial periods
5. Manage upgrades/downgrades
6. Implement dunning for failed payments

3. Webhook Handling

1. Create secure webhook endpoint
2. Verify webhook signatures
3. Make handlers idempotent
4. Process events in order
5. Handle retry scenarios
6. Log all webhook events

Best Practices

• Never store full card numbers—use tokenization
• Always verify webhook signatures
• Implement idempotency for payment operations
• Use test mode thoroughly before production
• Handle all payment states (pending, succeeded, failed)
• Store payment provider IDs for reconciliation

Anti-Patterns