Apps/WebApplicationReceipt

A Web Application Receipt is a portable, verifiable proof of purchase token. Receipts are created by payment services providers, distributed to clients, and verified by vendors of digital goods, content, and services.

The Web Application Receipt is implemented as a digitally-signed JSON data structure. This format is universally readable by clients and servers.

Data Fields

A receipt encodes an affirmation by a payment processor that a particular user has completed a transaction to acquire a particular digital product. It contains the following fields:

• typ: MUST be one of "purchase-receipt", "developer-receipt", "reviewer-receipt", "test-receipt".
• product: A JSON object identifying the product the receipt covers and any store specific data.
• user: A JSON object containing an identifier that the issuing store can use to identify the user associated with this receipt.
• iss: A full domain (scheme, host, and port) for the store that issued the receipt
• nbf: A "not-before" timestamp (seconds from 1970-01-01T00:00:00Z in UTC, RFC3339), indicating when the purchase was completed
• iat: An "issued-at" timestamp (seconds from 1970-01-01T00:00:00Z in UTC, RFC3339), indicating when this receipt was issued
• exp: (optional) An "expiry" timestamp (seconds from 1970-01-01T00:00:00Z in UTC, RFC3339), indicating when this receipt will expire
• detail: (optional) A URL that contains additional human- or machine-readable detail about the purchase
• verify: (optional) A URL that can be used by an authenticated application to verify a receipt
• reissue: (optional) A URL that can be used to re-issue a new receipt

the typ field

The typ identifies the type of the receipt. Not all types of receipts need to be accepted.

• 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.
• reviewer-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.

the product field

The product field identifies the digital good whose sale is represented by the receipt. It is a JSON object structure, containing the following fields:

• url: A URL representing the root of a domain, without a trailing slash (e.g. "https://someapp.com"), 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. Currently the following URLs schemes are supported: http://, https://, and app://(for packaged apps)
• storedata: A string that uniquely identifies this app or product for the verifier of the receipt.

the user field

The user field provides an identifier that the issuing store can use to identify the human user associated with this receipt. There is no requirement that any other actor be able to validate this field, or use its contents. It is a JSON object structure, containing the following fields:

• type: A string
• value: A string

The default supported value of type is directed-identifier, and value is a unique user ID. To protect user privacy, the user field should not be an email address, or another identifier that the user or anyone else might recognize. Instead, the suggested implementation is to randomly generate a GUID for each transaction. The store should retain the GUID, and use it to link receipts to accounts, but it should be an unusable opaque identifier to all others.

the iss field

The iss field is the full domain of the issuer of the receipt. It must contain at least a scheme and host, separated by a colon and '//'. If the port on which the issuer receives traffic is non-standard (80 for HTTP, 443 for HTTPS), the port must be included following a ':' character. A trailing slash '/' is NOT included in the value.

the nbf field

The nbf (not before) field identifies the time before which the receipt MUST NOT be accepted for processing. The processing of the nbf field requires that the current date/time must be after or equal to the not-before date/time listed in the nbf field. Implementers may provide for some small leeway, usually no more than a few minutes, to account for clock skew.

the iat field

The iat (issued at) field identifies the time at which the receipt was issued. This claim can be used to determine the age of the token.

the exp field

The exp (expiry) field identifies the time at which the receipt will expire.

the detail field

The detail field is a URL. It is expected to resolve to a human-readable web page which contains detailed information about the receipt. If a transaction log or refund capability is provided for the purchase, it is expected that this page will contain those functions. The page may optionally contain machine-readable information about the transaction. (TODO: Identify microformats/microdata fields?)

the verify field

The verify field is a URL. This can be used for automated verification of a receipt by application receivers and is encourage. See "Interaction with the verify URL", below.

the reissue field

The reissue field is a URL. It is used for automated reissuing of receipts.

An example receipt

