mozilla

Revision 457129 of subpage C

  • Revision slug: User:Mark_Giffin/subpage_C
  • Revision title: subpage C
  • Revision id: 457129
  • Created:
  • Creator: markg
  • Is current revision? No
  • Comment

Revision Content

[App payments guide]

There are two kinds of payments made by app end users in the Firefox Marketplace: a payment made to purchase an app (a paid app), and a payment made to buy something after the app is installed (an in-app payment). This page covers the flow for building and submitting apps that use both kinds of payments.

This page gives very simple ways to do these things. Keep in mind that there are many other ways to do it.

Building a paid app

Any app can be a paid app. It can be hosted or packaged, and it does not require special permissions. You can create a paid app simply by choosing to make it a paid app when you submit it to the Firefox Marketplace. However there are a few things that we recommend that you do to the app before submitting it. See the sections below.

Add installs_allowed_from

You should add the installs_allowed_from field to the app's manifest. Give it the URL of the Firefox Marketplace like this:

"installs_allowed_from": [ "https://marketplace.firefox.com" ]

This makes it so your app can only be installed from the Firefox Marketplace. You can add the URLs of other stores but this is all you need for now.

Verify the receipt

When an app is sold on the Marketplace, a digital receipt for the sale is created. You should code your app so that it verifies this sales receipt when it runs. This verification is not required but it is recommended. It will help avoid people installing your app without paying for it.

There is a Mozilla-maintained JavaScript helper library called receiptverifier that enables you to verify the receipt with a small amount of code. Include the following receiptverifier libraries in your app:

Then you can add the following code to your app (with text changes to match your app) to verify the receipt:

mozmarket.receipts.Prompter({
  storeURL: "https://marketplace.firefox.com/app/your-app",
  supportHTML: '<a href="mailto:you@yourapp.com">email you@yourapp.com</a>',
  verify: true
});

If you need to know more, here are some references on verifying receipts.

Submitting a Paid App to the Marketplace [INCOMPLETE]

Submitting an App to the Firefox Marketplace [link]
General instructions on submitting an app.
 
Marketplace Submission Video [link]
This video is a little out of date, but it shows the basic process of app submission. Two things that are missing for a paid app are choosing the Paid option and choosing a price.

Building an app with in-app payments

The following steps give the general flow for building an app that uses in-app payments.

Decide on a packaging model (packaged vs. hosted)

Before learning about payments, it will help to decide whether your app should be packaged or hosted. And if you need a packaged app, it will need to follow a Content Security Policy (CSP). See the references below for information about these things.

Packaged apps [link]
Explains the difference between a packaged app and a hosted app. Talks a little about the CSP that is required when you use a packaged app.

Content Security Policy [link]

Explains CSP implications.Get an API key.

In-app payment keys

Marketplace developer page where you get a development key to use while you are developing the app. Explains that you get an official production key when you submit the app.
 
Add a JWT request from the client to the server.
In-app payments
Information useful in the steps below.
 
Introducing navigator.mozPay() for Web Payments
High level overview of the process.
 
window.navigator.mozPay
The function used for in-app payments.
 
Web payment
Background information on in-app payments. The diagram at the bottom might be useful, although there are Gecko implementation details that you don't need. Also lists some helpful libraries regarding JWT near the bottom.
 
Add a JWT response from the server to the client.
In-app payments
Mentions the simulate field for development and testing.
 
JSON Web Token
A very technical specification useful for developers who don't already have a JWT library for their backend/server language.
 
Add a window.navigator.mozPay() call from the client to the Marketplace payment service.
Add a postback handler on the server.
In-app payments
Mentions how a postback must be responded to to complete the monetary transaction.
 
Web payment
Mentions that in production the postback and chargeback URLs must be over HTTPS, so you are going to need an SSL certificate. You should be using encrypted traffic protocols like HTTPS and WSS for payments.
 
Release the content to the client.

Submit an app with in-app payments

Remove the simulate field from the JWT.
Mentioned in In-app payments.
 
Use HTTPS for postback and chargeback URLs.
Mentioned in Web payment.
 
Submit the app to the Firefox Marketplace, choosing the In-app option.
Get a new API secret.
See the In-app payment keys page.
 
Set up a Bango payment account in the developer's section of the Marketplace.

Getting more help

IRC on irc.mozilla.org
#b2gpay
#openwebapps
Email list
dev-webapps
Bugzilla
Product = marketplace
Component = payments/refunds
 
 
 

Revision Source

