In order to support standardized commerce over the Web, it is vital that product offers and the result of purchases can be expressed in a simple manner. This specification enables the decentralized offer of products and services for sale and the transaction process resulting in a digitally verifiable receipt between the buyer and the vendor.

This is a highly experimental specification that is attempting to unify the work performed in the the Web Payments Community Group, the Linked Data community, and a number of other Web technology-related organizations . As such, the specification borrows a number of concepts from each group and attempts to sythesize these concepts into a solution that would be easily implemented and deployed by Web developers in order to provide an elegant product offer and digital receipt mechanism for the Web.

Introduction

Add introductory text about the need for a simple electronic commerce standard for the Web.

The Conceptual Model

There are three primary participants in a transaction; the buyer, the vendor, and the payment processor.

Participants

Vendors

A vendor is the entity providing an asset for sale. Typically, the vendor is the legal owner of the asset that is being listed for sale. Ownership of an asset can manifest in a variety of different forms. Copyright ownership, physical ownership, and sub-leased property or services are just a few of the types of ownership that apply to vendors.

Commerce Model

Transactions

A transaction is the exchange of value from one or more source accounts into one or more destination accounts.

Assets

An asset describes a particular item that is provided as a part of a commercial transaction. It is usually an item that can be accessed or acquired on the basis of a sale or rental under the terms of a particular license. Examples of assets include web pages, crowd-funded loans or grants, music files, video streams, use of virtual machines by the hour, 3D printer files for on-demand manufacturing, radio spectrum and many other items that are capable of being transacted.

Licenses

A license is a legal description of a licensee's rights to a particular asset. Licenses are usually included as a part of a receipt to express what a buyer may do with the asset that has been purchased.

Offers

A offer describes the combination of an asset that is for sale under a specific license and a set of payment terms that must be fulfilled in order to access the asset. Offers are often published on websites that sell assets as a way to express wares for sale in a decentralized manner.

Receipts

A receipt is the result of a commercial transaction and contains information such as the offer, the asset that was purchased, the parties involved in the transaction, the license outlining the rights to the asset, and payment information associated with the transaction.

Base Technologies

This specification builds on a number of successful Internet and Web technologies. These technologies are introduced in this section.

Representational State Transfer

REpresentational State Transfer [[REST]] is the architectural style that underpins the World Wide Web. It consists of a set of constraints to ensure that servers, gateways, proxies and clients may interact in a way that is predictable. Systems that are designed with this architecture in mind are called RESTful systems. This system is designed to be RESTful by ensuring that the constraints of REST are applied to all transactions that follow this system.

JavaScript Object Notation for Linking Data

JavaScript Object Notation for Linking Data [[!JSON-LD]] is a lightweight Linked Data format. It is easy for humans to read and write. It is easy for machines to parse and generate. It is based on the already successful JSON format and provides a way to help JSON data interoperate at Web-scale. If you are already familiar with JSON, writing JSON-LD is very easy. There is a smooth migration path from the JSON you use today, to the JSON-LD you will use in the future. These properties make JSON-LD an ideal Linked Data interchange language for JavaScript environments, Web services, and JSON document-based databases.

The Advanced Encryption Standard

The Advanced Encryption Standard (AES) [[!AES]] is a world standard adopted by the United States Government and used to secure a vast majority of the commercial transactions over the Internet via OpenSSL. Since much of the data exchanged over this system is sensitive, it is important that a strong cryptography suite is utilized to digitally sign and transfer the messages.

The Purchase Process

The simplest purchase process includes four distinct steps; publishing an asset, publishing a license, publishing a offer, and performing the purchase. Typically, the vendor publishes the asset description and the offer. Anyone may publish a license that is used in a offer. The purchase is performed via a payment processor.

While it is possible to express assets, licenses, and offers on the Web in many different machine-readable formats, to ensure that implementations do not become more complicated than necessary, all assets, licenses and offer MUST be expressed in JSON-LD [[!JSON-LD]] format.

Publishing an Asset

An asset describes a particular item that is provided as a part of a commercial transaction. It is usually an item that can be accessed or acquired on the basis of a sale or rental under the terms of a particular license. Examples of assets include web pages, music files, video streams, virtual machines intended to be paid for by the CPU-hour, 3D printer files for on-demand manufacturing, radio spectrum and crowd-funded loans and grants.

The following example describes a web page asset with the title "PaySwarm in Practice". The article was created by "Digital Bazaar, Inc." and the information in the asset is valid from November 28th, 2010 to November 28th, 2011. The asset is digitally signed by the organization providing it and thus can be cached, stored and then presented to someone else in a manner that is verifiable by the receiving party.

