• Skip to main content
  • Select language
  • Skip to search
MDN Web Docs
  • Technologies
    • HTML
    • CSS
    • JavaScript
    • Graphics
    • HTTP
    • APIs / DOM
    • WebExtensions
    • MathML
  • References & Guides
    • Learn web development
    • Tutorials
    • References
    • Developer Guides
    • Accessibility
    • Game development
    • ...more docs
Archive of obsolete content
  1. MDN
  2. Archive of obsolete content
  3. Marketplace
  4. Monetization
  5. Validating a receipt

Validating a receipt

In This Article
  1. When to validate a receipt
  2. How to validate a receipt
  3. Receipt contents
  4. What receipts you should accept
  5. Test receipts
  6. Receipt verification
  7. Combating app piracy
  8. Receipt fields

Marketplace feature removal
The functionality described on this page no longer works — Firefox Marketplace has discontinued support for Android, Desktop, Tablets, and payments (and other related functionality). For more information, read the Future of Marketplace FAQ.

If you have a paid app, you should check that a user has a valid receipt. If you do not check, someone can buy the app, get an immediate refund, and then have the app for free. Or someone can simply install the app by referencing the manifest file directly from your site. This article goes through the code and workflow needed to build in your own receipt validation.

A receipt is proof that an app buyer has purchased your app. A receipt encodes an affirmation by a payment processor that a particular user has completed a transaction to acquire a particular digital product. The receipt is sent to the user's machine after the user has paid for an app on the Firefox Marketplace. The receipt is placed on the user's machine using the second argument to the mozApps.install() method. The Firefox Marketplace calls install() for your app using the receipt.

When to validate a receipt

You have to decide when the app will validate the receipt. A usual time to validate is when the user starts the app. If it's a long-running app, you might want to validate on a regular schedule. An app that streams video, for example, might check the receipt every 20 minutes.

