Introducing navigator.mozPay() For Web Payments

What’s wrong with payments on the web? Any website can already host a shopping cart and take credit card payments or something similar. The freedom of today’s web supports many business models. Here’s what’s wrong:

  • Users cannot choose how to pay; they have to select from one of the pre-defined options.
  • In most cases, the user has to type in an actual credit card number on each site. This is like giving someone the keys to your expensive car, letting them drive it around the block in a potentially dangerous neighborhood (the web) and saying please don’t get carjacked!
  • Merchants typically have to manage all this on their own: payment processor setup, costly processing fees, and possibly even PCI compliance.

There are services to mitigate a lot of these complications such as PayPal, Stripe, and others but they aren’t integrated into web devices very well. Mozilla wants to introduce a common web API to make payments easy and secure on web devices yet still as flexible as the checkout button for merchants.

As a first step, Mozilla will introduce navigator.mozPay() in Firefox OS so that web apps can accept payments.

How Does It Work?

navigator.mozPay() is a JavaScript API inspired by but modified for things like multiple payment providers and carrier billing. When a web app invokes navigator.mozPay() in Firefox OS, the device shows a secure window with a concise UI. After authenticating, the user can easily charge the payment to her mobile carrier bill or credit card. When completed, the app delivers the product. Repeat purchases are quick and easy.

In an earlier article I talked about purchasing an app and receiving a receipt. navigator.mozPay() is different in that there is no concept of what product is purchased, it’s just an API to facilitate a payment for a digital good or service, whatever that may be.

The payment starts and finishes in the client but further processing and notifications happen server side. This article briefly explains how it all fits together. For complete, in-depth documentation read the Firefox Marketplace guide to in-app payments.

Integrating With A Payment Provider

Multiple providers will facilitate payments behind the scenes of navigator.mozPay(). For example, the Firefox Marketplace will be able to facilitate payments.

As a developer you will essentially grant permission to each provider that you would like to sell through. In the current design of the API, you do this by asking each provider for an Application Key and an Application Secret so that you can digitally sign payment requests. A signed request prevents unauthorized parties from selling your products and prevents users from tampering with the price, etc.

Initiating A Payment

When the user clicks a Buy button in your web app, you create a JSON Web Token (JWT) with your Application Secret. If you have agreements with multiple providers, you would create a JWT for each provider. Starting a payment looks roughly like this:

