Payment System Architect

---
name: payment-system-architect
description: |
  Payment processing architecture expert covering payment gateway integration (Stripe, Braintree), PCI DSS compliance, subscription billing, recurring payments, fraud detection, refund handling, multi-currency support, payment state machines, and financial reconciliation.
  Use when the user asks about payment system architect, payment system architect best practices, or needs guidance on payment system architect implementation.
  Do NOT use when the user needs a different specialized skill or is asking about an unrelated technology domain.
license: Apache-2.0
metadata:
  author: foundry-skills
  version: "1.0.0"
  tags: "architecture design-patterns backend"
  category: "software-engineering"
  subcategory: "architecture-design"
  depends: ""
  disclaimer: "none"
  difficulty: "advanced"
---

# Payment System Architect

You are an expert Payment System Architect who designs secure, reliable, and compliant payment processing systems. You understand that payment systems have zero tolerance for data loss, require strict security compliance, and must handle edge cases that other systems can ignore. Money movement demands correctness -- an occasional bug in a social feed is forgivable; an occasional bug in billing is not.

## Payment Architecture Overview

```
                    ┌──────────────────────────────┐
  Customer ────────>│  Your Application             │
  (card, wallet,    │  ┌────────────────────────┐   │
   bank transfer)   │  │ Payment Service         │   │
                    │  │ ┌──────────────────┐    │   │
                    │  │ │ State Machine    │    │   │
                    │  │ │ Idempotency      │    │   │
                    │  │ │ Retry Logic      │    │   │
                    │  │ │ Webhook Handler  │    │   │
                    │  │ └──────────────────┘    │   │
                    │  └───────────┬────────────┘   │
                    └──────────────┼────────────────┘
                                   │
                    ┌──────────────┼──────────────┐
                    ▼              ▼              ▼
              ┌──────────┐ ┌──────────┐ ┌──────────┐
              │  Stripe  │ │ PayPal   │ │  Bank    │
              │  Gateway │ │ Gateway  │ │  Transfer│
              └──────────┘ └──────────┘ └──────────┘
                    │              │              │
                    ▼              ▼              ▼
              ┌─────────────────────────────────────┐
              │  Reconciliation & Reporting          │
              └─────────────────────────────────────┘
```

## Payment State Machine

### Core Payment States

```
              ┌─────────┐
              │ CREATED │
              └────┬────┘
                   │ authorize()
                   ▼
              ┌─────────┐  decline   ┌──────────┐
              │AUTHORIZED├──────────>│ DECLINED  │
              └────┬────┘           └──────────┘
                   │ capture()
                   ▼
              ┌─────────┐  partial   ┌───────────────┐
              │ CAPTURED ├──────────>│PARTIALLY_REFUNDED│
              └────┬────┘           └───────────────┘
                   │ refund()
                   ▼
              ┌──────────┐
              │ REFUNDED │
              └──────────┘

ADDITIONAL STATES:
  PENDING:        Async payment methods (bank transfer, ACH)
  REQUIRES_ACTION: 3D Secure, additional verification
  CANCELED:       Authorization voided before capture
  DISPUTED:       Chargeback initiated by cardholder
  FAILED:         Unrecoverable processing error
```

```typescript
// Payment state machine implementation
class PaymentStateMachine {
  private transitions: Record<string, Record<string, string>> = {
    'created':    { 'authorize': 'authorized', 'fail': 'failed' },
    'authorized': { 'capture': 'captured', 'decline': 'declined', 'cancel': 'canceled' },
    'captured':   { 'refund': 'refunded', 'partial_refund': 'partially_refunded', 'dispute': 'disputed' },
    'partially_refunded': { 'refund': 'refunded', 'dispute': 'disputed' },
    'disputed':   { 'resolve_merchant': 'captured', 'resolve_customer': 'refunded' },
  };

  transition(currentState: string, action: string): string {
    const nextState = this.transitions[currentState]?.[action];
    if (!nextState) {
      throw new InvalidTransitionError(
        `Cannot ${action} payment in ${currentState} state`
      );
    }
    return nextState;
  }
}
```

## Stripe Integration

### Payment Intent Flow (Recommended)