<h2 id=".5BApp_payments_guide.5D">[App payments guide]</h2>
<p>There are two kinds of payments made by app end users in the Firefox Marketplace: a payment made to purchase an app (a paid app), and a payment made to buy something after the app is installed (an in-app payment). This page covers the flow for building and submitting apps that use both kinds of payments.</p>
<p>This page gives very simple ways to do these things. Keep in mind that there are many other ways to do it.</p>
<h2 id="Building_a_paid_app">Building a paid app</h2>
<div>
  <p><span style="line-height: 1.572;">Any app can be a paid app. It can be hosted or packaged, and it does not require special permissions. You can create a paid app simply by choosing to make it a paid app when you submit it to the Firefox Marketplace. However there are a few things that we recommend that you do to the app before submitting it. See the sections below.</span></p>
  <h3 id="Add_installs_allowed_from">Add <code>installs_allowed_from</code></h3>
  <p><span style="line-height: 1.572;">You should add the <code>installs_allowed_from</code> field to the app's manifest. Give it the URL of the Firefox Marketplace like this:</span></p>
  <pre>
<span class="brush: js" style="line-height: 1.572;">"installs_allowed_from": [ "https://marketplace.firefox.com" ]</span></pre>
</div>
<p>This makes it so your app can only be installed from the Firefox Marketplace. You can add the URLs of other stores but this is all you need for now.</p>
<h3 id="Verify_the_receipt"><span style="line-height: 1.572;">Verify the receipt</span></h3>
<p>When an app is sold on the Marketplace, a digital receipt for the sale is created. You should code your app so that it verifies this sales receipt when it runs. This verification is not required but it is recommended. It will help avoid people installing your app without paying for it.</p>
<p><span style="line-height: 1.572;">There is a Mozilla-maintained JavaScript helper library called</span><span style="line-height: 1.572;">&nbsp;</span><a href="https://github.com/mozilla/receiptverifier" style="line-height: 1.572;" title="https://github.com/mozilla/receiptverifier">receiptverifier</a><span style="line-height: 1.572;">&nbsp;</span><span style="line-height: 1.572;">that enables you to verify the receipt with a small amount of code.&nbsp;</span><span style="line-height: 1.572;">Include the following receiptverifier libraries in your app:</span></p>
<ul>
  <li><a href="https://github.com/mozilla/receiptverifier/blob/master/receiptverifier.js" style="line-height: 1.572;">receiptverifier.js</a></li>
  <li><a href="https://github.com/mozilla/receiptverifier/blob/master/receiptverifier-ui.js">receiptverifier-ui.js</a></li>
</ul>
<p>Then you can add the following code to your app (with text changes to match your app) to verify the receipt:</p>
<pre class="brush: js">
mozmarket.receipts.Prompter({
  storeURL: "https://marketplace.firefox.com/app/your-app",
  supportHTML: '&lt;a href="mailto:you@yourapp.com"&gt;email you@yourapp.com&lt;/a&gt;',
  verify: true
});</pre>
<h3 id="Paid_app_references"><span style="line-height: 1.572;">Paid app references</span></h3>
<p><span style="line-height: 1.572;">If you need to know more, here are some references on verifying receipts.</span></p>
<ul>
  <li><a href="https://hacks.mozilla.org/2013/02/building-a-paid-app-for-firefox-os" title="https://hacks.mozilla.org/2013/02/building-a-paid-app-for-firefox-os">Building a Paid App for Firefox OS</a> - High-level overview of paid apps and has useful links for more information.</li>
  <li>
    <p><a href="/en-US/docs/Web/Apps/Publishing/Marketplace_Payments" title="/en-US/docs/Web/Apps/Publishing/Marketplace_Payments">Marketplace Payments</a> -&nbsp;<span style="line-height: 1.572;">Some information about paid apps. Also has in-app payment information.</span></p>
  </li>
  <li>
    <p><span style="line-height: 1.572;"><a href="/en-US/docs/Web/Apps/Publishing/Validating_a_receipt" title="/en-US/docs/Web/Apps/Publishing/Validating_a_receipt"><span style="line-height: 1.572;">Validating a Receipt</span></a><span style="line-height: 1.572;">&nbsp;-&nbsp;Implementation details about verifying receipts.</span></span></p>
  </li>
  <li>
    <p><span style="line-height: 1.572;"><span style="line-height: 1.572;"><a href="https://github.com/mozilla/receiptverifier" title="https://github.com/mozilla/receiptverifier">receiptverifier</a> Library<span style="line-height: 1.572;">&nbsp;- The library used above.&nbsp;Has documentation on using it and includes an example of using it server side.</span></span></span></p>
  </li>
  <li>
    <p><span style="line-height: 1.572;"><span style="line-height: 1.572;"><span style="line-height: 1.572;"><a href="https://wiki.mozilla.org/Apps/WebApplicationReceipt" title="https://wiki.mozilla.org/Apps/WebApplicationReceipt">Web Application Receipt</a><span style="line-height: 1.572;">&nbsp;-&nbsp;Detailed information on what a receipt is.</span></span></span></span></p>
  </li>
