Merchant onboarding rollout playbook

01

Objective

Move an approved merchant from integration review to a bounded production rollout with validated rails, webhook endpoints, and reconciliation matchers—without skipping environment gates.

02

Prerequisites

• Merchant approval recorded with enabled rails documented.
• Separate sandbox and production secrets provisioned server-side.
• Lifecycle vocabulary agreed between finance, support, and engineering.
• Webhook endpoint deployed with raw-body verification in non-production first.

03

Operational signals

• Sandbox payments complete full lifecycle without manual overrides.
• Matchers produce expected exceptions for deliberate negative tests.
• Finance confirms recognition policy mapping for Confirmed vs treasury posting.

04

Decision points

• Which rails go live first versus staged enablement.
• Whether low-risk SKUs may fulfill on Paid while finance waits for Confirmed.
• Who approves production API key activation and webhook secret cutover.

05

Escalation paths

• Integration engineering → payment operations lead for rail mismatches.
• Finance controller → treasury for recognition policy exceptions.
• Security → secret rotation if credentials exposed during rollout.

06

Failure modes

• Production keys activated before webhook verification passes staging tests.
• Support macros that mark paid without payment_id references.
• Reconciliation matchers copied from demo data with wrong tolerances.

07

Recovery patterns

1. Freeze production posting; retain sandbox for replay testing.
2. Re-baseline lifecycle transitions from verified provider events.
3. Re-run matchers with documented tolerances before re-enabling auto-resolve.
4. Publish internal rollout checklist updates from root cause.