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.

Generate publishable and secret test keys; never commit these to the repo. Store in the secrets manager (1Password, AWS Secrets Manager, Vault) and grant access to engineering only.

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.

Open a support case with the gateway including request/response logs, timestamps, and the test card used. Re-run the failing scenarios after the fix and document the resolution before proceeding to checkout build.

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.

Don't rely on the redirect to mark the order paid — the customer may close the tab. The webhook is the source of truth; the thank-you page is a UX nicety. Fire the GA4 purchase event and Meta CAPI conversion server-side from the webhook to dodge ad-blocker loss.

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.

Direct API integrations require a Qualified Security Assessor for the on-site assessment plus penetration testing. Budget 8-12 weeks and $30-100K depending on environment scope. Most SMBs avoid this path — confirm the hosting decision is worth the cost.

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.

Director of E-commerce or COO confirms launch readiness across engineering, finance, and CX. Capture the decision, any deferred items, and signature for the audit trail.