Web Payments 1.0

Unofficial Draft 31 January 2012

Editor:
Manu Sporny, Digital Bazaar, Inc.

Abstract

The purpose of PaySwarm is to build payment into the core architecture of the Web. This document details the foundational layer of this architecture; creating a monetary transaction between two participants on the Web. The document also ensures that the transactional system is decentralized in nature and that all data is portable between systems. The goal is to build a decentralized payment network, ensuring that power and control rest with the participants in the network and not with any centralized authority.

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

Explanation of how this is the base specification for the majority of the types of commerce that happen on PaySwarm.

2. The Conceptual Model

The conceptual model for PaySwarm is relatively simple, and grounded in the way value exchange happens in the real world.

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 Terminology

2.2.1 Agents

An agent is any software that is capable of requesting an action to be performed in a way that is compliant with the PaySwarm specification. The software is usually controlled by a person or an organization that would like to perform some action on a PaySwarm-conformant network.

2.2.2 Participants

A participant is an entity that is capable of performing a transaction on the network. The participant often employs agents to execute transactions on the payment network.

2.2.3 Authorities

An 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 Transactions

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

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.

3.5 Web Keys

Describe the Web Keys specification.

4. The Transaction Process

The simplest exchange of value that can happen in the PaySwarm system is a transaction.

4.1 Transaction Terms

There are a number of terms that are used during the course of processing a transaction.

transaction service
The service endpoint identified by the ps:transactionService key in the domain's PaySwarm configuration file. The configuration file can be fetched by performing an HTTP GET request on the configuration service IRI.
transaction request
A JSON-LD formatted object that contains all of the necessary information required to initiate a transaction on a PaySwarm-conformant network.
transfer
A JSON-LD formatted object that specifies the movement of value from a source account to a destination account.

4.2 The Transaction Algorithm

There are two ways in which a Transaction may be initiated via a authority; Payment Link initiated and agent initiated. The first approach is where a publishing agent may initiate a transaction by constructing a URL targeted to the authority's transaction service using the Payment Links specification. The second approach is where an agent may initiate a transaction by performing an HTTPS POST of JSON-LD object expressing a ps:Transaction. The normative algorithm for performing this operation is detailed below. In both approaches, the authority processesing the request must note the ps:Transaction entry in all of the accounts associated in the transaction and ensure that all accounts external to the authority are notified via the Decentralized Settlement Algorithm.

The normative algorithm for performing an agent-initiated transaction is expressed below.

  1. An agent must construct a transaction request in JSON-LD format containing at least the following:
    @context
    A single value containing the string http://purl.org/payswarm/v1 or a list containing that context IRI as the first member, where subsequent context declarations must not override any values in the first member.
    @type
    The value ps:Transaction.
    com:transfer
    One or more transfers in JSON-LD format containing at least the following:
    @type
    The value ps:Transfer.
    com:amount
    A string value of the total amount of the transfer.
    com:currency
    The currency associated with the amount of the transfer. The value must be an ISO-4217 currency or a dereference-able IRI to a monetary system that is not specified in ISO-4217 but follows the specification of a Currency Mint.
    com:source
    The source account from which the funds listed in com:amount will be withdrawn.
    com:destination
    The destination account to which the funds listed in com:amount will be deposited.
    rdfs:comment
    A string specifying the purpose of the transfer as well as other details intended to be read by a human.
  2. The transaction request is digitally signed by the agent according to the Request Signature Algorithm using a private key associated with the public key that was previously registered with the authority according to the Vendor Registration Algorithm.
  3. The transaction request is sent to the authority of the agent via an HTTPS connection. The HTTPS protocol must be used for transmission of the request and retrieval of the response to prevent replay attacks.
  4. The authority processes the transaction request. Additional transfers may be added to the finalized transaction request by the authority, such as transaction fees, pursuant to existing agreements between the authority and the entity operating the agent. The following properties must be added to the transaction request:
    @id
    The finalized transaction identifier IRI. The value must be dereferenceable and return at least the transaction information returned at the end of this algorithm when accessed using a mechanism that proves authorization to access the resource.
    com:amount
    The total amount of the transaction which is calculated by adding up all of the transfers.
    com:currency
    The currency associated with the total amount of the transaction. The value must be an ISO-4217 currency or a dereference-able IRI to a monetary system that is not specified in ISO-4217 but follows the specification of a Currency Mint.
    com:date
    The date and time at which the transaction was recorded in the system.

The example below shows the full protocol-level exchange between the agent and the authority when performing a Transaction:

--------------------------------- Step #1 -----------------------------------

*** Agent creates a Transaction object

{
   "@type": "ps:Transaction"
   "ps:transfer":
   {
      "@type": "ps:Transfer",
      "com:amount": "7.50",
      "com:currency": "USD",
      "com:source": "https://bluebank.com/people/john/accounts/party-funds",
      "com:destination": "https://redbank.com/people/jane/accounts/hosting",
      "rdfs:comment": "Chipping in for the Pizza Party tomorrow."
   }
}

--------------------------------- Step #2 -----------------------------------

*** Agent signs the Transaction object

