ExtPay: taking payments inside a browser extension without running a server

The whole model in one snippet

ExtPay is the JavaScript library behind ExtensionPay.com, a service for adding payments to browser extensions, and the README puts the entire flow in a few lines:

// Example code
// your-extension/background.js
const extpay = ExtPay('your-extension-id');
extpay.startBackground();

extpay.getUser().then(user => {
    if (user.paid) {
        // ...
    } else {
        extpay.openPaymentPage()
    }
})

That is the product in miniature. You initialise with your extension id, you ask whether the current user is paid, and if not you send them to a payment page. There is no server for you to write, no webhook endpoint to expose and no database of subscribers for you to maintain, because the hosted service holds that state and your extension asks it about the current user.

The README quotes a user describing the same experience, saying that the setup took less than an hour and that they would not have monetised at all if they had to use Stripe directly, and that the service has earned extension creators over 800k dollars and counting.

The library uses Mozilla's webextension-polyfill internally for compatibility across browsers, which means it should work on almost all modern browsers, and the README points at a sample extension for both manifest versions as the way to learn by example.

The manifest requirements are the real integration cost

Two things have to be in the extension manifest, and both of them are visible to the user or to the browser, which is why they are worth reading carefully.

First, the storage permission:

{
    "permissions": [
      "storage"
    ]
}

The note that follows is the important one. ExtPay will not show a scary permission warning when users try to install your extension, which is a claim about how the permission is used rather than about the permission list itself.

For Firefox, the manifest may also need "https://extensionpay.com/*" in the extension manifest's permission for ExtPay to work properly.

And if you have a content_security_policy in your manifest, or you get a Refused to connect error, you have to add connect-src https://extensionpay.com to the extension's content security policy, with a link to the Mozilla documentation on the subject.

The install itself is a single command:

npm install extpay --save

If you are not using a bundler, you can copy the dist/ExtPay.js file into your project, or the ExtPay.module.js for ESM and the ExtPay.common.js for CommonJS, and the package manifest points at those same three files for the main, module, unpkg and jsdelivr entries.

The service worker catch that costs everyone an hour

The library has to be present in the background file, which is often named something like background.js, and the README is emphatic that it will not work correctly without it. With a bundler you can import or require it right in the background file.

The manifest V3 arrangement is a service worker:

{
    "background": {
        "service_worker": "background.js"
    }
}

And the background script does this:

// background.js

importScripts('ExtPay.js') // or `import` / `require` if using a bundler

var extpay = ExtPay('sample-extension'); // Careful! See note below
extpay.startBackground(); 

The note about service workers is the trap in this library, and it is worth reading twice. In the example above, extpay will become undefined when accessed in service worker callbacks, so to use extpay in a callback you have to redeclare it:

chrome.storage.local.get('foo', function() {
    var extpay = ExtPay('sample-extension');
    // ...
})

And the instruction that follows is the one people get wrong: make sure not to use extpay.startBackground() in callbacks, because it should only be called once.

For manifest V2 without a bundler, the file goes into the manifest itself, with the background scripts array listing both ExtPay.js and background.js, and the background script uses the same two calls, const extpay and startBackground.

This is a real sharp edge in an otherwise simple integration, and it is the kind of thing that produces an extension that works in development and breaks in production.

What the user object tells you

The getUser call makes a network request to the service and returns a user object, and the properties on it are the vocabulary for gating features.

There is a paid flag, which is true or false, and is meant to be a simple way to tell whether the user should have paid features activated. The subtlety is that for subscription payments, paid is only true if subscriptionStatus is active, so a lapsed subscriber is not a paid user in the code, which is the behaviour you want but not the behaviour most people assume.

There is paidAt, a Date object for when the user first paid, or null. There is email, the user's email if there is one or null. There is installedAt, a Date object for when the user installed the extension, which is what a trial is measured from. There is trialStartedAt, null or a Date object for when the user confirmed the free trial. And there is plan, which is null or the plan the user is on, described as an object with fields like unitAmountCents, currency, nickname, intervalCount and interval.

The getUser call can throw on network failure, and the documentation asks you to consider that possibility in your code, showing the promise form with a catch handler. That is worth taking seriously, because a paid feature that fails open on a network error is a feature you have given away.

The rest of the API follows the same pattern: openPaymentPage to let the user pay, openPaymentPage again to manage a subscription, openTrialPage for a free trial, openLoginPage for a user who has already paid, getPlans to list available plans, and onPaid.addListener to run code when payment completes.

Editorial conclusion

ExtPay fits a solo extension developer who wants a paid tier or a subscription without integrating Stripe, handling webhooks and building a login system, and who is comfortable sending their users to an external checkout page. It does not fit a team that needs the payment flow to live on its own domain, or a project with a strict policy against third-party calls from the extension. Before adopting it, read the manifest requirements, and check the pricing and the plan model, since the paid flag is tied to an active subscription rather than to a historical payment.

Frequently asked questions

Official sources

1. Glench/ExtPay on GitHub
2. Issues
3. Project website
4. README
5. Releases