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.

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.

Introduction

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.

How to Read this Document

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:

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.

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

Terminology

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

PaymentRequest

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

payment request contents
- The contents of a PaymentRequest message.
type
A set of one or more type identifiers associated with the object, typically set to "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.

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.

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

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?

PaymentResponse

A PaymentResponse expresses the result of processing a payment request.

payment response contents
- The contents of a PaymentResponse message.
type
An type identifier associated with the object, typically set to "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.
{
  "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"
  }
};
      

Supporting Datatypes

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).
The string should match the regular expression ^[0-9]+(\.[0-9]+)?$.

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

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

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.
{
  "paymentMethod": [
    "https://example.org/cards#VisaLegacy",
    "https://example.org/cards#MasterCardLegacy"
  ],
  "paymentAmount": {
    "amount": "4.35",
    "currency": "USD"
  }
}
      

Message Extensibility

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.

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

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

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.

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

Security and Privacy Considerations

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 .

Acknowledgements

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