PaySwarm 1.0 - Web API

Unofficial Draft 21 September 2011

Editor:
Manu Sporny, Digital Bazaar, Inc.

Abstract

The PaySwarm Web platform is an open web standard that enables Web browsers and Web devices to perform Universal Web Payment. PaySwarm enables the people that create digital content such as blog posts, music, film, episodic content, photos, virtual goods, and documents to distribute their creations through their website and receive payment directly from their fans and customers. The technology is designed to be integrated directly into blogging platforms, content management systems and general purpose websites. The standard can be applied to the entire content distribution lifecycle, from asset description, to product listings, to licenses, contracts and financial transactions. Features include the ability to exchange money, transact individual sales, subscriptions and micropayments.

Status of This Document

This document is merely a public working draft of a potential specification. It has no official standing of any kind and does not represent the support or consensus of any standards organisation.

Table of Contents

1. Introduction

The PaySwarm Web platform is an open web standard that enables Web browsers and Web devices to perform Universal Web Payment. PaySwarm enables the people that create digital content such as blog posts, music, film, episodic content, photos, virtual goods, and documents to distribute their creations through their website and receive payment directly from their fans and customers. The technology is designed to be integrated directly into blogging platforms, content management systems and general purpose websites.

The technology is provided as an open web platform, which is a combination of technology that is patent-free, royalty-free, published in a free specification, using well-defined protocols and other open technologies. The entire PaySwarm standard, like HTML, HTTP, and JavaScript, is an open web platform. Almost every successful Web technology is built and released in this way.

PaySwarm supports Micropayments. The standard assumes that customers do not want to be bothered to reach for their wallet every time they need to spend a couple of cents, or even a couple of dollars. Micropayment in this case, specifically refers to the ability to automatically distribute payments in increments of up to 1/100,000th of a cent to anybody listed in PaySwarm digital contracts.

It is the goal of this specification to create an environment that is friendly to content creators and customers alike. Distribution of digital goods is becoming an increasing part of the Web and therefore compensation for these digital goods must be as easy to perform as downloading the digital goods. The PaySwarm specification works with the architecture of the Web to deliver a solution that is universal across websites, industries and countries.

2. The Conceptual Model

There are three primary participants in a PaySwarm transaction; the asset acquirer, the asset owner, and the PaySwarm Authority.

2.1 Identity and Identifiers

