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

Introduction

When requesting and fulfilling a payment on the Web, a number of messages need to be passed between various parties to execute the movement of funds. This specification details those core 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 core 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 core messages.
Software developers who want to implement Web Payments systems.

Terminology

The terminology in this specification's terminology and messages need to be updated to match the Payments Architecture document.

The Data Model

The data model used for the messages in this specification is intended to be flexible enough to work with a variety of concrete syntaxes. Some of the more formal software designers may find this disconcerting as types and ranges are not strictly locked down at the data model layer. Others will find the need for an abstract data model unnecessary, preferring to express the messages in a more concrete syntax. Some may want to use UML, others may want RDF, and others may prefer JSON's data model. In short, the data model is up for discussion. The only requirement is that we use something that's flexible enough to work with a variety of programming environments while empowering developers to use validation tooling (like JSON Schema) if the facility is available to them.

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

The data model used to document the messages in this specification tends toward being more abstract and less formal while enabling data validation tools to be utilized if available. This is accomplished by providing the general description of the message in the abstract data model and the allowed value types and ranges via tooling for the concrete syntax (e.g. using JSON Schema for Web Payments Core Messages expressed as JSON).

What follows is a 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 constraints placed on the message definition in the abstract data model. Constraints are typically placed on the values using general techniques available to programming environments for each concrete syntax (e.g. JSON Schema 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.

Core Message Components

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. The string MUST begin with a single U+002D HYPHEN-MINUS character if the value is negative. 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"
}

AcceptablePaymentMethod

An AcceptablePaymentMethod expresses the terms under which a payment may be fulfilled.

paymentMethod: One or more payment method identifiers (as defined in [[PAYMENT-METHOD-IDENTIFIERS]]). For example, "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": ["VisaLegacy", "MasterCardLegacy"],
  "paymentAmount": {
    "amount": "4.35",
    "currency": "USD"
}

Core Messages

PaymentRequest

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

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".
acceptablePayment: One or more AcceptablePaymentMethods that the payee will accept as payment.

{
  "type": "PaymentRequest",
  "description": "Payment to ExampleMerch for widgets",
  "acceptablePayment": {
    "paymentMethod": "VisaLegacy",
    "paymentAmount": {
      "amount": "4.35",
      "currency": "USD"
    }
  }
};

PaymentAcknowledgement

A PaymentAcknowledgement expresses the result of processing a payment request.

type: An type identifier associated with the object, typically set to "PaymentAcknowledgement".
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".
payment: 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.

{
  "type": "PaymentAcknowledgement",
  "description": "Payment to ExampleMerch for widgets",
  "payment": {
    "paymentMethod": "VisaLegacy",
    "paymentAmount": {
      "amount": "4.35",
      "currency": "USD"
    },
    ... // payment method specific response details here
  }
};

Expressing Messages as WebIDL

Message

Expressing Messages as JSON

Expressing Messages as JSON-LD

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.

Security Considerations

Message Integrity

There are a variety of ways that message integrity can be protected. Which set of methods will this specification employ.

Message Replay

There are a variety of ways that message replay can be protected against. Which set of methods will this specification employ.