</ul>
<h2 id="Submitting_a_Paid_App_to_the_Marketplace_.5BINCOMPLETE.5D">Submitting a Paid App to the Marketplace [INCOMPLETE]</h2>
<div>
  Submitting an App to the Firefox Marketplace<span style="line-height: 1.572;">&nbsp;[link]</span></div>
<div>
  General instructions on submitting an app.</div>
<div>
  &nbsp;</div>
<div>
  Marketplace Submission Video<span style="line-height: 1.572;">&nbsp;[link]</span></div>
<div>
  This video is a little out of date, but it shows the basic process of app submission. Two things that are missing for a paid app are choosing the Paid option and choosing a price.</div>
<h2 id="Building_an_app_with_in-app_payments">Building an app with in-app payments</h2>
<p>The following steps give the general flow for building an app that uses in-app payments.</p>
<h3 id="Decide_on_a_packaging_model_(packaged_vs._hosted)"><span style="line-height: 1.572;">Decide on a packaging model (packaged vs. hosted)</span></h3>
<p>Before learning about payments, it will help to decide whether your app should be packaged or hosted. And if you need a packaged app, it will need to follow a Content Security Policy (CSP). See the references below for information about these things.</p>
<div>
  <span style="line-height: 1.572;">Packaged apps [link]</span></div>
<div>
  Explains the difference between a packaged app and a hosted app. Talks a little about the CSP that is required when you use a packaged app.</div>
<p>Content Security&nbsp;Policy [link]</p>
<p><span style="line-height: 1.572;">Explains CSP implications.</span><span style="line-height: 1.572;">Get an API key.</span></p>
<p><span style="line-height: 1.572;">In-app payment keys</span></p>
<div>
  Marketplace developer page where you get a development key to use while you are developing the app. Explains that you get an official production key when you submit the app.</div>
<div>
  &nbsp;</div>
<div>
  Add a JWT request from the client to the server.</div>
<div>
  In-app payments</div>
<div>
  Information useful in the steps below.</div>
<div>
  &nbsp;</div>
<div>
  Introducing navigator.mozPay() for Web Payments</div>
<div>
  High level overview of the process.</div>
<div>
  &nbsp;</div>
<div>
  window.navigator.mozPay</div>
<div>
  The function used for in-app payments.</div>
<div>
  &nbsp;</div>
<div>
  Web payment</div>
<div>
  Background information on in-app payments. The diagram at the bottom might be useful, although there are Gecko implementation details that you don't need. Also lists some helpful libraries regarding JWT near the bottom.</div>
<div>
  &nbsp;</div>
<div>
  Add a JWT response from the server to the client.</div>
<div>
  In-app payments</div>
<div>
  Mentions the simulate field for development and testing.</div>
<div>
  &nbsp;</div>
<div>
  JSON Web Token</div>
<div>
  A very technical specification useful for developers who don't already have a JWT library for their backend/server language.</div>
<div>
  &nbsp;</div>
<div>
  Add a window.navigator.mozPay() call from the client to the Marketplace payment service.</div>
<div>
  Add a postback handler on the server.</div>
<div>
  In-app payments</div>
<div>
  Mentions how a postback must be responded to to complete the monetary transaction.</div>
<div>
  &nbsp;</div>
<div>
  Web payment</div>
<div>
  Mentions that in production the postback and chargeback URLs must be over HTTPS, so you are going to need an SSL certificate. You should be using encrypted traffic protocols like HTTPS and WSS for payments.</div>
<div>
  &nbsp;</div>
<div>
  Release the content to the client.</div>
<h3 id="Submit_an_app_with_in-app_payments">Submit an app with in-app payments</h3>
<div>
  Remove the simulate field from the JWT.</div>
<div>
  Mentioned in In-app payments.</div>
<div>
  &nbsp;</div>
<div>
  Use HTTPS for postback and chargeback URLs.</div>
<div>
  Mentioned in Web payment.</div>
<div>
  &nbsp;</div>
<div>
  Submit the app to the Firefox Marketplace, choosing the In-app option.</div>
<div>
  Get a new API secret.</div>
<div>
  See the In-app payment keys page.</div>
<div>
  &nbsp;</div>
<div>
  Set up a Bango payment account in the developer's section of the Marketplace.</div>
<h3 id="Getting_more_help">Getting more help</h3>
<div>
  IRC on irc.mozilla.org</div>
<div>
  #b2gpay</div>
<div>
  #openwebapps</div>
<div>
  Email list</div>
<div>
  dev-webapps</div>
<div>
  Bugzilla</div>
<div>
  Product = marketplace</div>
<div>
  Component = payments/refunds</div>
<div>
  &nbsp;</div>
<div>
  &nbsp;</div>
<div>
  &nbsp;</div>
Revert to this revision