Payment Gateway Integration Checklist

Compare candidates on processing rate, supported card brands and wallets, payout cadence, chargeback tooling, and 3DS2 support. Common picks for SMB DTC: Shopify Payments (Stripe under the hood) for Shopify, Stripe for headless, Braintree for PayPal-native flows, Adyen for international, Authorize.Net for legacy. Capture the decision with rationale so finance and CX can plan around fees and payout timing.

Submit EIN, articles of incorporation, beneficial ownership, and bank account for ACH payouts. Underwriting commonly flags supplements, CBD, firearms, alcohol, and high-ticket categories — confirm the gateway accepts your MCC before integrating.

Hosted redirect typically qualifies for SAQ A. Embedded fields (Stripe Elements, Braintree Hosted Fields) are SAQ A-EP. Any direct card capture on your servers is SAQ D and requires a QSA. The hosting model decision below should match the SAQ you can realistically maintain.

Hosted redirect (gateway-hosted page) keeps PCI scope minimal but degrades on-brand experience. Embedded tokenized fields keep card data off your servers via iframe-isolated inputs. Direct API gives full UI control but pulls your servers into PCI scope and requires annual QSA assessment.

For Shopify, install the gateway's certified app from the App Store. For headless or custom platforms, pin the official SDK version (stripe-node, braintree-node, etc.) and avoid wrappers without security review.

Inject keys via environment variables at runtime. Separate test and live key sets per environment. Restrict live key access to production deploy roles only — a leaked secret key in a public repo is the most common payments incident.

Implement idempotency keys on every charge call so retries don't double-charge. Store the gateway's transaction ID, last-4, brand, and AVS/CVV result on the order. Refund logic must support partial refunds and reference the original transaction.

Subscribe to charge.succeeded, charge.failed, charge.dispute.created, and refund.created at minimum. Verify webhook signatures on every request — unsigned webhooks are a common spoofing vector. Return 2xx within 3 seconds or the gateway will retry and queue duplicates.

Test Visa, Mastercard, Amex, Discover, and JCB success and decline scenarios using the gateway's test card numbers. Cover 3DS2 challenge, AVS mismatch, CVV decline, insufficient funds, and expired card. Confirm the order state machine handles each correctly.

Use the gateway's drop-in or Elements/Hosted Fields so card data never touches your DOM. Match brand styling but resist over-customizing — every CSS override is a potential checkout regression. Include the trust badges customers expect (Visa, Mastercard, lock icon).

Mobile is 60-70% of DTC traffic. Test on real iOS Safari and Android Chrome — emulators miss keyboard behavior, autofill, and the iOS numeric keypad for card fields. Confirm the address autocomplete (Google Places) doesn't break on small screens.

Generic "Payment failed" loses sales. Distinguish soft declines (insufficient funds — retry with same card), hard declines (suspected fraud — try another card), AVS mismatches (re-enter address), and 3DS challenges (complete bank verification). Never expose raw gateway error codes to the shopper.

Wallets routinely lift mobile conversion 5-15%. Apple Pay requires a verified domain file at /.well-known/apple-developer-merchantid-domain-association. PayPal and Buy with Prime are worth A/B testing for the segments they reach.

Turn on Stripe Radar / Braintree Advanced Fraud / Adyen RevenueProtect with sensible defaults. Configure 3DS2 to trigger on risk score, not on every transaction — full 3DS on low-risk orders crashes conversion. Block known-bad IPs and velocity-limit by email and BIN.

Run an SSL Labs scan against the checkout subdomain; fix any A- or below grade before launch. Disable TLS 1.0 and 1.1 — PCI DSS prohibits them. Verify HSTS is set on the storefront and checkout.

For subscriptions or saved-card flows, store only the gateway's payment method token (pm_..., or vault ID). Never store PAN, CVV, or magnetic stripe data. Enable the gateway's network token / account updater so expired and reissued cards keep working.

SAQ A-EP and SAQ D require quarterly external vulnerability scans by an Approved Scanning Vendor (Trustwave, SecurityMetrics, ControlScan). Calendar the scans now so the first one isn't 90 days overdue at the first PCI attestation.

Complete the SAQ matching the hosting model selected, sign the Attestation of Compliance, and submit to the acquiring bank. Store with the dataflow diagram, network diagram, and policy docs the assessor will request annually.

Place a real $1-5 order with a personal card before opening checkout to traffic. Confirm the charge in the gateway, the order in the OMS, the webhook fired, the confirmation email sent, and the funds appear in the next settlement. Refund yourself afterward.

Page on payment-success-rate drops below threshold (e.g., 90% over 15 minutes), new chargebacks, and webhook delivery failures. Route to Slack #payments-alerts and PagerDuty for off-hours. A silent gateway outage during a Meta promo is a five-figure mistake.

Match the gateway's daily settlement report (gross, fees, refunds, chargebacks, reserves) against the ACH deposit hitting the bank. Hand the reconciliation template to bookkeeping (QuickBooks, Xero) so the first month-end close runs cleanly.

Train Gorgias / Zendesk agents on the dispute response window (typically 7-21 days) and what evidence wins: AVS match, CVV match, IP geolocation, delivery confirmation, customer communication. A chargeback rate above 1% threatens the merchant account itself.