348
edits
Changes
Created page with "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 vend..."
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:
* <tt>typ</tt>: MUST be the string <tt>"purchase-receipt"</tt>
* <tt>product</tt>: A URL identifying the product the receipt covers
* <tt>user</tt>: An independently-verifiable identifier for the user that made the purchase.
* <tt>iss</tt>: A full domain (scheme, host, and port) for the store that issued the receipt
* <tt>nbf</tt>: A "not-before" timestamp (seconds from 1970-01-01T00:00:00Z in UTC, RFC3339), indicating when the purchase was completed
* <tt>iat</tt>: An "issued-at" timestamp (seconds from 1970-01-01T00:00:00Z in UTC, RFC3339), indicating when this receipt was issued
* <tt>detail</tt>: (optional) A URL that contains additional human- or machine-readable detail about the purchase
* <tt>verify</tt>: (optional) A URL that can be used by an authenticated application to verify a receipt
=== the product field ===
The <tt>product</tt> field identifies the digital good whose sale is represented by the receipt. Conventionally, it is a URL. A URL representing the root of a domain, without a trailing slash (e.g. <tt>"https://someapp.com"</tt>), 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.
=== the user field ===
The <tt>user</tt> field provides an identification of a human user that can be independently verified by the both the issuer and verifier of the receipt. It is a JSON object structure, containing the following fields:
* <tt>type</tt>: A string
* <tt>value</tt>: A string
The only supported value of <tt>type</tt> at this writing is <tt>email</tt>; the value, in this case, is a verified email address.
=== the iss field ===
The <tt>iss</tt> 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 <tt>nbf</tt> (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 <tt>iat</tt> (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 detail field ===
The <tt>detail</tt> 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 microdata fields?)
=== the verify field ===
The <tt>verify</tt> field is a URL. Is is used for automated verification of a receipt by application receivers. See "Interaction with the verify URL", below.
=== An example receipt ===
{
typ: "purchase-receipt",
product: "https://grumpybadgers.com",
user: {
type: "email",
value: "pseud-123gBm51jc56s@idprovider.com"
},
iss: "https://appstore.com",
nbf: 131360185,
iat: 131360188,
detail: "https://appstore.com/receipt/5169314356",
verify: "https://appstore.com/verify/5169314356"
}
== Creation of the Digital Signature ==
As of this writing, the receipt is digitally signed by applying the [http://self-issued.info/docs/draft-jones-json-web-token.html 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 <tt>typ</tt>, <tt>iss</tt>, <tt>nbf</tt>, and <tt>iat</tt> 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:
# Verifying the cryptographic integrity of the receipt itself
# Authenticating the identity of the user presenting the receipt
# (optionally) 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 <tt>iss</tt> field will be used to pick a public key from a previously-retrieved list.
Authentication of the user is dependent on the user identification contained in the <tt>user</tt> field. At this writing, the only supported user identification technique is a verified email address delivered through BrowserID. BrowserID-savvy application runtimes will use the [[BrowserID Directed Identity Assertion]] API to allow verifying parties to retrieve a user assertion without requiring a consent popup during application launch.
If a payment provider offers a <tt>verify</tt> URL in the receipt, the verifying party is allowed to query that URL to determine the real-time status of the receipt.
=== Interaction with the <tt>verify</tt> URL ===
If the <tt>verify</tt> URL is present, the receiving party may verify it by issuing a GET request to it. The return value of this request is a JSON object with fields:
* <tt>status</tt>: A string, containing one of the values "ok", "pending", "refunded", or "invalid".
This verification is not required, but is provided to support real-time queries. Receipt issuers SHOULD require application authentication on this call, to prevent enumeration attack. Receipt issuers are encouraged to use a sparse, non-guessible receipt sequence ID if they do not authenticate verification calls.
== References ==
* [http://self-issued.info/docs/draft-jones-json-web-token.html JSON Web Token]
* RFC 3339: Date and Time on the Internet: Timestamps
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:
* <tt>typ</tt>: MUST be the string <tt>"purchase-receipt"</tt>
* <tt>product</tt>: A URL identifying the product the receipt covers
* <tt>user</tt>: An independently-verifiable identifier for the user that made the purchase.
* <tt>iss</tt>: A full domain (scheme, host, and port) for the store that issued the receipt
* <tt>nbf</tt>: A "not-before" timestamp (seconds from 1970-01-01T00:00:00Z in UTC, RFC3339), indicating when the purchase was completed
* <tt>iat</tt>: An "issued-at" timestamp (seconds from 1970-01-01T00:00:00Z in UTC, RFC3339), indicating when this receipt was issued
* <tt>detail</tt>: (optional) A URL that contains additional human- or machine-readable detail about the purchase
* <tt>verify</tt>: (optional) A URL that can be used by an authenticated application to verify a receipt
=== the product field ===
The <tt>product</tt> field identifies the digital good whose sale is represented by the receipt. Conventionally, it is a URL. A URL representing the root of a domain, without a trailing slash (e.g. <tt>"https://someapp.com"</tt>), 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.
=== the user field ===
The <tt>user</tt> field provides an identification of a human user that can be independently verified by the both the issuer and verifier of the receipt. It is a JSON object structure, containing the following fields:
* <tt>type</tt>: A string
* <tt>value</tt>: A string
The only supported value of <tt>type</tt> at this writing is <tt>email</tt>; the value, in this case, is a verified email address.
=== the iss field ===
The <tt>iss</tt> 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 <tt>nbf</tt> (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 <tt>iat</tt> (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 detail field ===
The <tt>detail</tt> 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 microdata fields?)
=== the verify field ===
The <tt>verify</tt> field is a URL. Is is used for automated verification of a receipt by application receivers. See "Interaction with the verify URL", below.
=== An example receipt ===
{
typ: "purchase-receipt",
product: "https://grumpybadgers.com",
user: {
type: "email",
value: "pseud-123gBm51jc56s@idprovider.com"
},
iss: "https://appstore.com",
nbf: 131360185,
iat: 131360188,
detail: "https://appstore.com/receipt/5169314356",
verify: "https://appstore.com/verify/5169314356"
}
== Creation of the Digital Signature ==
As of this writing, the receipt is digitally signed by applying the [http://self-issued.info/docs/draft-jones-json-web-token.html 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 <tt>typ</tt>, <tt>iss</tt>, <tt>nbf</tt>, and <tt>iat</tt> 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:
# Verifying the cryptographic integrity of the receipt itself
# Authenticating the identity of the user presenting the receipt
# (optionally) 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 <tt>iss</tt> field will be used to pick a public key from a previously-retrieved list.
Authentication of the user is dependent on the user identification contained in the <tt>user</tt> field. At this writing, the only supported user identification technique is a verified email address delivered through BrowserID. BrowserID-savvy application runtimes will use the [[BrowserID Directed Identity Assertion]] API to allow verifying parties to retrieve a user assertion without requiring a consent popup during application launch.
If a payment provider offers a <tt>verify</tt> URL in the receipt, the verifying party is allowed to query that URL to determine the real-time status of the receipt.
=== Interaction with the <tt>verify</tt> URL ===
If the <tt>verify</tt> URL is present, the receiving party may verify it by issuing a GET request to it. The return value of this request is a JSON object with fields:
* <tt>status</tt>: A string, containing one of the values "ok", "pending", "refunded", or "invalid".
This verification is not required, but is provided to support real-time queries. Receipt issuers SHOULD require application authentication on this call, to prevent enumeration attack. Receipt issuers are encouraged to use a sparse, non-guessible receipt sequence ID if they do not authenticate verification calls.
== References ==
* [http://self-issued.info/docs/draft-jones-json-web-token.html JSON Web Token]
* RFC 3339: Date and Time on the Internet: Timestamps
