Web Payments HTTP Messages 1.0

Abstract

This document specifies the Web Payments messages that are used to initiate and acknowledge a payment request via the HTTP protocol. The messages are typically passed between the software ecosystem that inititates, executes, and finalizes Web Payments.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

The most effective way to report issues and request features is to engage the working group via the Github issue tracker for the Working Group. Submitting issues as well as pull requests for changes to the specification are encouraged.

This document was published by the Web Payments Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-webpayments-comments@w3.org (subscribe, archives). All comments are welcome.

Publication as a First Public Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 September 2015 W3C Process Document.

1. Introduction

This section is non-normative.

When requesting and fulfilling a payment via HTTP on the Web, a number of messages need to be passed between various parties to execute the movement of funds. This specification details those HTTP messages and provides instructions on how to interpret those messages in a variety of operating environments.

1.1 How to Read this Document

This section is non-normative.

This document is detailed specification for a set of HTTP messages related to initiating, executing, and finalizing payments on the Web. The document is primarily intended for the following audiences:

Software developers who want to understand the design decisions and structure of the HTTP messages.
Software developers who want to implement Web Payments systems using the HTTP protocol.

1.1.1 Data Model Approach

When designing software systems, the data model used to express the components of the system is important. Data models tend to vary in their formalism. Some data models are more abstract where data values are not typed and only vaguely defined as to what their allowable values may be. Other data models are more concrete, with strongly defined value types and ranges.

The data model used to document the messages in this specification tends toward being more abstract. This is done to aid readability and ensure that the data model can be applied in a variety of programming environments. There is also a mechanism that we use in this specification that enables more formalism when it comes to data types and ranges. This is done to ensure that programmers can re-use specific data validation tooling if it is available to them.

In an attempt to make the description of this approach easier to understand, note the following simple example of a HelloWorld message definition:

HelloWorld

A message that is used to greet the world.

title: A short human-readable title for the message.
message: The message text itself.

Note that there are no formal data value constraints expressed in the message definition in the data model. Even though the data model is fairly abstract, constraints can still be placed on the values in each concrete syntax (e.g., JSON Schema [JSON-SCHEMA-CORE] [JSON-SCHEMA-VALIDATION] in most JSON environments). These constraints can be found in the sections titled Expressing Messages as WebIDL, Expressing Messages as JSON, and Expressing Messages as JSON-LD.

Issue 2: Should concrete expressions be normative?

Whether or not the "Expressing Messages as..." sections should be normative, or in an appendix is currently under debate.

For example, if a developer wanted to express the HelloWorld message definition above in JSON, the following JSON Schema could be used to validate such a message:

{
  "title": "HelloWorld Message JSON Schema",
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": ["title", "message"]
}

1.2 Terminology

This document attempts to communicate the concepts outlined in the Web Payments space by using specific terms to discuss particular concepts. This terminology is included below and linked to throughout the document to aid the reader:

payee: An entity that receives funds as required by a transaction.
payer: An entity that provides a source of funds as required by a transaction.
payment service provider: A body executing payment services such as credit institutions, electronic money institutions, post office giro institutions, payment institutions, central banks other than when acting in their capacity as a monetary authority or carrying out other functions of a public nature, and government departments and local authorities, other than when carrying out functions of a public nature.

2. HTTP messages

Issue 1: How should we test Web Payments messages?

It has been suggested that for the purposes of testing, we should have at least one normative representation of messages in JSON Schema format.

2.1 PaymentRequest

A PaymentRequest expresses a payment that is requested by a payee.

payment request contents — Fig. 1 - The contents of a PaymentRequest message.

type: A set of one or more type identifiers associated with the object, typically set to "PaymentRequest".

Issue 6: What is the range for 'type' in PaymentRequest?

The set of available types MAY be extended in the future to, for example, add things like "SubscriptionRequest" to identify payment requests that may have some recurring quality to them.
description: A human-readable description of the reason the payment request was initiated. This text MAY be displayed to the payer in a payment interface. For example, "Payment for widgets from Acme Anvil Emporium".
paymentTerms: One or more PaymentTerms that the payee will accept as payment.
paymentDetails: An optional set of information concerning the details of why the payment was requested, such as a list of items being purchased.
paymentOptions: An optional set of requests that are intended for the payment mediator or the payment application. For example, a payee may request that a payment mediator return the shipping address and the email address selected by the payer.

Issue 7: Should HTTP messages contain paymentDetails and paymentOptions?

The format for the paymentDetails and paymentOptions objects are still being actively discussed. They are expected to take the form of the PaymentDetails and the PaymentOptions objects in the Web Payments Browser API.

