Stripe Integration

Stripe is the most widely supported payment processor in ActiveManage, handling credit cards, Apple Pay, Google Pay, SEPA, BACS, ACH, Klarna and dozens of regional methods. Connecting it is a few-minute job — but doing it right ensures live charges flow safely and refunds work without manual intervention.

What You Need from Stripe

1. A Stripe account in Live mode.
2. The publishable key (begins pk_live_) — safe for client-side use.
3. The secret key (begins sk_live_) — server-side only, treat like a password.
4. The webhook signing secret — used to verify Stripe-originating webhook calls.

Step-by-Step

1. Open Architect Panel → Stripe Integration.
2. Paste publishable and secret keys. The secret is encrypted at rest.
3. Click Create webhook endpoint — the platform auto-registers /api/stripe/webhook on your Stripe account, copying the signing secret in.
4. Choose capture mode:
   • Automatic: charge captured immediately.
   • Manual: charge authorised but not captured (you confirm later, e.g. when shipping).
5. Click Test connection — the platform creates and immediately voids a $0.50 test charge on a Stripe test card.
6. Save.

Worked Examples

• SaaS subscriptions: Automatic capture, charges run on subscription renewal date.
• eCommerce store: Manual capture — only capture when warehouse confirms shipment.
• Marketplace: Stripe Connect setup — each vendor onboards via Stripe Connect; platform fee is automatically routed.
• Donation platform: One-off automatic captures with no recurring billing.

Warning: Never commit the secret key to source control. Configure it via the platform's encrypted secrets store. Stripe will rotate the key if it sees it in a public Git repo.

Stripe versions its API by date. Each new version may add features, change defaults or rename fields. ActiveManage pins to a specific API version so that Stripe's behaviour cannot change underneath you without warning.

Why Pinning Matters

• Stripe sometimes changes default behaviour — e.g. a webhook event payload gains new fields, or a response field becomes optional.
• Without pinning, your live integration would experience these changes silently and could break.
• With pinning, you get the stable behaviour you tested against; Stripe maintains backwards compat per version.

Reading the Current Pinned Version

Open Architect Panel → Stripe Integration → API Version. The current pinned version is shown alongside the release date and a link to Stripe's changelog.

When to Upgrade

• A new feature requires a newer version — e.g. Apple Pay Domain Verification added in a specific release.
• Quarterly hygiene — review pinned version every 3-6 months to avoid falling far behind.
• Stripe deprecation notice — Stripe occasionally retires very old versions; act before the cutoff.

Upgrade Process

1. Read Stripe's changelog from your current version to the target.
2. List every breaking change that affects features you use.
3. Update the pinned version in a staging environment first.
4. Run your integration test suite, including webhook event reception.
5. Deploy to production during a low-traffic window.
6. Monitor the Stripe dashboard for errors over the next 24 hours.

Worked Examples

• Conservative SaaS: Upgrade once a year after a thorough test cycle.
• Active marketplace: Upgrade quarterly to access new features (e.g. Tax automation).
• Multi-region app: Pin to the version with the broadest payment method support for the regions you serve.

Stripe webhooks let Stripe push events to ActiveManage in real time — “payment succeeded”, “subscription cancelled”, “dispute opened”, “invoice paid”. Reacting to these is how you keep your data in sync with Stripe's authoritative source of truth.

Critical Events to Handle

• payment_intent.succeeded — confirm the charge in your order/ticket record.
• payment_intent.payment_failed — mark the order/subscription as overdue, optionally email the customer.
• customer.subscription.updated — sync subscription status, plan, quantity.
• customer.subscription.deleted — mark the user's subscription cancelled.
• invoice.paid — log the invoice for accounting.
• charge.refunded — reflect the refund in your records.
• charge.dispute.created — flag for manual review.

How ActiveManage Receives Them

The endpoint /api/stripe/webhook accepts POSTs from Stripe. Every request is verified against the webhook signing secret to prevent spoofing. Valid events are dispatched to handlers that update database records.

Replay and Investigation

Every received event is logged. If your handler had a bug or your DB was unreachable, you can mark events for replay from the Stripe dashboard — and ActiveManage will reprocess them with the (now-fixed) handler.

Worked Examples

• Subscription churn: Listen to customer.subscription.deleted — trigger a “sorry to see you go” email plus an internal alert for accounts above a revenue threshold.
• Failed renewal: Listen to invoice.payment_failed — start a dunning sequence (3 retry emails over 7 days), then suspend service if still unpaid.
• Dispute alert: Listen to charge.dispute.created — page the finance team and freeze the related order.
• Refund: Listen to charge.refunded — release any reserved stock/booking and notify the user.

Note: Webhook events arrive out of order. Always check the event timestamp and ignore older events that would clobber newer state.

Failed payments are an inevitable part of accepting cards online — expired cards, insufficient funds, fraud blocks, network issues. A robust dunning strategy recovers most of them without manual chasing.

Categories of Failure

• Card declined (soft): Insufficient funds, temporary fraud check — retry later usually succeeds.
• Card declined (hard): Closed account, do-not-honour — must ask customer for a new card.
• Card expired: Update the card before retrying.
• Network or 3DS: Often a temporary glitch; immediate retry usually works.

Default Dunning Flow

1. Day 0: First failure. Retry once after 24 hours; email the customer.
2. Day 3: Second retry. Second email with a “Update card” deep link.
3. Day 7: Third retry. Final notice email warning of service suspension.
4. Day 10: Service suspended. Customer prompted to update card on next sign-in.
5. Day 30: Subscription cancelled and archived. Manual reactivation only.

Configuring

Open Site Settings → eCommerce → Failed Payments. Adjust retry days, email template names, and the suspension/cancellation thresholds.

Worked Examples

• SaaS: Three retries over 10 days then downgrade to free tier rather than full cancel.
• eCommerce: Single retry; on failure the order is cancelled — re-order required.
• Membership site: Long grace (30 days) to retain member relationships; aggressive email cadence to recover.
• Donation platform: Single retry then quietly fail — chasing donors over £5 looks bad.

Tip: Schedule retries for early in the customer's billing cycle (e.g. morning of payday) — recovery rates jump by 20–30% on these days.