Your extension. Ready to get paid.
Use your own extension and interface. Connect payments, customer identity, and tracking with the local SDK; templates are optional.
Integrate your own extension first#
Open My apps → your app → Setup → Connect usage tracking. Download the configured integration kit or copy the manifest, worker, and popup snippets. This path works without choosing a theme, downloading a demo product, connecting Stripe, or creating a pricing plan.
Merge the SDK and background worker into your source. Register startBackground() and startAnalytics() at worker top level; call track('app_open') when your interface opens and track('feature_export') when your own feature runs. Then add the payment snippet below and gate protected actions. Publish your extension update; TopPay cannot inject code into an installed extension.
Optional: try a configured demo#
- 1
Select an app and active plan
Open My apps → your app → Setup. Choose a pricing plan. Finish Stripe onboarding and plan syncing if the download button is disabled.
- 2
Download and load it
Choose Download ready-to-test extension. Unzip the file. In Chrome, open
chrome://extensions, enable Developer mode, select Load unpacked, and choose the folder containingmanifest.json. - 3
Try the customer experience
Open the extension from Chrome’s extensions menu. It loads the selected price and checks access. Click Pay or Start trial. Stripe opens its email and payment form; after completing checkout, the worker verifies access and reopens the popup when supported (or click the extension icon). A premium button appears only after access is confirmed.
What’s in the package#
| File | Purpose |
|---|---|
background.js | Registers lifecycle analytics and retries pending events. |
manifest.json | Chrome configuration and permission to contact the configured TopPay origin. |
config.js | Public app and plan configuration. No server secrets. |
payframe.js | Local TopPay SDK. The filename is retained for compatibility. |
popup.html / popup.js / style.css | A minimal checkout, access-check, and billing-management interface. |
README.md | Install steps, payment-mode notes, and identity limitations. |
Move the integration into your product#
Keep the SDK bundled locally. Load configuration and SDK before your popup logic. Replace the example callbacks below with your actual paywall, feature, and error UI.
// In popup.html: config.js, payframe.js, then your local popup.js.
// The ready-to-test download already supplies TOPPAY_CONFIG.
const { appId, profileId, origin } = globalThis.TOPPAY_CONFIG;
const topPay = TopPay(appId, {
profileId,
apiBaseUrl: origin + "/api"
});
// Worker must call startBackground() at top level (included in the kit).
const stop = topPay.watchAccess(user => {
if (user.active === true) showPremium();
else showPaywall(user.status); // Include retry/billing help; keep identity.
}, { profileId });
window.addEventListener('pagehide', stop, { once: true });
async function runPremiumFeature() {
try {
const { active } = await topPay.getUser({ profileId });
if (!active) {
showPaywall(); // Implement this in your product.
return;
}
await yourPremiumFeature(); // Your own product action.
} catch {
showRetryMessage(); // Keep the paid action locked on failure.
}
}
async function buySelectedPlan() {
return topPay.openPaymentPage({ profileId });
}
async function manageBilling() {
return topPay.openBillingPortal();
}Return from checkout and keep access current#
With the current SDK and startBackground() in your service worker, openPaymentPage() opens Stripe in a compact checkout window. The email/card form remains hosted by Stripe; it is not embedded in the extension popup.
After Stripe returns to TopPay, the worker verifies the same installation and selected plan. It retries while payment events are pending, then reopens your extension’s action popup where supported (Chrome 127+). The confirmation page stays available if reopening fails. Repeated clicks reuse the current checkout. No broad tabs, browsing-history, or content-script permission is needed.
const stop = topPay.watchAccess(user => {
premium.hidden = user.active !== true;
paywall.hidden = user.active === true;
billingButton.hidden = !user.billingAvailable;
// Render user.status: blocked, past_due, canceled, expired,
// refunded, disputed, unpaid, or unavailable.
}, {profileId});
window.addEventListener("pagehide", stop, {once:true});The watcher checks immediately, every 15 seconds while visible, on focus/connectivity changes, at known expiry, and after a background update. The worker checks approximately every five minutes; browser alarms can be delayed. Pending checkout retries survive service-worker suspension for up to 30 minutes. Network failures keep premium locked. Always verify again before each protected action; UI polling is not a substitute for backend enforcement.
For multiple alternative plans, pass {profileIds: [monthlyPlanId, lifetimePlanId]} to watchAccess. Valid access to an explicitly included alternative keeps the feature unlocked. Existing extensions must ship the updated SDK, worker, and UI listener; a dashboard change does not update already-distributed code.
Chrome permissions and identity#
The configured demo needs storage, alarms, and host access to its TopPay origin. Its background worker records install/update events and registers a removal callback. It has no content scripts and does not need access to the user’s browsing history. Put the SDK in a local JavaScript file; do not load it as a remote script.
{
"permissions": ["storage", "alarms"],
"host_permissions": ["https://toppayext.com/*"]
}Preserve permissions required by your own product. Both downloads use a background worker for analytics retries. The configured demo watches access while open and checks again before each protected action. The worker also refreshes access in the background.
Know what to test and what success looks like before launch.