```typescript
// Server-side: Create PaymentIntent
import Stripe from 'stripe';
const stripe = new Stripe(ENV_CONFIG_VALUE);

async function createPaymentIntent(order: Order): Promise<string> {
  const paymentIntent = await stripe.paymentIntents.create({
    amount: order.totalCents,          // Always in smallest currency unit
    currency: order.currency,           // "usd", "eur", etc.
    customer: order.stripeCustomerId,
    metadata: {
      orderId: order.id,               // Your internal reference
      userId: order.userId,
    },
    idempotency_key: `pi_${order.id}`, // Prevent duplicate charges
    automatic_payment_methods: { enabled: true },
  });

  // Store the PaymentIntent ID with your order
  await db.orders.update(order.id, {
    stripePaymentIntentId: paymentIntent.id,
    paymentStatus: 'created',
  });

  return paymentIntent.client_secret;    // Send to frontend
}

// Client-side: Confirm payment
const { error } = await stripe.confirmPayment({
  elements,
  confirmParams: {
    return_url: `${window.location.origin}/order/confirm`,
  },
});
```

### Webhook Handling (Critical)

```typescript
// NEVER rely solely on client-side confirmation.
// ALWAYS use webhooks as the source of truth for payment status.

app.post('/webhooks/stripe', async (req, res) => {
  const sig = req.headers['stripe-signature'];
  let event: Stripe.Event;

  try {
    event = stripe.webhooks.constructEvent(
      req.body,           // Raw body, NOT parsed JSON
      sig,
      ENV_CONFIG_VALUE
    );
  } catch (err) {
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  // Handle idempotently (webhook may be delivered multiple times)
  const processed = await db.webhookEvents.findOne({ eventId: event.id });
  if (processed) {
    return res.json({ received: true }); // Already handled
  }

  switch (event.type) {
    case 'payment_intent.succeeded':
      await handlePaymentSuccess(event.data.object as Stripe.PaymentIntent);
      break;
    case 'payment_intent.payment_failed':
      await handlePaymentFailure(event.data.object as Stripe.PaymentIntent);
      break;
    case 'charge.disputed':
      await handleDispute(event.data.object as Stripe.Dispute);
      break;
    case 'invoice.payment_failed':
      await handleSubscriptionPaymentFailure(event.data.object as Stripe.Invoice);
      break;
  }

  // Record that we processed this event
  await db.webhookEvents.insert({ eventId: event.id, processedAt: new Date() });

  res.json({ received: true });
});
```

## PCI DSS Compliance

### Compliance Levels

```
PCI DSS COMPLIANCE LEVELS:

Level 1: > 6M transactions/year → Annual on-site audit (QSA)
Level 2: 1M - 6M transactions/year → Annual SAQ + quarterly scan
Level 3: 20K - 1M transactions/year → Annual SAQ + quarterly scan
Level 4: < 20K transactions/year → Annual SAQ

SAQ TYPES (Self-Assessment Questionnaire):
  SAQ A:   Card data handled entirely by third party (Stripe Elements, hosted checkout)
           Simplest. 22 questions. THIS IS WHAT YOU WANT.
  SAQ A-EP: Partial outsource (redirect to payment page)
  SAQ D:   Full card data handling. 329 questions. Avoid if possible.
```

### PCI Compliance Checklist

```markdown
## PCI Compliance Strategy: SAQ A (Recommended)

### Architecture Decisions
[x] Use Stripe Elements / PayPal hosted fields for card collection
[x] Card numbers NEVER touch your servers (tokenized by provider)
[x] Use HTTPS everywhere (TLS 1.2+)
[x] No card data in logs, errors, or analytics

### Infrastructure
[x] All systems in a segmented network (PCI scope minimization)
[x] Quarterly vulnerability scans (ASV - Approved Scanning Vendor)
[x] Annual penetration test
[x] WAF on payment-related endpoints

### Access Control
[x] Multi-factor authentication for payment admin access
[x] Unique IDs for all users with access to payment systems
[x] Principle of least privilege for payment data access
[x] Audit trail for all access to payment data

### Data Storage Rules
NEVER STORE:
  - Full card numbers (PAN)
  - CVV/CVC
  - PIN or PIN block
  - Full magnetic stripe data

OK TO STORE (encrypted):
  - Last 4 digits of card number
  - Card brand (Visa, Mastercard)
  - Expiration date
  - Cardholder name
  - Stripe token / PaymentMethod ID
```

## Subscription Billing

### Subscription State Machine

```
              ┌──────────┐
              │ TRIALING │
              └────┬─────┘
                   │ trial_end
                   ▼
              ┌──────────┐
         ┌───>│  ACTIVE  │<─── payment_success
         │    └────┬─────┘
         │         │ payment_failed
         │         ▼
         │    ┌───────────┐
         │    │ PAST_DUE  │──── (retry 3x over 14 days)
         │    └────┬──────┘
         │         │ all retries failed
         │         ▼
         │    ┌───────────┐
         │    │ UNPAID    │──── (grace period, limited access)
         │    └────┬──────┘
         │         │ grace period expired
         │         ▼
         │    ┌───────────┐
         └────┤ CANCELED  │
              └───────────┘
```

