The payment method best practice document describes the practices of integrating property payment method into PaymentRequest API [[!PAYMENTREQUESTAPI]].


The Payment Request API [[!PAYMENTREQUESTAPI]] provides a standard way to initiate payment requests from Web pages and applications. The Web Payments Working Group is designing the API so that it may be used with a broad variety of payment methods, including card payments, direct debits and credits, proprietary payment methods, and distributed ledgers. The purpose of this document is to assist those who wish to describe how to use a given payment method with [[!PAYMENTREQUESTAPI]].

This is an early draft and we recognize that we need more experience with payment method specifications to strengthen the document.


This specification relies on several other underlying specifications.

Payment Request Architecture
The terms Payment Method, Payment App, and Payment Transaction Message Specification are defined by the Payment Request Architecture document [[!PAYMENTARCH]].
Payment Request API
The term PaymentRequest constructor is defined by the PaymentRequest API specification [[!PAYMENTREQUESTAPI]].
Payment Method Identifiers
The term Payment Method Identifier is defined by the Payment Method Identifiers specification [[!METHODIDENTIFIERS]].
The IDL in this specification is defined by Web IDL [[!WEBIDL]].

Payment Method Artifacts

A payment method is a system and set of rules for payments. A number of "artifacts" make it possible use a payment method with the PaymentRequest API:

Structure of a Payment Method Specification

A payment method specification SHOULD include:

Payment Method Specific Considerations

Conditional Matching Beyond Payment Method Identifier Matching

For some payment methods, merchants may wish to express that they accept a payment method but only under certain conditions (e.g., "I only credit cards from brand A and debit cards from brand B"). The Web Payments Working Group has discussed several ways to support more sophisticated matching beyond initial payment method identifier matching.

User Experience

For some payment methods that require a variety of data from the user (that will figure in the payment response), some of that data may not be required for all transactions. To enable payment apps to provide a streamlined user experience, authors of payment method specifications may wish to address topics such as:

Security and Privacy

Considerations in Payment Method Specifications

It is important to protect user data and ensure that it is exchanged securely throughout the network.

Authors of payment method specifications may wish to address topics such as:

  • tokenization of information in the payment response
  • topics that may vary by regulatory regime, such as whether data may be stored by a payment app.
  • links for developers to relevant rules defined for the payment method

Payee Identity

Origin information plays an important role on the Web in identifying the payee. In some use cases, origin information may be necessary but insufficient to identify the payee, including:

  • On hosted checkout pages, and
  • when a site otherwise provides services for multiple merchants.

In these cases, it may be useful to provide a "merchantID" in the data field of the payment request. Payment method specific data offers one way to avoid identifier conflicts across payment methods:

	    new PaymentRequest(
              supportedMethods: [""],
              data: {merchantId: "1234567890"}
           }, {
              supportedMethods: [""],
              data: {merchantId: "ASDFGHJKL"}
            }], shoppingCart).show();

Failures and Reconciliation

Some payment methods may be more sensitive to various failures (e.g., network) than others. To help parties with reconciliation of information after failures, each transaction can be identified with a unique paymentRequestID. Note: This is still under discussion; see issue 224) and issue 287.

Payment methods may define additional mechanisms to make use of the paymentRequestID. For example:

Reconciliation patterns may differ if software exchanging information is owned by the same entity, such as when an organization manages an E-Commerce site and also distributes the payment app the user has selected to pay.


We anticipate that payment methods will change over time. The Working Group anticipates that the ecosystem will use different payment method identifiers to distinguish versions. A merchant that accepts multiple versions of a payment method can supply multiple identifiers.

Operational Considerations

Payment Method Manifest Files

W3C Publishing Policy

W3C does not intend to define any payment methods. However, W3C does plan to publish a small number of payment method specifications (such as [[!CARDPAYMENT]]) that capture common practice of existing payment methods. This is to:

W3C only anticipates publishing payment method specifications as formal technical reports for open payment methods. Note: The Working Group is still developing a definition for "open payment method" but a key aspect is that anybody can write a (third party) payment app that implements the payment method, without a prior business agreement.

Note: It may be that the Web Payments Working Group identifies payment method patterns across a set of proprietary payment methods, in which case, the group may wish to publish a generic "open" payment method specification analogous to the way that [[!CARDPAYMENT]] abstracts data requirements from different card networks.