{
   "@type": "ps:Transaction"
   "ps:transfer":
   {
      "@type": "ps:Transfer",
      "com:amount": "7.50",
      "com:currency": "USD",
      "com:source": "https://bluebank.com/people/john/accounts/party-funds",
      "com:destination": "https://redbank.com/people/jane/accounts/hosting",
      "rdfs:comment": "Chipping in for the Pizza Party tomorrow."
   },
   "sec:signature":
   {
      "@type": "sec:JsonLdSignature",
      "dc:created": "2011-09-23T20:21:34Z",
      "sec:signer": "http://payswarm.example.com/i/john/keys/5",
      "sec:signatureValue": "ExMgoDIyOGQzNGVkMzVmmMzYzI43Q3OQzNmOWM32Nj4NTIyZTkZDYMI="
   }
}


---------------------------------- Step #3 ----------------------------------

*** Agent HTTPS POSTs the Transaction object to the authority

POST transactions HTTP/1.1
Host: bluebank.com
Content-Length: 634
Content-Type: application/ld+json

{
   "@type": "ps:Transaction"
   "ps:transfer":
   {
      "@type": "ps:Transfer",
      "com:amount": "7.50",
      "com:currency": "USD",
      "com:source": "https://bluebank.com/people/john/accounts/party-funds",
      "com:destination": "https://redbank.com/people/jane/accounts/hosting",
      "rdfs:comment": "Chipping in for the Pizza Party tomorrow."
   },
   "sec:signature":
   {
      "@type": "sec:JsonLdSignature",
      "dc:created": "2011-09-23T20:21:34Z",
      "sec:signer": "http://bluebank.com/people/john/keys/5",
      "sec:signatureValue": "ExMgoDIyOGQzNGVkMzVmmMzYzI43Q3OQzNmOWM32Nj4NTIyZTkZDYMI="
   }
}

---------------------------------- Step #4 ----------------------------------

*** authority processes the transaction and returns the finalized
*** transaction to the Agent

Cache-Control:no-cache, must-revalidate, max-age=0
Content-Length: 728
Content-Type: application/ld+json

{
   "@id": "https://bluebank.com/transactions/20110923f72b8ca3",
   "@type": "ps:Transaction",
   "com:amount": "7.65",
   "com:currency": "USD",
   "com:date": "2011-09-23T20:21:35Z",
   "ps:transfer":
   [{
      "@type": "ps:Transfer",
      "com:amount": "7.50",
      "com:currency": "USD",
      "com:source": "https://bluebank.com/people/john/accounts/party-funds",
      "com:destination": "https://redbank.com/people/jane/accounts/hosting",
      "rdfs:comment": "Chipping in for the Pizza Party tomorrow."
   },
   {
      "@type": "ps:Transfer",
      "com:amount": "0.15",
      "com:currency": "USD",
      "com:source": "https://bluebank.com/people/john/accounts/party-funds",
      "com:destination": "https://bluebank.com/accounts/processing-fees",
      "rdfs:comment": "Chipping in for the Pizza Party tomorrow."
   }]
}

5. The Decentralized Settlement Process

The decentralized settlement process is used to ensure the immediate and smooth transition of funds from an account on one authority to an account on another authority.

5.1 Decentralized Settlement Terms

The following terminology is used to describe concepts used to perform the settling of accounts between multiple PaySwarm Authorities.

disbursing authority
An authority that is disbursing a set of funds to one or more receiving PaySwarm authorities.
receiving authority
An authority that is receiving a set of funds from a disbursing authority.
escrow transfer log
A log of transfers that are either in the process of being disbursed or received for a particular particular financial account. The log is used to ensure that double-entries are not accidentally recorded due to network errors or other fatal errors associated with hardware or software failures.

5.2 The Decentralized Settlement Algorithm

The following algorithm ensures that funds transferred as a part of a transaction can be transmitted to one or more authority payment processors in an interoperable fashion such that there are no dangers that the value exchange is lost or mis-applied to the wrong accounts.

  1. The disbursing authority contacts each receiving authority listed in the list of transfers contained in the transaction being processed and retrieves the ps:TransactionBackhaul service from each configuration service endpoint. If any receiving authority is not available now or at any point during this process, or if the receiving authority is blacklisted for any reason, the transaction must fail.
  2. The disbursing authority processes transfers intended for financial accounts that are local to the system, noting outgoing and incoming transfer amounts in each financial account's escrow transfer log.
  3. The disbursing authority processes transfers intended for financial accounts that are on receiving authorities noting outgoing transfer amounts in each source financial account's escrow transfer log.
  4. The disbursing authority transmits the transaction to each receiving authority. The receiving authority processes transfers intended for financial accounts that are on the receiving authority noting incoming transfer amounts in each target financial account's escrow transfer log. If all amounts were not successfully marked in escrow, the transaction must fail.
  5. The disbursing authority moves all funds from escrow into all local financial accounts. The disbursing authority contacts all receiving authorities and instructs them to move all funds from escrow into all destination financial accounts. This two-stage commit process ensures that in the event of a failure while contacting multiple receiving authorities, that transactions can be backed out.
    While this algorithm outlines how transfer records are transmitted and recorded in a decentralized fashion, it does not outline how each authority ensures that currencies are exchanged between financial institutions. One such possibility is an ACH banking transfer, but such a transfer is not necessary if the banks adopt this protocol for clearing transactions across financial systems.

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/