FastSpring

You are integrating FastSpring as the Merchant of Record for a [Django / Next.js / FastAPI / Rails] application selling [SaaS subscriptions / one-time digital goods / usage-metered plans]. Follow these rules verbatim:

1. **Integration surface.** Use the FastSpring JavaScript Store Builder Library (popup storefront) or Embedded Component Library (in-page checkout) for the buyer-facing flow, and the FastSpring REST API (developer.fastspring.com) for server-side operations (subscription mutations, refunds, coupon creation, product catalog reads). Do NOT build a custom card form — FastSpring is the Merchant of Record and must be the one that collects PCI-scoped card data.

2. **Product setup.** Create products, pricing (including per-region localized prices where relevant), and subscription plans inside the FastSpring dashboard first. The server-side integration references these by product path — it does not create products dynamically in most flows.

3. **Webhook pipeline (critical).** Register a single webhook endpoint on your server. Subscribe to at minimum: `order.completed`, `subscription.activated`, `subscription.updated`, `subscription.canceled`, `subscription.payment.failed`, `return.created`. Enable **webhook expansion** in the FastSpring app so payloads include the full account, order, and subscription objects — this eliminates follow-up API round-trips on every event. Verify every request's HMAC signature using your webhook secret before processing. Reject requests with invalid or missing signatures.

4. **Idempotency and replay.** Persist every webhook's event id before acting on it. FastSpring may re-deliver events; your handler must be idempotent. When webhooks fail or are missed, use the `/events` endpoint to replay a window rather than trusting the original delivery alone.

5. **Entitlement model.** Source of truth for 'is this user a paying subscriber' is your local subscription mirror updated by webhooks — not the FastSpring API at request time. Treat the webhook stream as the ledger; reconcile nightly via a backfill cron that pages through the subscriptions API.

6. **Security best practices.** Store the FastSpring API credentials and webhook secret in [environment variables / your secrets manager]. Never expose server-side API keys to the browser. The Store Builder Library only needs the public storefront key. Enforce HTTPS on the webhook endpoint. Reject any non-FastSpring IP if you operate in a zero-trust network.

7. **Tax and compliance.** As MoR, FastSpring handles all VAT/GST/US sales tax calculation, collection, filing, and remittance. Do NOT attempt to compute or collect tax on your side. Do not store buyer addresses for tax purposes — rely on FastSpring's buyer records.

8. **Refund policy.** Refunds initiated via API or dashboard trigger a 3.5% refund fee on the order total. Full refunds credit back the original transaction fee to your account. Design refund UX to minimize partial-refund complexity.

9. **FX awareness.** If your product is priced in USD but sells globally, FastSpring applies a 3.5% markup on major currencies and 5.5% on all others at conversion time. Factor this into margin modeling — don't advertise a USD price and assume the customer pays the mid-market equivalent.

10. **Account-hold defense.** Document KYC/KYB upload requests promptly; unresponsiveness can trigger account holds. For sellers processing under $5,000/year, budget the $150/year risk-screening fee or pre-fund it before the account goes live.

11. **Testing.** Use FastSpring's test-mode storefront and dedicated test card numbers before routing real traffic. Run a full end-to-end test: webhook receipt → subscription mirror update → entitlement grant → renewal → cancellation → refund. Verify webhook signatures in test mode too.

Deliverables: (a) a `FastSpringWebhookHandler` that verifies signatures and routes each event type to a dedicated handler, (b) a local `Subscription` mirror table populated by webhooks, (c) an admin-only endpoint that replays events from `/events` for a given window, and (d) a nightly reconciliation job that reads subscriptions from the API and detects drift from the local mirror.