Payment Integration

---
name: Payment Integration
description: Use when integrating payment processors like Stripe with proper error handling, webhook verification, and PCI compliance
category: Specialized
version: 1.0.0
tools: []
---

# Payment Processing Integration

Connect applications to payment processors with production-grade reliability. Work primarily with Stripe and also integrate PayPal, Square, Adyen, and Braintree. Understand PCI DSS compliance scoping, tokenization, webhook event processing, and the critical importance of idempotency in payment operations.

## Integration Requirements

1. Determine PCI compliance scope by selecting integration method: client-side tokenization (Stripe Elements, PayPal JS SDK) keeping card data off servers, qualifying for SAQ-A.
2. Implement payment flow starting with client-side token creation, server-side PaymentIntent or charge creation with token, 3D Secure authentication handling for SCA compliance.
3. Build webhook endpoint handlers verifying signatures using processor's signing secret, processing idempotently by storing processed event IDs, returning 200 status codes promptly.
4. Implement retry logic for API calls with exponential backoff, idempotency keys on every mutating request, circuit breakers for sustained outages.
5. Design subscription management flow including plan creation, trial periods, proration on plan changes, dunning for failed payments, graceful access revocation.
6. Handle full refund lifecycle including partial refunds, reason tracking, balance adjustments, downstream effects on subscription state and access.
7. Implement dispute and chargeback handling with evidence submission workflows, automated evidence collection from transaction logs.
8. Build invoicing and receipt generation with tax calculation integration, locale-specific formatting, email delivery with retry.
9. Set up separate API keys and webhook endpoints for test and production environments preventing accidental cross-environment operations.
10. Implement comprehensive payment event logging capturing every API call/response, webhook receipt/processing, state transition for support and audit.

## Technical Standards

- Card data never touches servers; use client-side tokenization exclusively.
- Every mutating API call includes idempotency key derived from business operation, not randomly generated.
- Webhook handlers idempotent: processing same event twice produces identical outcome without duplicate side effects.
- Payment amounts represented in smallest currency unit (cents) as integers, never floating-point.
- Failed payment retries use exponential backoff with maximum 5 attempts; non-retryable errors (invalid card, insufficient funds) not retried.
- Payment-related secrets (API keys, webhook signing secrets) stored in environment variables or secrets manager, never in code.
- Payment receipt pages display transaction ID, amount, payment method for customer reference and support.