In order for a universal payment system to work seamlessly, there must be a universal way of identifying things in the environment. This specification uses Internationalized Resource Identifiers [IRI] to refer to things on the network. These things can be a personal identity (https://example.com/people/bob), financial account information (https://example.com/people/bob/accounts/42), public cryptography keys (https://example.com/people/bob/keys/14), assets, licenses and a variety of other pieces of long-lived information that exists on the Web. By naming these things with long-lived unique identifiers, it becomes possible to create a decentralized but stable universal payment architecture.

2.2 Participants

2.2.1 Asset Acquirers

An asset acquirer, more commonly known as a buyer, is an entity that is capable of acquiring the rights to a particular asset via a Contract. The entity is typically a person or an organization that would like to view, copy or otherwise utilize the asset that is being acquired.

2.2.2 Asset Providers

An asset provider, more commonly known as an owner, is the entity providing an asset for sale. Typically, the asset provider 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 asset providers.

2.2.3 PaySwarm Authorities

A PaySwarm Authority is used to store money, process and store contracts, and transfer monetary amounts between financial accounts. While a PaySwarm Authority may hold a great deal of financial data, they are built with data portability in mind. PaySwarm participants may move their money and purchase history from one authority to another. Data portability is a mandatory part of this specification.

2.3 Commerce Model

2.3.1 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.

2.3.2 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 contract to express what a buyer may do with the asset that has been purchased.

2.3.3 Listings

A listing 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. Listings are often published on websites that sell assets via PaySwarm as a way to express wares for sale in a decentralized manner.

2.3.4 Contracts

A contract is the result of a commercial transaction in PaySwarm and contains information such as the listing, 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.

3. Base Technologies

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

3.1 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. PaySwarm is designed to be RESTful by ensuring that the constraints of REST are applied to all transactions performed via PaySwarm systems.

3.2 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.

3.3 The Advanced Encryption Standard

The Advanced Encryption Standard (AES) [FIPS-197] 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 PaySwarm participants is sensitive, it is important that a strong cryptography suite is utilized to digitally sign and transfer the messages.

3.4 HTML+RDFa

Web sites are largely implemented on top of the HyperText Markup Language (HTML). This format is known to be fairly easy to author and publish on the Web. In addition to being easy to publish, it is also important that data published via HTML can be easily read by machines without placing an undue burden on Web authors. Publishing structured data in a decentralized manner also requires a language that is capable of being both expressive and deterministic. The Resource Description Framework in attributes [RDFA-CORE] extends HTML [HTML-RDFA] to allow structured data to be expressed via HTML, but in a way that is easy for Web developers to author.

4. The Registration Process

4.1 Asset Acquirer Registration

In order for an asset acquirer to transact, they must have an account on a PaySwarm Authority. Typically, this account must also contain a positive amount of funds that may be used to acquire goods or services. How this account is created and funds are deposited are outside of the scope of this specification. However, the end result of this sign up process must result in the following items being created for the asset acquirer:

  1. An entity IRI that will be used to identify the entity that is transacting. For example: https://example.com/people/jane.
  2. A financial account IRI that is associated with the entity IRI above. For example: https://example.com/people/jane/accounts/primary.
  3. A positive amount of funds in the financial account mentioned above.

4.2 Asset Provider Registration

In order for an asset provider to transact, they must have an account on a PaySwarm Authority. How this account is created and managed is outside of the scope of this specification. However, the end result of this sign up process must result in the following items being created for the asset provider:

  1. An entity IRI that will be used to identify the entity that is transacting. For example: https://example.com/people/manu.
  2. A financial account IRI that is associated with the entity IRI above. For example: https://example.com/people/manu/accounts/primary.

Since all assets and listings are digitally signed, a public key must be registered for the asset provider with the PaySwarm Authority. This is typically performed by the publishing agent software that is publishing the assets and listings for sale on behalf of the asset provider. The registration is accomplished by executing the following algorithm:

  1. The publishing agent generates and stores a public/private keypair that will be used to associate the publishing agent with the asset provider.
  2. The publishing agent retrieves the PaySwarm Authority configuration from a configuration IRI, given a base IRI to the PaySwarm Authority.
    1. The configuration IRI is generated by concatenating a base IRI, such as https://example.com/ with the payswarm-v1-config suffix. For example, the previous base IRI concatenated with the configuration suffix would result in the following configuration IRI: https://example.com/payswarm-v1-config.
    2. An HTTP GET is performed on the configuration IRI with the HTTP Accept header set to application/ld+json. The PaySwarm Authority must respond with a compacted JSON-LD document using the context specified at https://purl.org/payswarm/v1
    3. The result must be a JSON-LD document containing a flat set of key-value pairs. The public-key registration IRI is identified by the public-key-service key in the JSON-LD document. The value will be the public key service IRI.
  3. The publishing agent initiates an HTTP redirect for the user agent. An HTTP GET request is performed to the public key service IRI with the addition of two IRI query parameters. The first parameter, public-key, is the X.509 PEM-encoded public key. The second parameter, registration-callback, is the registration callback IRI for the publishing agent.
  4. The PaySwarm Authority associates the publishing agent with the asset provider based on the provided public key. Note that is process must authenticate the asset provider via a login process if the asset provider does not have an active login session. Other configuration steps may be performed at this stage, including the specification of defaults for the particular publishing agent.
  5. The PaySwarm Authority specifies a set of publishing agent configuration values and, using the provided public key, encrypts and base-64 encodes the value. The result is sent back to the registration-callback IRI via an HTTP POST.
    1. The following configuration values must be included in the JSON-LD response data to the publishing agent; ... FIXME ...
    2. The JSON-LD response is compacted and encrypted using the public key associated with the registration request. The encrypted byte stream is then base-64 encoded.
    3. The base-64 encoded byte stream is transmitted to the registration callback via an HTTP POST request that is initiatited by the user agent. This is most commonly accomplished by having the PaySwarm Authority generate an HTML form that can be submitted to the publishing agent when a form submission button is clicked via the user agent.
    4. The publishing agent decrypts the base-64 encoded byte stream, extracts the configuration values and stores each value for use during the latter parts of the publishing and purchase process.

5. The Purchase Process

5.1 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, use of virtual machines by the 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 - Full Article #1". 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 person 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": "http://purl.org/payswarm/v1",
   "@subject": "https://example.org/articles/1#asset",
   "@type": ["ps:Asset", "ps:WebPage"],
   "dc:title": "PaySwarm in Practice",
   "dc:creator": 
   {
      "foaf:name": "Digital Bazaar, Inc.",
   }
   "ps:contentUrl": "https://example.org/articles/1",
   "ps:assetProvider": "https://example.org/person/john-doe#me",
   "ps:authority": "https://payswarm.example.com/about#authority",
   "ps:validFrom": "2010-11-28T00:00:00Z",
   "ps:validUntil": "2011-11-28T00:00:00Z"
   "ps:signature": 
   {
       "@type": "sig:JsonldSignature",
       "sig:signer": "https://payswarm.example.com/people/john-doe#key-5",
       "sig:signatureValue": "OWM3YzI4OGQzNGVkMzV...IyZTk2MzQzNmExMgo="
   }
}