{
  "@context": "https://w3id.org/payments/v1",
  "id": "http://example.org/articles/1#asset",
  "type": ["Asset", "WebPage"],
  "title": "PaySwarm in Practice",
  "description": "This article covers how to use PaySwarm on your Website.",
  "creator": {
    "type": "Organization",
    "name": "Digital Bazaar, Inc.",
  }
  "contentUrl": "http://example.org/articles/1",
  "validFrom": "2010-11-28T00:00:00Z",
  "validUntil": "2011-11-28T00:00:00Z"
  "signature": {
    "type": "GraphSignature2012",
    "created": "2010-11-28T00:00:00Z",
    "creator": "https://payswarm.example.com/i/digital-bazaar#key-5",
    "signature": "OWM3YzI4OGQzNGVkMzV...IyZTk2MzQzNmExMgo="
  }
}

In order to publish this asset on a Web page, a vendor MUST mark the data up in JSON-LD and place it into an HTML file. For example, assume that the following file is served from the http://example.org/articles/1-purchase URL:

<html>
 <head>
   <title>Buy: PaySwarm in Practice</title>
 </head>
 <body>

   <script type="application/ld+json">
{
  "@context": "https://w3id.org/payments/v1",
  "id": "http://example.org/articles/1#asset",
  "type": ["Asset", "WebPage"],
  "title": "PaySwarm in Practice",
  "description": "This article covers how to use PaySwarm on your Website.",
  "creator": {
    "type": "Organization",
    "name": "Digital Bazaar, Inc.",
  }
  "contentUrl": "http://example.org/articles/1",
  "validFrom": "2010-11-28T00:00:00Z",
  "validUntil": "2011-11-28T00:00:00Z"
  "signature": {
    "type": "GraphSignature2012",
    "created": "2010-11-28T00:00:00Z",
    "creator": "https://payswarm.example.com/i/digital-bazaar#key-5",
    "signature": "OWM3YzI4OGQzNGVkMzV...IyZTk2MzQzNmExMgo="
  }
}
   </script>

  

  <button onclick="buyItem()">Buy</button>

 </body>
</html>
        

It may not initially be clear why an asset would need to be digitally signed. There are two major reasons that assets MUST be digitally signed in order to take part in a secure financial system. The first is to ensure, from a legal standpoint, that the person or organization claiming ownership over the asset is clear. The second is to ensure that forgery cannot occur on any of the asset information claimed by the owner of the asset. For example, if the asset were listed on an non-secure HTTP-based Web site, the information could be easily modified in transit.

Publishing a License

A license is a legal description of a licensee's rights to a particular asset. Licenses are usually included as a part of a receipt to express what a buyer may do with an asset that has been purchased. A license can include a number of rights bestowed upon the licensesee as well as further limitations on those rights. For example, how an asset may be re-broadcast, how often a digital asset may be physically reproduced, what an asset may specifically not be used for, and liability limitations when using the asset are but a few of the rights and obligations expressible via a license.

The following example describes a very simple license for personal use.

{
   "@context": "https://w3id.org/payments/v1",
   "id": "http://payswarm.example.com/licenses/personal-use",
   "type": "License",
   "format": "text/html",
   "licenseTemplate": "This personal use license allows you to save the 
      purchased asset onto any device that you own for your personal enjoyment
      and make up to <span property=\"ex:physicalCopies\" /> printed
      copies of the work for personal use."
   "licenseTerms": 
   {
      "ex:physicalCopies": 5
   }
}
        

Licenses do not need to be created for each site on the Web. In many cases, common licenses can be placed on a website and re-used by a large number of sites that sell assets under similar license terms.

Publishing a offer

A offer describes the combination of an asset that is for sale under a specific license and a set of payment terms that must be fulfilled in order to access the asset. offers are often published on websites that sell assets as a way to express things that are for sale, in a decentralized manner.

The following example describes an asset for sale for $0.05 USD under a license that covers acceptable use of blog posts. The offer is valid from March 2nd 2011 to March 3rd 2011. The only restriction on additional payees is that the payment processor (the organization processing the payment) may only take a maximum of 10% of the final sale price to cover their fees.

