ExtPay.js — Monetize browser extensions with payments

The JavaScript library for ExtensionPay.com, a service to easily add payments to browser extensions. So far ExtensionPay has earned extension creators over $500k and counting!

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

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

Below are directions for using this library in your browser extension. If you learn better by example, you can also view the code for a sample extension. This library uses Mozilla's webextension-polyfill library internally for compatability across browsers which means it should work on almost all modern browsers.

"It hasn't even been 1 year yet and I'm already going to pass $4,000 in annual subscriptions on an extension that I never in a million years thought I would be able to make a penny from. Thanks so much for creating this tool! I would not have even tried to monetize if I had to use Stripe directly, and you made it so easy. It took less than an hour to set it up and test it. Definitely have plans to create more extensions now that I know how easy it is to monetize them." - David, Neobuyer extension

1. Install
2. Configure your manifest.json
3. Add ExtPay to background.js (required!)
4. Use extpay.getUser() to check a user's paid status
   • user object properties
5. Use extpay.openPaymentPage() to let the user pay
6. Use extpay.getPlans() to list available payment plans
7. Use extpay.onPaid.addListener() to run code when the user pays
8. Use extpay.openPaymentPage() to let the user manage their subscription
9. Use extpay.openTrialPage() to let the user sign up for a free trial
10. Use extpay.openLoginPage() to let the user log in if they've paid already

Note: ExtPay.js doesn't contain malware or track your users in any way. This library only communicates with ExtensionPay.com servers to manage users' paid status.

If you like this library, please star it! ⭐️ It helps us out :)

1. Install

npm install extpay --save

If you're not using a bundler, you can copy the dist/ExtPay.js file into your project (or ExtPay.module.js for ESM / ExtPay.common.js for Common JS).

2. Configure your manifest.json

ExtPay needs the following configuration in your manifest.json (for both manifest v2 and v3):

{
    "permissions": [
      "storage"
    ]
}

ExtPay will not show a scary permission warning when users try to install your extension.

Note: For Firefox, you may have to include "https://extensionpay.com/*" in your extension manifest's "permission" for ExtPay to work properly.

If you have a "content_security_policy" in your manifest or get a Refused to connect to 'https://extensionpay.com...' error, you'll have to add connect-src https://extensionpay.com to your extension's content security policy. <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_security_policy">See Mozilla's documentation for more details</a>.

3. Add ExtPay to background.js (required!)

You need to put ExtPay in your background file, often named something like background.js. If you don't include ExtPay in your background file it won't work correctly. If you're using a bundler you can import 'ExtPay' or require('ExtPay') right in your background.js.

With either Manifest V3 or Manifest V2 you'll need to sign up and register an extension. When you register an extension you'll create an extension id that you'll use when initializing ExtPay. We'll use sample-extension as the extension id in the following examples.

Manifest V3

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

// background.js

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

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

Note about service workers: In the example above extpay will become undefined when accessed in service worker callbacks. To use extpay in service worker callbacks, redeclare it like so:

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

Make sure not to use extpay.startBackground() in callbacks — it should only be called once.

Manifest V2

If you're not using a bundler, add ExtPay.js to manifest.json:

{
    "background": {
        "scripts": ["ExtPay.js", "background.js"]
    }
}

// background.js
const extpay = ExtPay('sample-extension')
extpay.startBackground();

4. Use extpay.getUser() to check a user's paid status

This method makes a network call to get the extension user's paid status and returns a user object.

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

or use await:

async function foo() {
    const user = await extpay.getUser();
    if (user.paid) {
        // ...
    }
}

It is possible for extpay.getUser() to throw an error in case of a network failure. Please consider this possibility in your code e.g. extpay.getUser().then(/* ... */).catch(/* handle error */)

The user object returned from extpay.getUser() has the following properties:

user object properties

| property | description | | --- | --- | | user.paid | true or false. user.paid is meant to be a simple way to tell if the user should have paid features activated. For subscription payments, paid is only true if subscriptionStatus is active. | | user.paidAt | Date() object that the user first paid or null.| | user.email | The user's email if there is one or null.| | user.installedAt | Date() object the user installed the extension. | | user.trialStartedAt | null or Date() object the user confirmed their free trial. | | user.plan | null or the plan the user is on. For example: {unitAmountCents: 1000, currency: 'usd', nickname: null, intervalCount: 1, interval: 'month'}. Unpaid users never have a plan. See extpay.getPlans() elsewhere in this README for more detail. | | subscription only| | | user.subscriptionStatus | One of active, past_due, or canceled. active means the user's subscription is paid-for. past_due means the user's most recent subscription payment has failed (expired card, insufficient funds, etc). canceled means that the user has canceled their subscription and the end of their last paid period has passed. You can read more about how subscriptions work here. | | user.subscriptionCancelAt | null or Date() object that the user's subscription is set to cancel or did cancel at. |

5. Use extpay.openPaymentPage() to let the user pay

Opens a new browser tab where the user can pay to upgrade their status.

extpay.openPaymentPage([planNickname])

The payment page looks like this:

The plan buttons take you to a Stripe Checkout page:

Note: extpay.openPaymentPage() can fail to open the tab if there is a network error. Please consider this possibility in your code.

You can optionally include your planNickname as an argument to extpay.openPaymentPage(planNickname) to directly open the Stripe payment page for that plan. For example: extpay.openPaymentPage('my_plan_nickname'). Plan nicknames can be edited in the ExtensionPay.com extension settings page.

While developing your extension in test mode, you will need to enter your account password in order to proceed to the Stripe Checkout page. This is to prevent fraudulent access to your extension. You can use Stripe's test cards in order to test the payment experience in development.

It is best to open the payment page when the user has a clear idea of what they're paying for.

Depending on how you configure your extension, users that have paid before can log in to activate their paid features on different browsers, profiles, or after uninstalling/reinstalling.

You should turn on as many payment methods in your Stripe settings as possible to maximize your revenue.

Also see our guide for how to create coupon / discount / promotion codes for your extensions.

6. Use extpay.getPlans() to list available payment plans

For example, an extension with a $10 monthly and $99 yearly plan might look like this:

  > await extpay.getPlans();
  [
    {
      unitAmountCents: 1000,
      currency: 'usd',
      nickname: null,
      intervalCount: 'month',
      interval: 1
    },
    {
      unitAmountCents: 9900,
      currency: 'usd',
      nickname: null,
      intervalCount: 'year',
      interval: 1
    }
  ]

The specification for plans looks like this:

  interface Plan {
    unitAmountC