FAQ

Monetize.software is a comprehensive in-app purchase platform that helps developers monetize their applications through subscriptions and tokenized payments. The platform provides:

• SDK v3 (recommended) — bundled npm package with Shadow DOM modal, headless mode for backends, and Chrome Extension MV3 support
• SDK v2 (legacy) — single <script> tag for quick HTML integrations without a build step
• Headless / Server-side — BillingClient from SDK v3 /core for custom UI, AI proxy via ApiGatewayClient, bring-your-own auth
• Payment processing through Stripe, Paddle, Chargebee, Freemius, and Overpay
• Analytics and reporting to track your revenue and user behavior

You can choose between subscription models (monthly/yearly) or token-based payments for pay-per-use scenarios.

Use SDK v3 for any new project. It’s bundled, renders without an iframe, has a headless /core export for backends, and is the only SDK that passes Chrome Web Store review (MV3, no remote code). See the SDK v3 Quickstart.

Stay on SDK v2 if:

• You ship a plain HTML landing without a build step (drop-in <script> tag)
• You already integrated v2 and don’t need the new features

v2 is in maintenance mode but supported — it isn’t going away.

Integration time depends on your chosen approach:

SDK v3 — PaywallUI in the browser (Recommended):

• 10–20 minutes for basic web setup
• 30–45 minutes for a Chrome Extension (offscreen + service worker)
• Bundled npm package, no iframe, Shadow DOM modal

SDK v3 — Headless / server-side:

• 30–60 minutes for basic integration
• You build your own UI and run server-side flows (apiKey + identity, webhooks for state)
• Full control over UX, works from any backend (Node, Python, Go, PHP, …) — the API is a typed JS wrapper but the underlying HTTP contract is language-agnostic
• See Headless / server-side

SDK v2 — Client-Side (legacy, HTML landings):

• 10–15 minutes for basic setup
• Single <script> tag, no build required
• Maintenance mode — new projects should use SDK v3

All approaches include comprehensive documentation and code examples to get you started quickly.

SDK v3 in the browser: Minimal frontend coding. Install the npm package, instantiate PaywallUI with your paywallId, call paywall.open() on your CTA button. No backend required for the basic flow — auth, checkout redirect, and state sync happen via the SDK.

Headless / Server-side: More technical knowledge required:

• Backend development experience (Node, or any language that can speak HTTP — see Headless / server-side)
• Webhook handling to sync subscription state to your DB
• Identity passing (apiKey + identity per request) when you bring your own auth

Either way the dashboard handles paywall design, pricing, trial settings, and payment processor configuration — no code needed for those.

Monetize.software works with various application types:

Web Applications:

• SaaS platforms
• Content websites
• Online tools and calculators
• Educational platforms

Extensions:

• Chrome extensions
• Browser add-ons

Mobile Apps:

• Using server-side SDK
• React Native applications

Desktop Applications:

• Electron apps
• Web-based desktop software

Monetize.software supports five payment processors. You can connect multiple to one paywall and use them for different regions, products, or as fallbacks.

Stripe — global coverage (190+ countries), low fees (2.9% + 30¢), strong fraud protection. Recommended for most businesses.

Paddle — merchant of record. Handles VAT/sales-tax compliance automatically. Good for digital products with global sales.

Chargebee — flexible subscription billing with advanced dunning, revenue recognition, and tax tooling. Suitable for enterprises with complex billing rules.

Freemius — designed for WordPress plugins/themes and SaaS. Merchant of record; hosted checkout. Note: Freemius does not provide a hosted customer portal — use SDK methods (cancelSubscription) directly for cancel flows.

Overpay — alternative card acquirer with broad regional support. Useful when Stripe/Paddle reject high-risk verticals.

See Payment Processors for full setup.

Yes! Monetize.software supports various promotional strategies:

Free Trials:

• Time-based trials (7, 14, 30 days)
• Usage-based trials (number of actions)
• Anonymous trials (no signup required)

Promotional Pricing:

• Discount coupons
• Limited-time offers
• First-month discounts
• Lifetime deals

Token Bonuses:

• Welcome tokens for new users
• Referral bonuses
• Seasonal promotions

Configure these options in your paywall settings dashboard.

SDK v3 ships as one npm package with three integration modes — pick by how much you want to own.

PaywallUI (browser modal) — drop-in:

✅ Quick 10-minute setup, ready-made paywall in Shadow DOM, built-in OAuth/email/OTP auth, automatic state sync across tabs ❌ Visual customization limited to dashboard settings (brand color, layout, copy)

PaywallUI in a Chrome Extension — same API plus a shared offscreen document:

✅ One auth/billing state across popup, content scripts in every tab, and the service worker; passes CWS review (no remote code, no iframe) ❌ Requires offscreen + service-worker setup (see the Extension guide)

BillingClient headless (server-side) — full control:

✅ Bring-your-own auth, your own pricing/checkout UI, custom AI proxy via ApiGatewayClient, server-rendered access checks ❌ You implement webhooks for state sync, the UI is yours to build

All three share one paywallId — switch modes without migrations. See SDK v3 Quickstart.

Two paths, depending on where your users live:

Use our AuthClient (browser flows):

• Built-in email + password, email OTP, OAuth (Google / Apple), anonymous sign-in
• Session persistence + automatic token refresh + cross-tab sync via the SDK
• Best for SPAs and Chrome extensions where you don’t already have a login UI

Bring your own auth (headless/server flows):

• Use apiKey + identity (email and your stable userId) on every server-side call
• Your existing login system stays the source of truth; we use the email/userId as a binding key
• State sync via webhooks (subscription.*, payment.*) into your DB
• See Headless / server-side

Security:

• PKCE + per-call state nonce on OAuth (resistant to postMessage spoofing)
• Bearer tokens are short-lived; refresh handled automatically by the SDK
• PCI DSS via payment processors (checkout is hosted by Stripe/Paddle/Chargebee/etc.)
• apiKey is server-only — the SDK refuses to construct with it in browser context

Webhooks are HTTP callbacks that notify your server about payment events in real-time:

Key Events:

• payment.completed - Successful payment
• subscription.created - New subscription
• subscription.cancelled - Subscription cancelled
• refund.created - Refund processed
• trial.started - Trial period began

Why Use Webhooks:

• Instant notification of payment status
• Reliable even if user closes browser
• Synchronize your database with payment data
• Automate user access management
• Handle edge cases and failures

PaywallUI (Shadow DOM modal):

• Brand color, layout (vertical / horizontal / compact), copy, and localization — all from the dashboard
• Renders inside a Shadow DOM so host page CSS doesn’t bleed in (and vice versa)
• Container customization for non-modal placement (inline, drawer) via SDK options

Headless (BillingClient):

• Full control — render your own pricing page, your own buttons, your own UX
• billing.bootstrap() gives you prices, offers, settings, locales to render however you want
• billing.createCheckout({ priceId }) returns the URL — you redirect when ready

Monetize.software supports locale pricing:

Benefits:

• Increase conversion rates globally
• Fair pricing for all users
• Maximize revenue potential
• Reduce payment failures

Refund Policy:

• You control your refund policy
• Process refunds through payment processor
• Automatic access revocation
• Partial refund support

Refund Process:

1. Customer requests refund
2. You approve in the payment processor’s dashboard (Stripe, Paddle, Chargebee, Freemius, or Overpay)
3. Webhook (refund.created) notifies your system
4. User access automatically removed
5. Refund processed by the payment processor

Best Practices:

• Clearly state refund policy
• Offer trial periods to reduce refunds
• Provide excellent customer support
• Use partial refunds for usage-based services

Revenue Analytics:

• Monthly recurring revenue (MRR)
• Annual recurring revenue (ARR)
• Revenue growth trends
• Conversion funnel analysis

User Metrics:

• Active subscribers
• Churn rate analysis
• Customer lifetime value (LTV)
• Trial conversion rates

Payment Analytics:

• Payment success rates
• Failed payment analysis
• Geographic revenue breakdown
• Popular pricing plans

Real-Time Dashboard:

• Live transaction monitoring
• Today’s revenue and signups
• Active trial users
• Payment processor performance

Export Options:

• CSV data export
• Custom date ranges
• Automated email reports

Conversion Tracking:

• Paywall open rates
• Payment completion rates
• Trial-to-paid conversion
• Geographic conversion differences

User Journey Analysis:

• Time from signup to payment
• Most effective marketing channels
• Feature usage correlation with payments
• Churn prediction indicators

Optimization Tips:

• Offer appropriate trial periods
• Use geographic pricing
• Optimize paywall timing
• Provide clear value propositions

Official Support Channels:

Documentation:

• Comprehensive guides and API references
• Code examples and tutorials
• Integration walkthroughs
• Best practices and tips

Community Support:

• Telegram Community  - Active community chat

Direct Support:

• Email support (support@monetize.software)
• Priority support for paid plans
• Technical consultation available

Response Times:

• Community support: Usually within a few hours
• Email support: 24-48 hours
• Priority support: Within 4 hours
• Critical issues: Immediate response

Self-Service Resources:

• FAQ section (this page)
• Integration templates