5.2 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 contract to express what a buyer may do with the asset that has been purchased.

The following example describes an overly-simplified personal use license.

{
   "@context": "http://purl.org/payswarm/v1",
   "@subject": "http://payswarm.example.com/licenses/personal-use",
   "@type": "ps:License",
   "dc:format": "text/html",
   "ps:licenseTemplate": "This personal use license allows you to save the 
      purchased item 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."
   "ps:licenseTerms": 
   {
      "ex:physicalCopies": 5
   }
}

5.3 Publishing a Listing

A listing 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. Listings are often published on websites that sell assets via PaySwarm 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 PaySwarm Authority (the organization processing the payment) may only take a maximum of 10% of the final sale price to cover their fees.

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

5.4 Authorizing a Payment Session

5.5 Performing a Purchase

5.6 The Contract

A contract is the result of a commercial transaction in PaySwarm and contains information such as the listing, 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": "http://purl.org/payswarm/v1",
   "@subject": "<http://payswarm.example.com/contracts/28394729347",
   "@type": ["ps:Transaction", "ps:Contract"],
   "com:amount": "0.05",
   "com:currency": "USD",
   "com:date": "2011-03-02T03:00:53Z",
   "com:payee": 
   [
      {
         "@type": "com:Payee",
         "com:currency": "USD",
         "com:destination": "https://payswarm.example.com/i/authority/accounts/main",
         "com:payeePosition": 0,
         "com:rate": "10.00",
         "com:rateContext": "com:TaxExempt",
         "com:rateType": "com:InclusivePercentage",
         "rdfs:comment": "PaySwarm Authority Transaction Processing"
      }
   ],
   "com:transfer": 
   [
      {
         "@type": "com:Transfer",
         "com:amount": "0.045",
         "com:currency": "USD",
         "com:destination": "https://payswarm.example.com/i/bob/accounts/primary",
         "com:forTransaction": "http://payswarm.example.com/contracts/28394729347",
         "com:source": "https://payswarm.example.com/i/jane/accounts/primary",
         "rdfs:comment": "Payment for PaySwarm in Practice by Bob Smith."
      },
      {
         "@type": "com:Transfer",
         "com:amount": "0.005",
         "com:currency": "USD",
         "com:destination": "https://payswarm.example.com/i/authority/accounts/main",
         "com:forTransaction": "http://payswarm.example.com/contracts/28394729347",
         "com:source": "https://payswarm.example.com/i/jane/accounts/primary",
         "rdfs:comment": "PaySwarm Authority Transaction Processing"
      }
   ],
   "dc:created": "2011-03-02T03:00:53Z",
   "ps:asset": 
   {
      "@subject": "http://example.com/articles/1#asset",
      "@type": ["ps:Asset", "ps:WebPage"],
      "dc:creator": 
      {
         "foaf:name": "Bob Smith"
      },
      "dc:title": "PaySwarm in Practice",
      "ps:assetProvider": "https://payswarm.example.com/i/bob",
      "ps:authority": "https://payswarm.example.com/client-config",
      "ps:contentUrl": "http://example.com/articles/1",
      "ps:signature": 
      {
         "@type": "ps:JsonldSignature",
         "dc:created": "2011-03-02T00:00:00Z",
         "dc:creator": "https://payswarm.example.com/i/bob/keys/4",
         "ps:signatureValue": "XuLEGuq+ne56Qsc5Nic8I="
      }
   },
   "ps:assetAcquirer": "https://payswarm.example.com/i/jane",
   "ps:assetProviderIdentity": 
   {
      "ps:identityHash": "df913752be56fe0d37dcedc2d7f44708373d2a68"
   },
   "ps:license": 
   {
      "@subject": "http://payswarm.example.com/licenses/blogging",
      "@type": "ps:License",
      "dc:format": "text/html",
      "ps:licenseTemplate": "Personal Use License ..."
   },
   "ps:listing": 
   {
      "@subject": "http://example.com/articles/1#listing",
      "@type": ["gr:Offering", "ps:Listing"],
      "com:payee": 
      [
         {
            "@subject": "http://example.com/articles/1#listing-payee",
            "@type": "com:Payee",
            "com:currency": "USD",
            "com:destination": "https://payswarm.example.com/i/bob/accounts/primary",
            "com:rate": "0.05",
            "com:rateType": "com:FlatAmount",
            "rdfs:comment": "Payment for PaySwarm in Practice by Digital Bazaar."
         }
      ],
      "com:payeeRule": 
      [
         {
            "@type": "com:PayeeRule",
            "com:destinationOwnerType": "ps:Authority",
            "com:maximumRate": "10",
            "com:rateType": "com:InclusivePercentage"
         }
      ],
      "ps:asset": "http://example.com/articles/1#asset",
      "ps:assetHash": "14618b56ff597a2fed560db9aa0610fe442106a4",
      "ps:license": "http://payswarm.example.com/licenses/blogging",
      "ps:licenseHash": "0d8866836917f8ef58af44accb6efab9a10610ad",
      "ps:signature": 
      {
         "@type": "ps:JsonldSignature",
         "dc:created": "2011-03-02T00:00:00Z",
         "dc:creator": "https://payswarm.example.com/i/bob/keys/4",
         "ps:signatureValue": "KXtwA5kXZBJzj1rkPMJmGDROjM+fpi2cJIB+Xqf10="
      },
      "ps:validFrom": "2011-03-02T00:00:00+0000",
      "ps:validUntil": "2011-03-03T00:00:00+0000"
   },
   "ps:listingHash": "1acbd23c3a7d8827270a959a2760f7c4ded98022",
   "ps:signature": 
   {
      "@type": "ps:JsonldSignature",
      "dc:created": "2011-03-02T03:00:53Z",
      "dc:creator": "https://payswarm.example.com/i/authority/keys/1",
      "ps:signatureValue": "ZnGaAs0QCIfEAvCsj2TxRTs8ekQrbbQUXvTLWcQ0kQ=="
   }
}

