A while ago Mozilla announced navigator.mozPay() for accepting payments on Firefox OS. This was our first step toward helping developers do commerce on the web. It solved the problem of processing payments but what about the rest? Today we’re announcing an early peek at fxpay, a library for the rest of what you need as a developer to sell digital products in your app. This small JavaScript library (11kB minified) gives you some nice additional features on top of payment processing:

• Work with a catalog of in-app products without hosting your own server
• Securely verify each payment in one simple JavaScript callback
• Restore previous purchases from receipts

The mozPay() API is great if you need to integrate with an existing system but building a product catalog from scratch is a lot of work. If you have an idea for adding revenue to your app, why not quickly toss in some products and see what sells?

The fxpay library is designed to get you selling as quickly as possible. Because it interacts with the Firefox Marketplace API you don’t need to manage code on your own server — you enter product details on Firefox Marketplace and call some JavaScript functions in your app to sell them.

First: A Warning

fxpay is in an early experimental state. We’re looking for your help to make it a concise, intuitive library which means the API might change rapidly. There’s a section below for details about how to get involved.

Offer Some Products For Sale

After running bower install fxpay (installation details), show some products for sale within your app using getProducts():

// First, let's test with some fake products.
fxpay.configure({fakeProducts: true});

fxpay.getProducts(function(error, products) {
  if (error) {
    console.error(error);
  } else {
    products.forEach(function(product) {
      addBuyButtonForProduct(product);
    });
  }
});

The code here would add a buy button for each product so that tapping the button would start a purchase. Here’s a simplistic example:

function addBuyButtonForProduct(product) {
  var button = document.createElement('button');
  button.textContent = 'Buy ' + product.name;
  button.addEventListener('click', function () {

    fxpay.purchase(product.productId,
                   function(error, product) {
      if (error) {
        console.error(error);
      } else {
        console.log(product.name + ' bought!');
      }
    });

  });
  document.body.appendChild(button);
}

That’s it. The call to fxpay.purchase() guides the user through payment via mozPay() and verifies the result on the Firefox Marketplace server. If you receive the callback without an error that means the purchase was verified and funds will be transferred to your account upon completion. It is safe to deliver the product.

Try It Out

Install an app on the Firefox OS Simulator using the App Manager and tap your custom buy button. Since this is a test with fake products, you’ll see a payment simulation screen. Tap Continue and your purchase callback will fire, allowing you to get your product delivery code working.

Restoring Purchases

When a user completes a purchase, a portable receipt is installed on their device behind the scenes. This is a cryptographically signed JSON object that proves ownership of the product. Each time the user returns to your application, you’ll want to check for any receipts so you can restore their purchased products. The fxpay library does the validation for you but you have to define a callback for when each product is restored like this:

fxpay.init({
  onerror: function(error) {
    console.error('init error:', error);
  },
  onrestore: function(error, product) {
    if (error) {
      console.error('onrestore error:', error);
    } else {
      console.log(product.name + ' restored');
    }
  }
});

Just like the purchase callback, if you don’t get an error it means the receipt is valid; the user owns the product so you should make it available. You probably only need to run init() once when your app starts up.

Publishing Your Application

Once you get everything working with fake products, the next step is to submit your app to the Firefox Marketplace developer hub so users can install it. The submission process is detailed in the documentation; it includes entering bank account details to receive payouts and submitting real names and prices of the products you wish to sell.

Once all of your products are in place and your app has been approved, set {fakeProducts: false} and the same code you see here will begin to work with real products. The getProducts() function will use your app’s origin to retrieve the configured products.

Example App

The fxpay library ships with an example app that you can install from the App Manager and play around with.

Get Involved

Do you have an idea for an app with in-app payments? Try it out. We’re announcing an early version of fxpay so we can make it work well for you, the developer. If something breaks or just feels awkward or if you have an idea to make the library better, get in touch!

• Submit an idea using our user voice forum
• Start a discussion thread on dev-marketplace
• File a bug
• Submit a pull request to the frontend script or the backend API

Going Further

The Payments team at Mozilla is small (but mighty!). This release has a lot of missing features but we wanted to start getting early feedback. Here are a few ideas for features we’d like to add next:

Support More App Types

Right now, fxpay is limited to privileged packaged apps on mobile only. See all prerequisites. We’re working to open up access to other app types such as hosted apps and desktop apps.

Receipt Recovery

If a user loses their device or deletes the app they will lose their in-app purchase receipts. Those receipts are backed up on the Marketplace server but users don’t have an interface to reinstall them yet. We’re trying to figure out a way to do that in bug 1045228.

Exact Product Prices

Price points and currencies vary by mobile network but non-certified apps don’t have a reliable way to detect users’ networks. Currently you can’t display prices next to your custom buy buttons. We’d like to offer some solutions for this even if it’s just a manual currency selector. See bug 1063758.

Product Assets

This first release of fxpay is best suited for local content such as unlocking a level in a game. If an app were to distribute remote content such as a MP3 file as a ring tone, there would be no way to securely protect the contents of that file. We’ll be considering how to add support for this in bug 1063059.

We’re planning lots of other stuff too!