{
 typ: "purchase-receipt",
 product: {
   url: "https://grumpybadgers.com",
   storedata: "5169314356"
 },
 user: {
   type: "directed-identifier",
   value: "4fb35151-2b9b-4ba2-8283-c49d381640bd"
 },
 iss: "https://appstore.com",
 nbf: 131360185,
 iat: 131360188,
 exp: 141360188,
 detail: "https://appstore.com/receipt/5169314356",
 verify: "https://appstore.com/verify/5169314356",
 reissue: "https://appstore.com/reissue/5169314356"
}

Creation of the Digital Signature

As of this writing, the receipt is digitally signed by applying the JSON Web Token draft specification.

This specification may be superseded by the Javascript Object Signature and Encryption specification (JOSE), which is currently still in the discussion stages.

In JSON Web Token parlance, the typ, iss, nbf, and iat fields are Reserved Claims, and are subject to normal JWT processing rules.

Verification of a Receipt

Applications receiving a receipt are expected to verify it by:

1. Verifying the cryptographic integrity of the receipt itself
2. Checking the validity of the receipt with the issuer

Verifying the receipt is according to the usual rules of JWT verification. Public key discovery for the issuer is out of scope for JWT, but it is expected that verifying parties will receive public keys from their chosen payment providers through well-documented means, and that the iss field will be used to pick a public key from a previously-retrieved list.

If a payment provider offers a verify URL in the receipt, the verifying party is allowed to query that URL to determine the real-time status of the receipt.

Mozilla Marketplace Privacy Policy

The Mozilla Marketplace will have a privacy policy about what is logged when a receipt is verified.

Interaction with the verify URL

If the verify URL is present, the receiving party may verify it by issuing a POST request to it, where the message body contains the complete receipt.

Currently checking the receipt validity with the issuer is the only way to confirm the status of the payment with the issuer. In future version of the receipt we hope to address this to provide more privacy for users by reducing the number of server checks.

The return value of this request is a JSON object with fields:

• status: A string, containing one of the values "ok", "pending", "refunded", "expired" or "invalid".
• reason: An optional field, normally only populated when a receipt is invalid, this will give you a reason it failed.

Application-level authentication on the verifyURL request is not strictly required, as the possession of a receipt proves that the application is already part of a trusted message flow.

Applications are free to re-query the verifyURL field as often as they see fit; whether this is a one-time or an every-time interaction, or something in between, is up to the application implementor to decide.

The verify URL will always return 200 for a successful check. Other possible response codes are 500 (server error) or a 503 (server busy). In the case of a 503, the client should retry at a later date. Clients should not assume that a 503 is a sign that the receipt is invalid.

Firefox Marketplace receipts

Receipts issued by the Firefox Marketplace receipts differ from the spec in that they contain two parts. The receipt is split on a tilde (~). The second half is the receipt as discussed in this document. The first half of the receipt is a JSON Web Key:

 {u'exp': 1384565449,
  u'iat': 1353029449,
  u'iss': u'https://marketplace-dev-cdn.allizom.org/public_keys/test_root_pub.jwk',
  u'jwk': [{u'alg': u'RSA',
            u'exp': u'AQAB',
            u'kid': u'signer.dev.addons.phx1.mozilla.com',
            u'mod': u'AO4UtZW...'}],
  u'nbf': 1353029449,
  u'price_limit': 100,
  u'typ': u'certified-key'}

The fields are:

• jwk: The JSON Web Key token
• iss: A full domain (scheme, host, and port) for the store that issued this JSON Web Key
• nbf: A "not-before" timestamp (seconds from 1970-01-01T00:00:00Z in UTC, RFC3339), indicating when the transaction was completed
• iat: An "issued-at" timestamp (seconds from 1970-01-01T00:00:00Z in UTC, RFC3339), indicating when this transaction was issued
• exp: (optional) An "expiry" timestamp (seconds from 1970-01-01T00:00:00Z in UTC, RFC3339), indicating when this transaction will expire
• price_limit: always 100
• typ: always "certified-key"

References

• JSON Web Token
• JSON Web Key
• RFC 3339: Date and Time on the Internet: Timestamps