{
  "@context": "https://w3id.org/payments/v1",
  "id": "http://example.com/articles/1#offer",
  "type": "Offer",
  "payee": [{
    "id": "http://example.com/articles/1#offer-payee",
    "type": "Payee",
    "currency": "USD",
    "destination": "https://payswarm.example.com/i/bob/accounts/primary",
    "rate": "0.05",
    "rateType": "FlatAmount",
    "comment": "Payment for PaySwarm in Practice by Digital Bazaar."
  }],
  "payeeRule": [{
    "type": "PayeeRule",
    "destinationOwnerType": "payment processor",
    "maximumRate": "10",
    "rateType": "InclusivePercentage"
  }],
  "asset": "http://example.com/articles/1#asset",
  "assetHash": "14618b56ff597a2fed560db9aa0610fe442106a4",
  "license": "http://payswarm.example.com/licenses/blogging",
  "licenseHash": "0d8866836917f8ef58af44accb6efab9a10610ad",
  "validFrom": "2011-03-02T00:00:00+0000",
  "validUntil": "2011-03-03T00:00:00+0000"
  "signature": {
    "type": "GraphSignature2012",
    "created": "2011-03-02T00:00:00Z",
    "creator": "https://payswarm.example.com/i/bob/keys/4",
    "signatureValue": "KXtwA5kXZBJzj1rkPMJmGDROjM+fpi2cJIB+Xqf10="
  }
}

Performing a Purchase

A normal purchase, as opposed to an automatic purchase, is typically performed via a Web browser-based user agent when the participant has never performed a purchase with the vendor's website. The process consists of re-directing the Web browser to the buyer's payment processor for the purposes of authorizing payment to the vendor for a particular offer. If a payment authorization is not approved, the user agent is re-directed back to the vendor's website with an error. If the payment authorization is approved, the user agent is re-directed back to the vendor's website with a short-form receipt, which is used as a proof-of-purchase for the vendor's offer.

Purchase Terms

There are a number of terms that are used during the course of the purchase process.

offer hash
An identifier created by processing a offer expressed as JSON-LD through the RDF Graph Normalization Algorithm and then generating a SHA-1 hash of the result.
purchase callback
An URL that will be on the receiving end of an HTTP POST from the payment processor with the result of a purchase request.
reference identifier
A string value that MUST be greater than one character and less than 256 characters used by the vendor to track purchases. These identifiers can be used to ensure that asset that can be purchased multiple times, like game tokens, can be tracked by the vendor. These identifiers also allow the vendor to protect against unintended double-purchasing due to network failures.
receipt
The resulting value of a purchase request, typically sent from the payment processor to the publishing agent. The object typically contains a short-form receipt as well as other information that may be pertinent to the transaction.

The Purchase Algorithm

The normative algorithm for performing a purchase is expressed below.

  1. The publishing agent initiates a purchase request for a specific offer by re-directing the user agent to the receipts service endpoint:
    1. Generate the purchase request URL by concatenating the receipts service and the following URL parameters:
      offer
      The URL-encoded offer URL.
      offer-hash
      A SHA-1 hash of the offer after being normalized using the RDF Graph Normalization Algorithm.
      callback
      A de-referenceable URL that MUST be able to process an HTTP POST request from the payment processor with the result of a purchase request.
      reference
      An optional, internal reference identifier used by the publishing agent to keep track of the purchase.
      nonce
      An optional cryptographic value that will be used in the encrypted response to the vendor. The response nonce is utilized to prevent replay attacks on the vendor.
    2. Perform an HTTP 303 redirect via the user agent to the purchase request URL.
  2. The payment processor processes the purchase request ending in either an error message or a short-form receipt:
    1. If the purchase was denied or failed for any reason, the payment processor performs an HTTP POST via the user agent back to the callback URL supplied by the vendor during the initiation of the purchase request.
    2. If the purchase was successful, then a receipt is generated and transmitted to the vendor:
      1. To generate the receipt in JSON-LD format, the following pieces of information MUST be expressed:
        @context
        A single value containing the string https://w3id.org/payments/v1 or a list containing that context URL as the first member, where subsequent context declarations MUST NOT override any values in the first member.
        type
        The value Receipt.
        preference
        An array of preferences that are requested by either the payment processor or the participant. All valid options are listed below:
        preAuthorization - The participant has pre-authorized future purchases for the vendor and thus the Automatic Purchasing Algorithm MAY be used for future purchases. If this preference setting is mentioned, the publishing agent SHOULD store the participant's information, including the payment processor URL, for use in future automatic transactions.
        receipt
        The receipt used in the receipt is a summary of the digital receipt that was finalized via the payment processor. It includes the minimum amount of information necessary for the publishing agent to correctly identify the offer that was transacted:
        type
        The value receipt.
        asset
        An URL to the asset that was purchased.
        assetHash
        The SHA-1 hash of the asset information after being normalized using the RDF Graph Normalization Algorithm.
        reference
        The reference identifier, if one was suppied via the purchase request.
        license
        An URL to the license describing the rights associated with the asset that was purchased.
        licenseHash
        The SHA-1 hash of the license information after being normalized using the RDF Graph Normalization Algorithm.
        offer
        An URL to the offer that was purchased.
        offerHash
        The SHA-1 hash of the offer information after being normalized using the RDF Graph Normalization Algorithm.
        assetAcquirer
        An URL to the identity that acquired the asset.
      2. The payment processor initiates an HTTP POST via the user agent back to the callback URL supplied by the publishing agent during the initiation of the purchase request. The POST data is digitally signed according to the Request Signature Algorithm, using the public key of the payment processor.
    3. The publishing agent acts upon the callback by granting access to the asset if the purchase was successful, or providing a page detailing why the purchase failed. The publishing agent SHOULD note any preferences in the receipt and utilize those preferences when processing future purchases from the participant.