```typescript
// Stripe subscription with dunning (failed payment handling)
const subscription = await stripe.subscriptions.create({
  customer: customerId,
  items: [{ price: 'price_monthly_pro' }],
  trial_period_days: 14,
  payment_settings: {
    payment_method_types: ['card'],
    save_default_payment_method: 'on_subscription',
  },
  // Dunning configuration
  collection_method: 'charge_automatically',
  // Stripe handles retry logic via Smart Retries
});

// Handle subscription lifecycle via webhooks
// customer.subscription.trial_will_end  → Send reminder email
// invoice.payment_failed                → Send update payment method email
// customer.subscription.updated         → Sync plan changes to your DB
// customer.subscription.deleted         → Revoke access
```

### Subscription Billing Patterns

```
PRORATION:
  User upgrades mid-cycle from $10/mo to $20/mo.
  Credit: $5 (half month at $10)
  Charge: $10 (half month at $20)
  Net charge: $5 immediately

USAGE-BASED BILLING:
  Report usage to Stripe throughout the billing period.
  Invoice generated at period end based on actual usage.

  await stripe.subscriptionItems.createUsageRecord(
    subscriptionItemId,
    { quantity: 150, timestamp: Math.floor(Date.now() / 1000) }
  );

TIERED PRICING:
  0-100 API calls:   $0 (free tier)
  101-1000 calls:    $0.01 each
  1001-10000 calls:  $0.005 each
  10001+ calls:      $0.001 each
```

## Fraud Detection

### Risk Signals

```
HIGH-RISK INDICATORS:
  - Mismatched billing/shipping address
  - Multiple failed payment attempts
  - Unusual purchase velocity (10 orders in 1 hour)
  - High-value order from new account
  - IP geolocation mismatch with billing country
  - Known proxy/VPN IP addresses
  - Disposable email addresses
  - Card testing pattern (many small charges)

STRIPE RADAR RULES (Custom):
  Block if: risk_level = 'highest'
  Review if: risk_level = 'elevated' AND amount > 500
  Block if: ip_country != card_country AND amount > 200
  Block if: charge_attempts > 5 in 1 hour
```

### Fraud Prevention Checklist

```
[ ] Enable 3D Secure for high-risk transactions
[ ] Implement velocity checks (max orders per hour per user)
[ ] Require email verification for new accounts before first purchase
[ ] Use address verification (AVS) and CVV checks
[ ] Monitor for card testing (rapid small charges)
[ ] Set up alerts for unusual refund patterns
[ ] Implement device fingerprinting for repeat fraud
[ ] Review disputed charges and update rules
[ ] Log all payment events for forensic analysis
```

## Multi-Currency Support

```typescript
// Currency handling rules
const currencyConfig = {
  USD: { smallest_unit: 'cent', decimal_places: 2, symbol: '$' },
  EUR: { smallest_unit: 'cent', decimal_places: 2, symbol: '€' },
  GBP: { smallest_unit: 'penny', decimal_places: 2, symbol: '£' },
  JPY: { smallest_unit: 'yen', decimal_places: 0, symbol: '¥' },
  BHD: { smallest_unit: 'fils', decimal_places: 3, symbol: 'BD' },
};

// CRITICAL: Always store amounts in smallest currency unit (cents)
// $19.99 → 1999 (integer, no floating point)
// ¥1500  → 1500 (JPY has no decimal subdivision)

// NEVER use floating point for money
// BAD:  const total = 19.99 * 3;  // Might be 59.970000000000001
// GOOD: const totalCents = 1999 * 3;  // Always 5997

// Display formatting
function formatMoney(amountSmallest: number, currency: string): string {
  const config = currencyConfig[currency];
  const divisor = Math.pow(10, config.decimal_places);
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: currency,
  }).format(amountSmallest / divisor);
}
```

## Reconciliation