Note that if the user is offline, the app will not be able to validate the receipt. What the app does in this situation is up to you. To avoid some user annoyance you might want to be lax on enforcing the receipt checking (let's say the user is temporarily in a tunnel), and just keep trying until the user is online again.

How to validate a receipt

The simplest way to validate a receipt is to use the Firefox Marketplace validation service. If your app is HTML-only, where the server doesn't do anything but serve static files, you can use the fxpay.validateAppReceipt() method of Mozilla's fxpay JavaScript library.

Receipt contents

The receipt used by an Open Web app is a portable, verifiable proof of purchase token. It is a digitally-signed JSON data structure called a JSON Web Token (JWT). This format is universally readable by clients and servers. There are JWT libraries available for many programming languages.

What receipts you should accept

The receipt is proof of payment, but it is up to the app developer to decide what kind of receipts you would like to accept. Here's a list of the things you should check:

  • The receipt is from a store you are selling the app from. Check that the iss field is in your whitelist.
  • The receipt is for your app. For hosted apps, check that the product URL field is correct. For packaged apps, check that the product storeData is correct until bug 867265 is resolved. The value of storeData is not known until a receipt is issued, but will remain constant from then on.
  • The verification URL is at a domain or subdomain of the store. Check that the verify URL is a subdomain of the iss field.
  • The receipt is for a purchase and not a test receipt. Check the typ field.

The fxpay app receipt validator will do these checks for you automatically.

Test receipts

During development the Firefox Marketplace can issue test receipts so that the payment lifecycle can be completely tested. Use this utility page on the Firefox Developer Hub to generate receipts for testing. These look like normal receipts except they have a typ of test-receipt. The app should accept these receipts during development and then not accept them once on sale. Doing so would allow anyone to bypass the sales process and use a test receipt in your app.

By default the fxpay app receipt validator does not allow test-receipts.

Receipt verification

Without using a JWT library, you can find the URL for the validation service in the verify field in the receipt, and then send the receipt to the validation service. Each app has a different URL to the Firefox Marketplace validation service.

The code sample below will show the verify URL in the receipt. The code is set up to be used in the Firefox web console developer tool.

var request = navigator.mozApps.getSelf();
request.onsuccess = function() {
  // Get the app's receipt and decode it
  console.log(atob(request.result.receipts[0].split('~')[1].split('.')[1])); 
};

To get the verify URL, this sample does the following things:

  • It saves the return from mozApps.getSelf() — a reference to the current app — in a request variable.
  • If the request is successful, the app's first receipt is retrieved, and the value fed in from JWT is split to get the actual part that contains the receipt.
  • It decodes the Base64-encoded receipt using the JavaScript Window.atob function.

The following is a pretty-printed example of the result of the code above. It is a full receipt, minus the JWT parts.

{
  "product": {
    "url": "http://example.com",
    "storedata": "id=111111"
  },
  "iss": "https://marketplace.mozilla.org",
  "verify": "https://receiptcheck.marketplace.mozilla.org/verify/111111", // The verify URL
  "detail": "https://marketplace.mozilla.org/en-US/purchases/111111",
  "reissue": "https://marketplace.mozilla.org/en-US/app/example/purchase/reissue",
  "user": {
    "type": "directed-identifier",
    "value": "1234-abcd99ef-a123-456b-bbbb-cccc11112222"
  },
  "exp": 1353028900,
  "iat": 1337304100,
  "typ": "purchase-receipt",
  "nbf": 1337304100
}

Once you get the verify URL, use the POST method to send the full JWT in the body of a message. The validation service response is described above. The following snippet would get the full JWT of the app's first receipt in the sample above.

request.result.receipts[0]

Note that the cryptographic aspects of a JWT are not dealt with in the code above. If you verify the receipt with the Marketplace it will check the cryptographic signature itself.

Note: You can find another, more expansive example of receipt verification in Kumar McMillan's Private Yacht example.

Combating app piracy

Even if you validate receipts for your paid app, it can be pirated if someone passes around the valid receipt for others to use. The receipt validation methods given above do not prevent this.

If you want a better defense against piracy, you might want to set up a proxy server that will be an intermediary between the app and the Firefox Marketplace. The proxy server can check the receipts, IP addresses and other things to restrict widespread usage of valid receipts. The server might do something like notice if the same receipt was coming from different IP addresses and take appropriate action.

This Python code is an in-progress project that could give you some ideas for a proxy server. Django Receipts is a test proxy that will validate receipts. You shouldn't use this as a production proxy but you can learn from it as a test. Here is more information on verifying receipts yourself.

Receipt fields

A receipt contains the following fields:

typ
A string identifying the type of receipt. It must be one of:
  • purchase-receipt - A receipt issued when a transaction is completed. This type of receipt should be accepted by the app at all times.
  • developer-receipt - A receipt issued to the developer of the app. Usually they will be issued by the store for the use of the developer. This receipt may have a short expiry.
  • reveiwer-receipt - A receipt issued to the reviewer of the app. Usually they will be issued by the store for reviewers of the app. This receipt only needs to be accepted during the review period. This receipt may have a short expiry
  • test-receipt - A receipt issued to test the app during development. This receipt SHOULD NOT be accepted, except during development. This receipt may have a short expiry.
product
JSON object identifying the product that the receipt covers and any store-specific data. It has the following fields:
  • url - URL representing the root of a domain, without a trailing slash (for example, "https://someapp.com"). This is conventionally defined to represent "a web application". URLs rooted further inside the site are conventionally defined to represent "in-application purchases", and can use whatever path scheme is convenient to the developer and issuer of the receipt.
  • storedata - A string that uniquely identifies this app for the verifier of the receipt.
user
JSON object containing a user ID for the user who made the purchase. It has the following fields:
  • type - A string with the value "directed-identifier".
  • value - A string that is a unique ID for the user. A given user will show up as a different user ID for each app purchased.
iss
Domain for the store that issued the receipt.
nbf
"Not-before" timestamp indicating when the purchase was completed. The timestamp is the number of seconds from 1970-01-01T00:00:00Z in UTC, RFC 3339.
iat
"Issued-at" timestamp indicating when the receipt was issued. Same timestamp format as nbf. You can use this value to determine the age of the receipt.
exp
(optional) Expiry timestamp indicating when the receipt will expire. Same timestamp format as nbf.
detail
(optional) URL that contains additional human- or machine-readable detail about the purchase. If a transaction log or refund capability is provided for the purchase, it is expected that this page will contain those functions.
verify
(optional) URL that can be used by an authenticated application to verify a receipt. Note that the Firefox Marketplace always provides this field for an app. If you are going to create your own app marketplace, you might not use this field.
reissue
(optional) URL that can be used to re-issue a new receipt.

Document Tags and Contributors

Tags: 
  • Apps
  • Firefox OS
  • Marketplace
  • Receipts
  • Web Payment
 Contributors to this page: chrisdavidmills, kumar303, markg, kohei.yoshino, andymckay, Sheppy, ianbicking, jswisher
 Last updated by: chrisdavidmills, Mar 29, 2016, 2:33:27 AM

  1. .htaccess ( hypertext access )
  2. <input> archive
  3. Add-ons
    1. Add-ons
    2. Firefox addons developer guide
    3. Interaction between privileged and non-privileged pages
    4. Tabbed browser
    5. bookmarks.export()
    6. bookmarks.import()
  4. Adding preferences to an extension
  5. An Interview With Douglas Bowman of Wired News
  6. Apps
    1. Apps
    2. App Development API Reference
    3. Designing Open Web Apps
    4. Graphics and UX
    5. Open web app architecture
    6. Tools and frameworks
    7. Validating web apps with the App Validator
  7. Archived Mozilla and build documentation
    1. Archived Mozilla and build documentation
    2. ActiveX Control for Hosting Netscape Plug-ins in IE
    3. Archived SpiderMonkey docs
    4. Autodial for Windows NT
    5. Automated testing tips and tricks
    6. Automatic Mozilla Configurator
    7. Automatically Handle Failed Asserts in Debug Builds
    8. BlackConnect
    9. Blackwood
    10. Bonsai
    11. Bookmark Keywords
    12. Building TransforMiiX standalone
    13. Chromeless
    14. Creating a Firefox sidebar extension
    15. Creating a Microsummary
    16. Creating a Mozilla Extension
    17. Creating a Release Tag
    18. Creating a Skin for Firefox/Getting Started
    19. Creating a Skin for Mozilla
    20. Creating a Skin for SeaMonkey 2.x
    21. Creating a hybrid CD
    22. Creating regular expressions for a microsummary generator
    23. DTrace
    24. Dehydra
    25. Developing New Mozilla Features
    26. Devmo 1.0 Launch Roadmap
    27. Download Manager improvements in Firefox 3
    28. Download Manager preferences
    29. Drag and Drop
    30. Embedding FAQ
    31. Embedding Mozilla in a Java Application using JavaXPCOM
    32. Error Console
    33. Exception logging in JavaScript
    34. Existing Content
    35. Extension Frequently Asked Questions
    36. Fighting Junk Mail with Netscape 7.1
    37. Firefox Sync
    38. Force RTL
    39. GRE
    40. Gecko Coding Help Wanted
    41. HTTP Class Overview
    42. Hacking wiki
    43. Help Viewer
    44. Helper Apps (and a bit of Save As)
    45. Hidden prefs
    46. How to Write and Land Nanojit Patches
    47. Introducing the Audio API extension
    48. Java in Firefox Extensions
    49. JavaScript crypto
    50. Jetpack
    51. Litmus tests
    52. Makefile.mozextension.2
    53. Microsummary topics
    54. Migrate apps from Internet Explorer to Mozilla
    55. Monitoring downloads
    56. Mozilla Application Framework
    57. Mozilla Crypto FAQ
    58. Mozilla Modules and Module Ownership
    59. Mozprocess
    60. Mozprofile
    61. Mozrunner
    62. Nanojit
    63. New Skin Notes
    64. Persona
    65. Plug-n-Hack
    66. Plugin Architecture
    67. Porting NSPR to Unix Platforms
    68. Priority Content
    69. Prism
    70. Proxy UI
    71. Remote XUL
    72. SXSW 2007 presentations
    73. Space Manager Detailed Design
    74. Space Manager High Level Design
    75. Standalone XPCOM
    76. Stress testing
    77. Structure of an installable bundle
    78. Supporting private browsing mode
    79. Table Cellmap
    80. Table Cellmap - Border Collapse
    81. Table Layout Regression Tests
    82. Table Layout Strategy
    83. Tamarin
    84. The Download Manager schema
    85. The life of an HTML HTTP request
    86. The new nsString class implementation (1999)
    87. TraceVis
    88. Treehydra
    89. URIScheme
    90. URIs and URLs
    91. Using Monotone With Mozilla CVS
    92. Using SVK With Mozilla CVS
    93. Using addresses of stack variables with NSPR threads on win16
    94. Venkman
    95. Video presentations
    96. Why Embed Gecko
    97. XML in Mozilla
    98. XPInstall
    99. XPJS Components Proposal
    100. XRE
    101. XTech 2005 Presentations
    102. XTech 2006 Presentations
    103. XUL Explorer
    104. XULRunner
    105. ant script to assemble an extension
    106. calICalendarView
    107. calICalendarViewController
    108. calIFileType
    109. xbDesignMode.js
  8. Archived open Web documentation
    1. Archived open Web documentation
    2. Browser Detection and Cross Browser Support
    3. Browser Feature Detection
    4. Displaying notifications (deprecated)
    5. E4X
    6. E4X Tutorial
    7. LiveConnect
    8. MSX Emulator (jsMSX)
    9. Old Proxy API
    10. Properly Using CSS and JavaScript in XHTML Documents
    11. Reference
    12. Scope Cheatsheet
    13. Server-Side JavaScript
    14. Sharp variables in JavaScript
    15. Standards-Compliant Authoring Tools
    16. Using JavaScript Generators in Firefox
    17. Window.importDialog()
    18. Writing JavaScript for XHTML
    19. XForms
    20. background-size
    21. forEach
  9. B2G OS
    1. B2G OS
    2. Automated Testing of B2G OS
    3. B2G OS APIs
    4. B2G OS add-ons
    5. B2G OS architecture
    6. B2G OS build prerequisites
    7. B2G OS phone guide
    8. Building B2G OS
    9. Building and installing B2G OS
    10. Building the B2G OS Simulator
    11. Choosing how to run Gaia or B2G
    12. Customization with the .userconfig file
    13. Debugging on Firefox OS
    14. Developer Mode
    15. Developing Firefox OS
    16. Firefox OS Simulator
    17. Firefox OS apps
    18. Firefox OS board guide
    19. Firefox OS developer release notes
    20. Firefox OS security
    21. Firefox OS usage tips
    22. Gaia
    23. Installing B2G OS on a mobile device
    24. Introduction to Firefox OS
    25. Mulet
    26. Open web apps quickstart
    27. Pandaboard
    28. PasscodeHelper Internals
    29. Porting B2G OS
    30. Preparing for your first B2G build
    31. Resources
    32. Running tests on Firefox OS: A guide for developers
    33. The B2G OS platform
    34. Troubleshooting B2G OS
    35. Using the App Manager
    36. Using the B2G emulators
    37. Web Bluetooth API (Firefox OS)
    38. Web Telephony API
    39. Web applications
  10. Beginner tutorials
    1. Beginner tutorials
    2. Creating reusable content with CSS and XBL
    3. Underscores in class and ID Names
    4. XML data
    5. XUL user interfaces
  11. Case Sensitivity in class and id Names
  12. Creating a dynamic status bar extension
  13. Creating a status bar extension
  14. Gecko Compatibility Handbook
  15. Getting the page URL in NPAPI plugin
  16. Index
  17. Inner-browsing extending the browser navigation paradigm
  18. Install.js
  19. JXON
  20. List of Former Mozilla-Based Applications
  21. List of Mozilla-Based Applications
  22. Localizing an extension
  23. MDN
    1. MDN
    2. Content kits
  24. MDN "meta-documentation" archive
    1. MDN "meta-documentation" archive
    2. Article page layout guide
    3. Blog posts to integrate into documentation
    4. Current events
    5. Custom CSS classes for MDN
    6. Design Document
    7. DevEdge
    8. Developer documentation process
    9. Disambiguation
    10. Documentation Wishlist
    11. Documentation planning and tracking
    12. Editing MDN pages
    13. Examples
    14. Existing Content/DOM in Mozilla
    15. External Redirects
    16. Finding the right place to document bugs
    17. Getting started as a new MDN contributor
    18. Landing page layout guide
    19. MDN content on WebPlatform.org
    20. MDN page layout guide
    21. MDN subproject list
    22. Needs Redirect
    23. Page types
    24. RecRoom documentation plan
    25. Remove in-content iframes
    26. Team status board
    27. Trello
    28. Using the Mozilla Developer Center
    29. Welcome to the Mozilla Developer Network
    30. Writing chrome code documentation plan
    31. Writing content
  25. MMgc
  26. Makefile - .mk files
  27. Marketplace
    1. Marketplace
    2. API
    3. Monetization
    4. Options
    5. Publishing
  28. Mozilla release FAQ
  29. Newsgroup summaries
    1. Newsgroup summaries
    2. Format
    3. Mozilla.dev.apps.firefox-2006-09-29
    4. Mozilla.dev.apps.firefox-2006-10-06
    5. mozilla-dev-accessibility
    6. mozilla-dev-apps-calendar
    7. mozilla-dev-apps-firefox
    8. mozilla-dev-apps-thunderbird
    9. mozilla-dev-builds
    10. mozilla-dev-embedding
    11. mozilla-dev-extensions
    12. mozilla-dev-i18n
    13. mozilla-dev-l10n
    14. mozilla-dev-planning
    15. mozilla-dev-platform
    16. mozilla-dev-quality
    17. mozilla-dev-security
    18. mozilla-dev-tech-js-engine
    19. mozilla-dev-tech-layout
    20. mozilla-dev-tech-xpcom
    21. mozilla-dev-tech-xul
    22. mozilla.dev.apps.calendar
    23. mozilla.dev.tech.js-engine
  30. Obsolete: XPCOM-based scripting for NPAPI plugins
  31. Plugins
    1. Plugins
    2. Adobe Flash
    3. External resources for plugin creation
    4. Logging Multi-Process Plugins
    5. Monitoring plugins
    6. Multi-process plugin architecture
    7. NPAPI plugin developer guide
    8. NPAPI plugin reference
    9. Samples and Test Cases
    10. Shipping a plugin as a Toolkit bundle
    11. Supporting private browsing in plugins
    12. The First Install Problem
    13. Writing a plugin for Mac OS X
    14. XEmbed Extension for Mozilla Plugins
  32. SAX
  33. Security
    1. Security
    2. Digital Signatures
    3. Encryption and Decryption
    4. Introduction to Public-Key Cryptography
    5. Introduction to SSL
    6. NSPR Release Engineering Guide
    7. SSL and TLS
  34. Solaris 10 Build Prerequisites
  35. Sunbird Theme Tutorial
  36. Table Reflow Internals
  37. Tamarin Tracing Build Documentation
  38. The Basics of Web Services
  39. Themes
    1. Themes
    2. Building a Theme
    3. Common Firefox theme issues and solutions
    4. Creating a Skin for Firefox
    5. Making sure your theme works with RTL locales
    6. Theme changes in Firefox 2
    7. Theme changes in Firefox 3
    8. Theme changes in Firefox 3.5
    9. Theme changes in Firefox 4
  40. Updating an extension to support multiple Mozilla applications
  41. Using IO Timeout And Interrupt On NT
  42. Using SSH to connect to CVS
  43. Using workers in extensions
  44. WebVR
    1. WebVR
    2. WebVR environment setup
  45. XQuery
  46. XUL Booster
  47. XUL Parser in Python