Payment Gateway Integration Template

For most SaaS startups and mid-market companies, Stripe is the default choice: best API documentation, fastest integration, and strong ecosystem. Adyen is better for enterprise companies with complex multi-market requirements and high-volume optimizations. Braintree (PayPal) is strongest when PayPal is a primary payment method. Evaluate based on your specific payment methods, markets, volume, and engineering team's experience. Use the evaluation scorecard in this template to compare objectively.

SAQ A (the lightest compliance level) should be your goal. This means all card data is handled by the provider's hosted fields or checkout. Your servers never see raw card numbers. If you need more control over the payment page design, SAQ A-EP is acceptable but requires more security work. Never build a system where raw card data passes through your servers (SAQ D) unless you are a payment company. The compliance and audit costs are significant.

Every major provider has a sandbox environment with test card numbers that simulate various scenarios: successful payments, declines, 3DS challenges, network errors, and disputes. Run your full test suite against the sandbox. Then do a gradual rollout: route 5% of live traffic to the new integration, monitor success rates and latency for 48 hours, and ramp up if metrics are healthy. Keep the ability to route 100% back to the old system for 30 days after full rollout.

If your billing logic is straightforward (plan + seats, monthly/annual), use the provider's subscription system (Stripe Billing, Chargebee, etc.). It handles proration, invoicing, dunning, and tax automatically. Build your own only if you have complex billing requirements that the provider cannot handle: metered billing with custom aggregation, multi-party payouts, or hybrid pricing models that require custom invoice line items. Use a [build-vs-buy assessment](/tools) to evaluate the tradeoff.

Card networks (Visa, Mastercard) flag merchants above 0.9-1.0% chargeback rate. Exceeding this threshold triggers monitoring programs with higher fees or potential termination. A healthy SaaS product should target < 0.3%. If your chargeback rate exceeds 0.5%, investigate: common causes are unclear billing descriptors (customers do not recognize the charge), missing cancellation confirmations, and delayed refunds. ---