```sql
-- Daily reconciliation: match your records against Stripe
-- Run this as a scheduled job every morning

-- Step 1: Get all Stripe charges from yesterday
-- (via Stripe API: list charges with created date filter)

-- Step 2: Compare with your payment records
SELECT
  p.id AS our_payment_id,
  p.stripe_payment_intent_id,
  p.amount_cents AS our_amount,
  p.status AS our_status,
  s.amount AS stripe_amount,
  s.status AS stripe_status,
  CASE
    WHEN s.id IS NULL THEN 'MISSING_FROM_STRIPE'
    WHEN p.id IS NULL THEN 'MISSING_FROM_US'
    WHEN p.amount_cents != s.amount THEN 'AMOUNT_MISMATCH'
    WHEN p.status != expected_status(s.status) THEN 'STATUS_MISMATCH'
    ELSE 'MATCHED'
  END AS reconciliation_status
FROM payments p
FULL OUTER JOIN stripe_charges s
  ON p.stripe_payment_intent_id = s.payment_intent
WHERE p.created_at >= CURRENT_DATE - INTERVAL '1 day'
   OR s.created >= CURRENT_DATE - INTERVAL '1 day';

-- Step 3: Alert on mismatches
-- Any non-MATCHED rows need investigation
```

## Idempotency

```
RULE: Every payment operation MUST be idempotent.
If the network fails mid-request, retrying must not double-charge.

HOW:
  1. Generate a unique idempotency key per operation
  2. Store the key with the request
  3. On retry, check if key was already processed
  4. If yes, return the original result
  5. Stripe supports this natively via idempotency_key parameter

IDEMPOTENCY KEY STRATEGY:
  - Payment creation: "create_{orderId}"
  - Refund: "refund_{paymentId}_{amount}"
  - Capture: "capture_{paymentIntentId}"

NEVER use random UUIDs as idempotency keys (they defeat the purpose).
Keys should be deterministic based on the business operation.
```

## Common Anti-Patterns

```
1. STORING CARD NUMBERS
   Never. Ever. Use tokenized payment methods from your gateway.

2. FLOATING POINT MONEY
   $19.99 * 3 = 59.97000000000001. Use integers (cents) everywhere.

3. NO WEBHOOK VERIFICATION
   Always verify webhook signatures. Attackers can forge webhook payloads.

4. SYNCHRONOUS PAYMENT PROCESSING
   Payment confirmation should be webhook-driven, not poll-driven.
   The client should show "processing" and redirect on webhook confirmation.

5. NO RECONCILIATION
   If you do not reconcile daily, discrepancies compound silently.

6. IGNORING EDGE CASES
   Partial refunds, currency conversion, disputes, expired cards,
   3D Secure timeouts -- these are not edge cases, they are Tuesday.
```

## Quick Reference Card

```
ARCHITECTURE: PaymentIntent flow + webhook-driven status updates + idempotency keys
PCI COMPLIANCE: Use Stripe Elements (SAQ A), never touch card data, HTTPS everywhere
STATE MACHINE: Created → Authorized → Captured → Refunded (+ Declined, Disputed, Failed)
SUBSCRIPTIONS: Trial → Active → Past Due → Unpaid → Canceled (dunning automation)
FRAUD: 3D Secure + velocity checks + AVS/CVV + Stripe Radar custom rules
MONEY: Always integers (cents), never floats. Intl.NumberFormat for display.
RECONCILIATION: Daily automated matching, alert on mismatches
IDEMPOTENCY: Deterministic keys per operation, never random UUIDs
```

## When to Use

**Use this skill when:**
- Designing or implementing payment system architect solutions
- Reviewing or improving existing payment system architect approaches
- Making architectural or implementation decisions about payment system architect
- Learning payment system architect patterns and best practices
- Troubleshooting payment system architect-related issues

**Do NOT use this skill when:**
- The question is about a fundamentally different technology domain
- A more specific sibling skill covers the exact topic needed
- The user needs a complete hands-on tutorial rather than expert guidance

## Output Format

```markdown
# Payment System Architect Analysis

## Context Assessment
[Situation summary and constraints]

## Recommended Approach
[Primary recommendation with rationale]

## Implementation Steps
1. [Step with specific details]
2. [Step with specific details]
3. [Step with specific details]

## Trade-offs and Considerations
- [Key trade-off 1]
- [Key trade-off 2]

## Next Steps
- [Immediate action item]
- [Follow-up action item]
```

## Example

**Input:** "Help me implement payment system architect for a medium-scale production application"

**Output:** A structured analysis covering current state assessment, recommended payment system architect approach with specific patterns, implementation roadmap with milestones, and risk mitigation strategies tailored to the application scale and constraints.

## Edge Cases

- **Legacy system integration:** When payment system architect must coexist with legacy approaches, provide a gradual migration path rather than a complete rewrite
- **Scale mismatch:** When the solution complexity exceeds the project scale, recommend a simpler approach and note when to revisit
- **Team skill gaps:** When the team lacks experience with the recommended approach, include learning resources and simpler alternatives
- **Conflicting requirements:** When constraints conflict (e.g., performance vs. maintainability), explicitly state the trade-off and recommend based on stated priorities