5.7 Verifying a Purchase

6. The PaySwarm API

7. Implementation Details

7.1 Digital Signatures

7.1.1 Signing

7.1.2 Verifying

8. Data Portability

One of the freedoms that is ensured by this specification is the freedom to own your data and move it to a PaySwarm Authority of your choosing. That is, your transaction history is your property and therefore you must be able to move it to a location of your choosing at will. In order to ensure that this freedom is protected, data portability must be implemented by all conforming implementations of this specification.

8.1 Transfering Purchase History

9. Security Concerns

9.1 Identity Management

9.2 Digital Signatures

9.3 Identifying and Removing Troublemakers

9.4 Halting Asset Distribution

A. References

A.1 Normative references

[FIPS-197]
Information Technology Laboratory. Specification for the ADVANCED ENCRYPTION STANDARD (AES) November 26th, 2001. Department of Commerce, National Institute of Standards and Technology. URL: http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf
[HTML-RDFA]
Manu Sporny; et al. HTML+RDFa 04 March 2010. W3C Working Draft. URL: http://www.w3.org/TR/rdfa-in-html/
[IRI]
M. Duerst, M. Suignard. Internationalized Resource Identifiers (IRI). January 2005. Internet RFC 3987. URL: http://www.ietf.org/rfc/rfc3987.txt
[JSON-LD]
Manu Sporny; Gregg Kellogg; Dave Longley; et al. JSON-LD latest. W3C Community Group Working Draft. URL: http://json-ld.org/spec/latest/
[RDFA-CORE]
Shane McCarron; et al. RDFa Core 1.1: Syntax and processing rules for embedding RDF through attributes. 31 March 2011. W3C Working Draft. URL: http://www.w3.org/TR/2011/WD-rdfa-core-20110331

A.2 Informative references

[REST]
Fielding, Roy Thomas. Architectural Styles and the Design of Network-based Software Architectures 2000. University of California, Irvine. URL: http://www.ics.uci.edu/~fielding/pubs/dissertation/