document.querySelector('').onclick = function() {
    navigator.mozPay([mozillaJWT, otherJWT, ...]);

Defining A Product

A JWT is a signed JSON object that defines details like the product name and price. Here is an example with some attributes removed for brevity:

  "aud": "",
  "request": {
    "name": "Magical Unicorn",
    "pricePoint": 1,
    "postbackURL": "",
    "chargebackURL": ""

You define prices as price points so that the payment provider can handle currency conversions for you in each region. In this example, pricePoint 1 might be €0.89 or $0.99, etc. Micropayments in small amounts will be supported. Consult the navigator.mozPay() spec for details on how to construct a payment request JWT.

Completing a Payment

To complete the payment, you need to wait for the provider to POST a result to your server’s postbackURL (on success) or chargebackURL (on failure). A more complete example of requesting a purchase in JavaScript would involve waiting for the postback to arrive, like this:

var request = navigator.mozPay([mozillaJWT, otherJWT]);
request.onsuccess = function() {
  // The payment window has closed.
  whenPaymentResultReceived(function() {
    console.log('Success! User has purchased a Magical Unicorn.');

To implement whenPaymentResultReceived() you might open a web socket to your server, wait for the payment result, and verify the incoming JWT signature. The navigator.mozPay() spec has details on how postback and chargeback notifications work.

Try It Out

Payments aren’t fully live yet in the Firefox Marketplace but you can simulate a payment to test out your code. Log into the Firefox Marketplace Developer Hub and generate an Application Key and Application Secret for simulations. With those keys you can add a special parameter to the JWT like this:

  "request": {
    "name": "Magical Unicorn",
    "pricePoint": 1,
    "simulate": {"result": "postback"}

This will show a payment window on Firefox OS but it won’t charge you real money. It will let you test your client side JavaScript code and your server postback handlers to make sure everything is integrated smoothly. When you go live, just remove the simulate attribute. If you’re new to Firefox OS development, check out the Firefox OS Simulator.

If you’re already working on a game or a web app for Firefox OS try thinking about using navigator.mozPay() to offer premium content.

This Would Be Way Easier With A Library

We thought so too! We built libraries for Node.JS and Python to make the server side logic for navigator.mozPay() as easy as possible. Libraries for more languages are on the way. We also are experimenting with removing the server prerequisite entirely.

Current Status

As you can probably tell by the prefix, navigator.mozPay() is an experimental API and might change drastically or become unprefixed without notice. It will process live payments on the first Firefox OS phones and evolve quickly from real world usage.

Mozilla plans to work with other vendors through the W3C to reach consensus on a common API that supports web payments in the best way possible. After shipping in Firefox OS, Mozilla plans to add navigator.mozPay() to Firefox for Android and desktop Firefox.

New Business Models

Advertising has been the primary business model on the web for a long time but users have made it clear that they don’t want to see ads. Mozilla isn’t trying to directly disrupt the ad business but it is trying to fix serious privacy issues relating to ad networks.

What if users explicitly paid for content instead? navigator.mozPay() enables this kind of direct payment model: if something is good on the web, you can pay for it. It already seems to be working well for existing mobile apps. Will mobile ads even generate the same revenue for content producers as they do on desktop? I don’t have answers to these questions but one thing is for certain: the web should support businesses of all kinds and payments should be a first class feature of the web.

Is It Webby?

Mozilla’s main goal with navigator.mozPay() is to give users and merchants choice, security, and an easy to use payments system. The details about how merchants interact with payment providers is not yet specified in the API and that is clearly a gap. The first Firefox OS phones will ship with a whitelist of allowed payment providers which is also not ideal.

In a more webby model, all parties involved in the payment would be fully decentralized so that innovation can occur naturally and unknown payment providers could emerge. Who will be the next M-Pesa? An elegant API would support that. Building a secure decentralized payment API is an ambitious challenge; the solution would need to address these core trust issues:

  • How can customers trust that they will receive the goods after paying?
  • How would customers ensure that their payment credentials are handled securely?
  • How do merchants guarantee that they’ll get paid after delivering goods?

As with anything related to money, there is incentive for fraud every step of the way. BitCoin is a digital currency that solves some of these trust issues with block chains and PaySwarm is a web payment protocol that solves some of these issues with decentralized assets, public keys, etc. Mozilla will be watching PaySwarm as well as other models and hopefully navigator.mozPay() can incorporate some of these concepts eventually.

About kumar303

Kumar hacks on Mozilla web services and tools for various projects, such as those supporting Firefox Add-ons. He hacks on lots of random open source projects too.

More articles by kumar303…


  1. Tim Wright

    Very cool, is this intended strictly for click based purchases, keeping recurring billing on the server? Or do you see this also available for auto billing purposes?

    April 4th, 2013 at 03:18

  2. Oliver

    Hi Guys,

    cool idea, be sure to include Bitcoin payments as an option (possibly using a payment processor like Bitpay)

    April 4th, 2013 at 05:23

    1. Manu Sporny

      Hi Oliver,

      The PaySwarm work (as mentioned at the end of the article) does plan to integrate Bitcoin as well as other alternative currencies. There are a number of regulatory issues to address, but we think they’re surmountable issues.

      April 5th, 2013 at 08:25

  3. Marcin

    Sounds decent. Complicated given the number and variation in payment systems.

    Any Mozilla plans to open its own payment system as an additional revenue stream to fund developers + researchers for this down the line ?

    April 4th, 2013 at 05:53

    1. Manu Sporny

      Marcin, I’m definitely not speaking for Mozilla here, but will be making an open proposal to the Mozilla organization to fund some of their development initiatives by building payment into the browser (and charging a miniscule fee that will go towards more awesome Web development at Mozilla).

      There are many, many, legal hurdles that would need to be overcome to see that happen, but the PaySwarm (and Meritora) work certainly makes this a possibility. We are interested in pursuing that possibility if folks at Mozilla are interested.

      April 5th, 2013 at 08:27

    2. Kumar McMillan

      Marcin, I’m not sure if I understand your question correctly but navigator.mozPay() is intended exactly as a revenue stream for developers, researchers, or whoever wants to sell digital goods, take donations, etc. The goal is to let developers exchange content for money online easier.

      April 5th, 2013 at 10:52

  4. Kumar McMillan

    The first version will just be for click based purchases. You could keep track of recurring schedules on the server and prompt users when they return to the app but in the future we plan to offer proper recurring billing as part of the API.

    April 4th, 2013 at 08:02

  5. Julien

    I suppose there’s a mistake on the meaning of “chargebackURL” .
    Usually a chargeback happens when a user cancels a transaction after it has been billed (the user tells his bank he never made this payment himself, so the bank re-credits user’s account). It’s an asynchronous event that may happen many months after the real payment.
    Do you have any clue on what is really this url meant to be used to?

    April 4th, 2013 at 08:23

    1. Kumar McMillan

      chargeback is a loaded term, yes. In our case it could mean the user asked for a refund or the the charge was reversed or it simply failed in some other way. The app may indeed get notified *in the future* of a chargeback.

      April 4th, 2013 at 15:13

  6. Manu Sporny

    Just a bit more on PaySwarm, which is mentioned at the end of the article as a decentralized payment solution. The first commercial implementation of it launched two days ago, here:

    You can learn more about PaySwarm here:

    April 4th, 2013 at 14:12

  7. cren

    This sounds great, I would love to see an example using Bitcoin.

    April 4th, 2013 at 16:38

    1. Manu Sporny

      cren, in the PaySwarm work, a bitcoin example would just change the currency value, so instead of something like this:


      “amount”: “135.00”,
      “currency”: “USD”


      You would see something like this:


      “amount”: “1.00”,
      “currency”: “BTC”


      We are still working on Bitcoin support in PaySwarm, but it is planned.

      April 5th, 2013 at 08:30

  8. Mike

    Awesome, I hope Bitcoin is incorporated soon!

    April 4th, 2013 at 17:17

  9. Dan

    As bitcoin takes off it will make for amazing payment methods for web browsers. Web browsers could have integrated wallets and if you have remeber password selected payment will be as simple as clicking a button, literally, it couldn’t get simpler.

    April 5th, 2013 at 01:52

    1. Manu Sporny

      Dan, R, while I share your enthusiasm for Bitcoin, and we’re building support for Bitcoin into PaySwarm, there are downsides – namely, no chargebacks.

      This is both a feature and a bug as it makes it highly unlikely that high-value transactions will happen with Bitcoin. There are some cases where you want to use USD and others where you want to use Bitcoin. PaySwarm is currency agnostic, and will support virtual currencies like Bitcoin as well… each has its place and use.

      April 5th, 2013 at 08:32

      1. David Bialer

        I am curious to understand if Bitcoin or Payswarm for that matter is capable of handling micro transactions, like under US$.50, down to $.05 in a cost-effective way. I am looking at solutions for micro-payments, particularly interesting for emerging markets where transactions could be very small. The issue is that payment processing overhead can be very high and exceed the value of the transaction itself. There are a lot of middlemen involved, but Bitcoin seems to have the promise of potentially eliminating middlemen and fraud risk.

        Can Bitcoin be split in micro units and are there any processing fees involved in transactions? It would be an interesting method with PaySwarm.

        April 8th, 2013 at 11:54

        1. Manu Sporny

          Both Bitcoin and PaySwarm are capable of handling microtransactions. Bitcoin is accurate down to 8 decimal places. PaySwarm is more accurate, with accuracy down to 10 decimal places: 0.0000000001. PaySwarm is also currency agnostic, so it can do this sort of microtransaction for any currency. Bitcoin can only do these microtransactions for Bitcoin amounts (so, no support for USD, EUR, JPY, etc.)

          Currently, the first commercial implementation of PaySwarm is Meritora:

          Meritora’s fees are 2% of the transaction amount, with a $0.0002 minimum transaction fee (this means that you can have thousands of tiny, tiny transfers, but the total transaction amount must result in at least $0.0002 of fees to cover the costs of storing the transaction for you).

          The bottom line is that both PaySwarm and Bitcoin can do microtransactions today.

          April 9th, 2013 at 10:13

  10. R

    +1 for bitcoins Moz!!! That is a fantastic idea!

    April 5th, 2013 at 03:51

  11. evan

    The problem with ads is not their visability but rather the beligerent tracking that accompanies them.

    The only reason ads get sacrificed in the privacy war is because the way they are implemented makes them the easiest part to filter.

    April 6th, 2013 at 17:22

  12. Pasi

    This is the point when someone asks, “what if the user has JS disabled?”!

    I’ve been mostly developing webshops for the past 10 years, and this is something that really keeps technology back, as you need to have a separate system for those who have JS disabled for what any reason, because it seems the shop keepers are worried they’d loose sales because of it.

    April 6th, 2013 at 23:34

  13. Marcin


    Actually what I was thinking was that Mozilla could become a payment gateway itself and then use some portion of the fees collected to fund development efforts (whether just for the mozPay initiative or the browser as a whole), thereby reducing the reliance on donations + agreements with Google.

    Not clear whether that conflicts at all with the non-profit status of Mozilla Corp but thought I’d throw it out there.


    April 7th, 2013 at 03:19

    1. Kumar McMillan

      Marcin, yes, Mozilla does intend to support its mission by charging a nominal fee when processing payments. However, we also would like to introduce competition into web payments so that the fees go down for everyone.

      April 7th, 2013 at 23:27

  14. Corn¸

    Guys, what about becoming payment processor it self and ease the charges and handling. PaPal is shit dealing with PayPal is shit too. Google also can sometimes make problems and moneybookers are shit even more. PayZa is scam what we really need is someone who offers easy type of payment processing – directly or what ever … This what you planing is helping what ? to use multiple payment processors and that’s it? Give us something better than that – be a processor your self …

    April 7th, 2013 at 05:28

  15. Fernando Jiménez

    Great article Kumar!

    It is worth mentioning that the Firefox Marketplace itself uses navigator.mozPay() to charge for application purchases requested from Firefox OS devices.

    / Fernando

    April 7th, 2013 at 09:43

  16. Fernando Jiménez


    Mozilla already implemented a payment gateway that will act as a payment provider for navigator.mozPay in the first version of Firefox OS. I don’t know if there will be a fee collected for each payment though.

    Note that this doesn’t mean that there won’t be other possible payment providers.

    / Fernando

    April 7th, 2013 at 09:50

  17. Francisco

    Hi. Just a short question. Is it possible to turn the UI of Firefox into the first one? On the simulator or on the geeksphone.

    If not, is there any way to change the UI manually? I mean changing the CSS of the OS.

    Picture of what I mean:

    April 7th, 2013 at 16:47

    1. Kumar McMillan

      Francisco: Maybe. You’d have to dig pretty deep into the history of Gaia but if you went back as far as that screenshot other things won’t work too well since it was unstable back then.

      April 7th, 2013 at 23:22

  18. Blue Hand

    Great Article McMillan!
    Thanks for such a wonderfull idea!

    April 7th, 2013 at 23:35

  19. David

    What are the non-US payments? Does it deal with VAT, BTW, IVF, state sales tax or other excise taxes? Do I need to adapt accounting software to work with this?

    April 8th, 2013 at 00:53

    1. Kumar McMillan

      As a developer, you will not need to calculate your own tax, they will be pre-calculated per region. The details on that will be announced shortly here:

      April 8th, 2013 at 10:13

  20. Justin Short

    Interesting work! We’re have the opposite of the usual use-case – we want to pay money to consumers, not take it. Our (free) game awards prizes to the best players, no strings attached.

    We’re currently planning to use paypal but getting the prize money into their system has a ~3% charge we’d have to take out of the prizes. Is there any way or any plans to be able to send money using your api? That would be very useful for us.

    For more information about the game:

    April 9th, 2013 at 01:05

    1. Kumar McMillan

      Justin, you may want to check out what Balanced offers:

      April 9th, 2013 at 10:39

      1. Justin Short

        Thanks Kumar! I generally like escrow systems – nice to see someone offering that. If anyone knows of other alternatives I’d appreciate the heads-up!

        We had also been considering BTC, of course, but are not sure if the average consumer is ready for those yet.

        April 9th, 2013 at 18:04

  21. Stephen

    This sounds great for in-app purchases / addons to existing applications. Is there also a mechanism in place (in Firefox Marketplace?) for 1-time up front purchases?

    e.g. If I want to sell my game/app for the ~$1 price tier… is there a way I can set that up in the store?

    April 29th, 2013 at 10:22

Comments are closed for this article.