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:

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"
  }
}

3. Message Extensibility

Issue 9: How is message extensibility achieved?

One proposal for providing message extensibility is to allow messages to be interpreted as JSON-LD with a specific context, such as https://example.org/contexts/web-payments/v1. Doing this would not only solve message versioning, but it would also enable decentralized extensibility for all payment messages while ensuring that there are no clashes in terminology between industry verticals.

4. Expressing Messages as WebIDL

The Web Payments messages described in this specification are intended to be used in browser-based programming environments. The conformance language for browser-based objects is WebIDL. The table below cross-references the messages in this specification to their WebIDL definitions in other specifications.

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

5. Expressing Messages as JSON

The Web Payments messages described in this specification are intended to be used in programming environments that support JSON. The conformance language for JSON objects is JSON Schema. The table below cross-references the messages in this specification to their JSON Schema definitions.

Message JSON Schema
PaymentRequest PaymentRequest.json
PaymentResponse PaymentResponse.json
Issue 4: Inline JSON Schema / JSON-LD

It has been requested that the examples in the table above be included in the document as hide-able inline text areas for easier access.

6. Expressing Messages as JSON-LD

The Web Payments messages described in this specification are intended to be used in programming environments that support JSON-LD. The conformance language for JSON-LD objects is a JSON-LD Frame coupled with JSON Schema. The table below cross-references the messages in this specification to their JSON-LD Frames and JSON Schema definitions.

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

7. Security and Privacy Considerations

Issue 10: What are the security and privacy implications of the HTTP messages?

The Working Group is currently in the early stages of the analysis of the security and privacy implications of this specification. The ongoing analysis can be accessed via the Web Payments Working Group Security and Privacy Considerations wiki .

A. Acknowledgements

This section is non-normative.

The editor would like to thank the Web Payments Community Group and the Web Payments Working Group.

Thanks to the following individuals, in order of their first name, for their input on the specification: ...

B. References

B.1 Normative references

[ISO4217]
ISO 4217: Codes for the representation of currencies and funds. ISO.

B.2 Informative references

[JSON-SCHEMA-CORE]
F. Galiegue; K. Zyp; G. Court. IETF. JSON Schema: Core Definitions and Terminology. Expired informational. URL: http://tools.ietf.org/html/draft-zyp-json-schema-04
[JSON-SCHEMA-VALIDATION]
F. Galiegue; K. Zyp; G. Court. IETF. JSON Schema: Interactive and Non-Interactive Validation. Expired informational. URL: http://tools.ietf.org/html/draft-fge-json-schema-validation-00
[PAYMENT-REQUEST-API]
Adrian Bateman; Zach Koch; Richard Barnes; Roy McElmurry. W3C. Payment Request API. W3C First Public Working Draft. URL: https://www.w3.org/TR/payment-request/