Performing Automatic Purchases

An automatic purchase is one where a vendor has been previously authorized by a participant to perform purchases with the buyer's pre-authorized consent. This is typically used when the vendor is trusted, or when the participant has set a spending limit with the vendor and does not want to be bothered unless that spending limit is reached. Automatic purchases are designed to get out of the way of the participant and make the transactional flow as friction-free as possible.

Purchase Terms

There are a number of terms that are used during the course of the purchase process.

purchase request
A message consisting of a offer URL, a offer hash, a participant identity URL, and an optional reference identifier. The message is typically sent by a publishing agent to a participant's payment processor for processing.

The Automatic Purchase Algorithm

The automatic purchase algorithm is outlined below:

  1. The publishing agent prepares a purchase request by constructing a JSON-LD message. The following pieces of information MUST be expressed:
    @context
    A single value containing the string https://w3id.org/payments/v1 or a list containing that context URL as the first member, where subsequent context declarations MUST NOT override any values in the first member.
    type
    The value PurchaseRequest.
    offer
    An URL to the offer that was purchased.
    offerHash
    The SHA-1 hash of the offer information after being normalized using the RDF Graph Normalization Algorithm.
    assetAcquirer
    An URL to the identity that acquired the asset.
    reference
    The reference identifier, if one was suppied via the purchase request.
  2. The purchase request is digitally signed by the publishing agent according to the Request Signature Algorithm using the private key associated with the offer in the purchase request. The purchase request is sent to the payment processor of the participant via an HTTPS connection. The HTTPS protocol MUST be used for transmission of the request and retrieval of the response to prevent replay attacks.
  3. The payment processor checks to ensure that the publishing agent is authorized to perform an automatic purchase on behalf of the provided participant identity URL and responds to the publishing agent:
    1. If the transaction fails, the exception details are placed into a JSON-LD message and sent to the publishing agent.
      Determine how this system will handle response exceptions.
    2. If the transaction is successful, a receipt is generated for the publishing agent. The following fields MUST be placed into the response:
      @context
      A single value containing the string https://w3id.org/payments/v1 or a list containing that context URL as the first member, where subsequent context declarations MUST NOT override any values in the first member.
      type
      The value Receipt.
      receipt
      The receipt used in the receipt is a summary of the digital receipt that was finalized via the payment processor. It includes the minimum amount of information necessary for the publishing agent to correctly identify the offer that was transacted:
      type
      The value receipt.
      asset
      An URL to the asset that was purchased.
      assetHash
      The SHA-1 hash of the asset information after being normalized using the RDF Graph Normalization Algorithm.
      reference
      The reference identifier, if one was suppied via the purchase request.
      license
      An URL to the license describing the rights associated with the asset that was purchased.
      licenseHash
      The SHA-1 hash of the license information after being normalized using the RDF Graph Normalization Algorithm.
      offer
      An URL to the offer that was purchased.
      offerHash
      The SHA-1 hash of the offer information after being normalized using the RDF Graph Normalization Algorithm.
      assetAcquirer
      An URL to the identity that acquired the asset.
    3. The receipt is encrypted according to the Response Encryption Algorithm, using the public key associated with the private key that digitally signed the offer. The encrypted receipt is sent to the publishing agent.
  4. The publishing agent receives the response, which will either be an exception or a receipt, and responds accordingly to the user agent.

The Receipt