Example 1: An example of a payment request expressed in JSON

{
  "type": "PaymentRequest",
  "description": "Payment to ExampleMerch for widgets",
  "paymentTerms": {
    "paymentMethod": "https://example.org/cards#VisaLegacy",
    "paymentAmount": {
      "amount": "4.35",
      "currency": "USD"
    }
  }
};

Issue 3: Validation of values that may contain more than one item

Whether or not values that may contain one or more items, such as paymentTerms above should throw an error during validation if they are not an array is under discussion. That is, should we say that values that could contain more than one item MUST always be wrapped in an array?

2.2 PaymentResponse

A PaymentResponse expresses the result of processing a payment request.

payment response contents — Fig. 2 - The contents of a PaymentResponse message.

type: An type identifier associated with the object, typically set to "PaymentResponse".

Issue 8: What is the value range for 'type' property in PaymentResponse?

The set of available types MAY be extended in the future to add things like Receipt to identify acknowledgements that contain receipt information.
description: Human readable text that will be used to identify what the payment was for. This text MAY be displayed to the payer. For example, "Payment to ExampleMerch for widgets".
paymentTerms: Information such as the payment method used and the payment amount. Payment method specific information, such as the status of the payment, MAY also be included. The presence and meaning of this extra information is dependent on the payment method. The payment information MAY be used by the payee or their associated payment service provider to, for example, finalize a payment or display information to the payer.
paymentOptions: Any payment options that were requested by the payee, such as email address, phone number, or billing address.

Example 2: An example of a payment response

{
  "type": "PaymentResponse",
  "description": "Payment to ExampleMerch for widgets",
  "payment": {
    "paymentMethod": "https://example.org/cards#VisaLegacy",
    "paymentAmount": {
      "amount": "4.35",
      "currency": "USD"
    },
    ... // payment method specific response details here
  },
  "paymentOptions": {
    "email": "jdoe@example.org"
  }
};

2.3 Supporting Datatypes

2.3.1 FinancialAmount

A FinancialAmount is used to express a scalar financial value.

currency: currency is a string containing a three-character alphaneumeric code for the currency as defined by [ISO4217] or a URL for a currency identifier. For example, "USD" for US Dollars or "https://example.com/currencies/experimental-XYZ" for a new experimental currency.
amount: A string containing the decimal monetary value. The string MUST use a single U+002E FULL STOP character as the decimal separator. All other characters must be characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9).

Note

The string should match the regular expression ^[0-9]+(\.[0-9]+)?$.

The following example shows how to represent $55.00 US Dollars.

Example 3: $55 US Dollars expressed as JSON

{
  "amount": "55.00",
  "currency": "USD"
}

2.3.2 PaymentTerms

PaymentTerms express the type of payment method, amount, and other information under which a transaction may be fulfilled.

paymentMethod: One or more payment method identifiers (as defined in an associated payment method specification). For example, "https://example.org/cards#VisaLegacy" or "https://newnetwork.example.com/methods/SuperCard"
paymentAmount: The FinancialAmount requested by the payee. The value may also be a set of FinancialAmounts that express the desired amount in different currencies.

Example 4: Payment for $4.35 USD may be fulfilled using non-tokenized Visa and MasterCard expressed as JSON

{
  "paymentMethod": [
    "https://example.org/cards#VisaLegacy",
    "https://example.org/cards#MasterCardLegacy"
  ],
  "paymentAmount": {
    "amount": "4.35",
    "currency": "USD"
  }
}

Message	JSON-LD Frame	JSON Schema
PaymentRequest	PaymentRequest-frame.jsonld	PaymentRequest.json
PaymentResponse	PaymentResponse-frame.jsonld	PaymentResponse.json

Web Payments HTTP Messages 1.0

W3C First Public Working Draft 15 September 2016

Abstract

Status of This Document

1. Introduction

1.1 How to Read this Document

1.1.1 Data Model Approach

HelloWorld

1.2 Terminology

2. HTTP messages

2.1 PaymentRequest

2.2 PaymentResponse

2.3 Supporting Datatypes

2.3.1 FinancialAmount

2.3.2 PaymentTerms

3. Message Extensibility

4. Expressing Messages as WebIDL

5. Expressing Messages as JSON

6. Expressing Messages as JSON-LD

7. Security and Privacy Considerations

A. Acknowledgements

B. References

B.1 Normative references

B.2 Informative references

Message	WebIDL Definition
PaymentRequest	[PAYMENT-REQUEST-API] Section 4: Payment Request
PaymentResponse	[PAYMENT-REQUEST-API] Section 11: Payment Response