Introduction
Agencies lose margin when payment go-lives become war rooms: wrong keys, webhook URLs pointing to staging, HPOS incompatibilities, or support macros that promise refunds the gateway cannot automate.
This runbook consolidates PatSaTECH-style integration discipline into a client-deliverable checklist. It stitches together WooCommerce payment gateway integration checklist, staging vs production testing, safe plugin updates, order status mapping, and PCI-safe logging.
Quick answer
No production keys until staging matrix passes. One change window owner. Webhook health dashboard day 1. Deliver client a one-page support doc: descriptors, refund policy, escalation contacts, and what not to log.
1. Pre-project intake
Collect before build:
| Item | Notes |
|---|---|
| Processor contract status | Live vs pending underwriting |
| Integration model | Hosted, embedded, redirect (hosted vs integrated) |
| Currencies and settlement (display vs settlement) | |
| Subscriptions, BNPL, ACH, marketplace scope | |
| HPOS plan (HPOS article) | |
| Plugin vs custom decision (plugin vs custom) |
Confirm who holds merchant of record and chargeback inbox.
2. Build and staging sign-off
Engineering deliverables:
- Gateway plugin configured with sandbox keys
- SSL valid on checkout host (SSL insecure checkout)
- Webhook endpoint registered + signature verified
- Order status map documented (mapping guide)
- Idempotency verified on replay (idempotency)
Staging test matrix (minimum):
- Successful sale (classic + Blocks if used)
- Decline path
- 3DS if applicable (3DS/SCA)
- Refund from Woo + from gateway dashboard
- Wallet pay if in scope (digital wallets)
- Subscription renewal or GF/EDD recurring if in scope
Sign-off: client product owner + agency lead in writing (ticket or doc).
3. Production cutover
Cutover steps:
- Maintenance window communicated (even if zero downtime)
- Replace sandbox keys with live; double-check mode toggles
- Update webhook URLs to production domain
- Verify billing descriptor with client (descriptors)
- Place live micro-transaction (refund immediately if policy allows)
- Enable monitoring alerts (webhook monitoring)
Do not simultaneously launch unrelated Woo major upgrade + gateway swap + theme redesign.
If migrating processors, follow migration article sequencing.
4. First 72 hours monitoring
Watch:
- Authorization rate vs staging baseline (analytics)
- Webhook 4xx/5xx rates
- Duplicate capture alerts (duplicate payments)
- Support ticket volume mentioning “payment”
Incident triggers: checkout 500, 100% webhook failure, settlement currency wrong, gift card split errors (gift cards).
Escalate to processor with transaction IDs—not PAN (PCI-safe logging).
5. Client handoff package
Deliver:
- Architecture one-pager (gateway, plugins, HPOS status)
- Order status ↔ event map
- Safe update procedure (safe updates)
- Support macros for declines, duplicates, chargebacks (chargebacks vs refunds)
- TCO summary of fees (TCO article)
- Renewal dates for plugin licenses (buying guide)
- Link to plugin installation support if purchased
Optional: schedule 30-day review for auth rate and reconciliation sample.
FAQ
Who owns webhook secret rotation?
Define in handoff—often client DevOps with agency advisory.
Should agencies hold live API keys?
Prefer client vault; agency access time-boxed and audited.
What about headless frontends?
Add headless payment primer appendix.
Related reading
Key takeaways
- No production keys until the client-approved sandbox matrix passes on staging that mirrors HPOS/Blocks plans.
- Assign one cutover owner and a written rollback path—agencies lose margin on Friday war rooms.
- Webhooks must point to production with valid secrets before finance trusts order status.
- Deliver a one-page client handoff: descriptors, refund policy, escalation, and what not to log.
- Link the commercial landing: WooCommerce payment gateways for agencies.