A receipt is the result of a commercial transaction and contains information such as the offer, the asset that was purchased, the parties involved in the transaction, the license outlining the rights to the asset, and payment information associated with the transaction.

The following example describes a purchase that occurred on March 2nd 2011 for a Web-based article called "PaySwarm in Practice". The article was authored and listed for sale by Bob Smith and a personal use license was acquired by Jane, who may now peruse the article.

{
  "@context": "https://w3id.org/payments/v1",
  "id": "http://payswarm.example.com/receipts/28394729347",
  "type": ["Transaction", "receipt"],
  "amount": "0.05",
  "currency": "USD",
  "created": "2011-03-02T03:00:53Z",
  "payee": [{
    "type": "Payee",
    "currency": "USD",
    "destination": "https://payswarm.example.com/i/processor/accounts/main",
    "payeePosition": 0,
    "rate": "10.00",
    "rateContext": "TaxExempt",
    "rateType": "InclusivePercentage",
    "comment": "payment processor Transaction Processing"
  }],
  "transfer": [{
    "type": "Transfer",
    "amount": "0.045",
    "currency": "USD",
    "destination": "https://payswarm.example.com/i/bob/accounts/primary",
    "forTransaction": "http://payswarm.example.com/receipts/28394729347",
    "source": "https://payswarm.example.com/i/jane/accounts/primary",
    "comment": "Payment for PaySwarm in Practice by Bob Smith."
  }, {
    "type": "Transfer",
    "amount": "0.005",
    "currency": "USD",
    "destination": "https://payswarm.example.com/i/processor/accounts/main",
    "forTransaction": "http://payswarm.example.com/receipts/28394729347",
    "source": "https://payswarm.example.com/i/jane/accounts/primary",
    "comment": "payment processor Transaction Processing"
  }],
  "created": "2011-03-02T03:00:53Z",
  "asset": {
    "id": "http://example.com/articles/1#asset",
    "type": ["Asset", "WebPage"],
    "creator": {
      "name": "Bob Smith"
    },
    "title": "PaySwarm in Practice",
    "assetProvider": "https://payswarm.example.com/i/bob",
    "payment processor": "https://payswarm.example.com/client-config",
    "contentUrl": "http://example.com/articles/1",
    "signature": {
      "type": "GraphSignature2012",
      "created": "2011-03-02T00:00:00Z",
      "creator": "https://payswarm.example.com/i/bob/keys/4",
      "signatureValue": "XuLEGuq+ne56Qsc5Nic8I="
    }
  },
  "assetAcquirer": "https://payswarm.example.com/i/jane",
  "license": {
    "id": "http://payswarm.example.com/licenses/blogging",
    "type": "License",
    "format": "text/html",
    "licenseTemplate": "Personal Use License ..."
  },
  "offer": {
    "id": "http://example.com/articles/1#offer",
    "type": ["Offering", "offer"],
    "payee": [{
      "id": "http://example.com/articles/1#offer-payee",
      "type": "Payee",
      "currency": "USD",
      "destination": "https://payswarm.example.com/i/bob/accounts/primary",
      "rate": "0.05",
      "rateType": "FlatAmount",
      "comment": "Payment for PaySwarm in Practice by Digital Bazaar."
    }],
    "payeeRule": [{
      "type": "PayeeRule",
      "destinationOwnerType": "payment processor",
      "maximumRate": "10",
      "rateType": "InclusivePercentage"
    }],
    "asset": "http://example.com/articles/1#asset",
    "assetHash": "14618b56ff597a2fed560db9aa0610fe442106a4",
    "license": "http://payswarm.example.com/licenses/blogging",
    "licenseHash": "0d8866836917f8ef58af44accb6efab9a10610ad",
    "signature": {
      "type": "GraphSignature2012",
      "created": "2011-03-02T00:00:00Z",
      "creator": "https://payswarm.example.com/i/bob/keys/4",
      "signatureValue": "KXtwA5kXZBJzj1rkPMJmGDROjM+fpi2cJIB+Xqf10="
    },
    "validFrom": "2011-03-02T00:00:00+0000",
    "validUntil": "2011-03-03T00:00:00+0000"
  },
  "offerHash": "1acbd23c3a7d8827270a959a2760f7c4ded98022",
  "signature": {
    "type": "GraphSignature2012",
    "created": "2011-03-02T03:00:53Z",
    "creator": "https://payswarm.example.com/i/processor/keys/1",
    "signatureValue": "ZnGaAs0QCIfEAvCsj2TxRTs8ekQrbbQUXvTLWcQ0kQ=="
  }
}

Verifying a Purchase