Skip to content

PaymentMethodPractice

Jump to bottom
ianbjacobs edited this page Jun 27, 2019 · 35 revisions

The Payment Request API 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 Payment Request API.

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

Payment Method Artifacts

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

  • A "payment method specification," which is a description of the request and response data exchanged between the browser and payment apps when the payment method is invoked.
  • A machine-readable manifest (available when dereferencing the payment method identifier) with instructions about using the payment method in practice (e.g., with information about payment apps that support the payment method). Note: The Web Payments Working Group expects to specify a vocabulary for this manifest file; see the draft Payment Method Manifest specification.
  • A payment method identifier that serves two purposes: it is used in the matching algorithm of Payment Request API and can be dereferenced for the manifest.

Structure of a Payment Method Specification

A payment method specification SHOULD include:

  • One or more payment method identifiers.
  • Information that parties must provide as input to the payment request API that is specific to the payment method (and not general information about the transaction). This is done via the data parameter of the PaymentRequest constructor.
  • Information that will be in the response from the payment request API. This will typically be information collected from the user (e.g., card number for card payments) through user interface displayed by the browser.
  • Any other payment method-specific requirements that are not addressed by the underlying payment request API, and that developers of payment apps need to take into account when building support for the payment method. See the next section for some payment method specific considerations.
  • Recommended behavior to handle exceptions (e.g., in case of network failures)

Payment Method Specific Considerations

Many payment methods are likely to need to consider these topics in their design and deployment.

Payment Handler Ecosystem

Payment method owners may take several approaches to deploying a new payment method:

  • Proprietary URL-based payment method. If a payment method owner wishes to exercise control over which payment handlers may service the payment method, they should use a URL identifier for the payment method and provide a payment method manifest to authorize trusted handlers.

If the payment method owner only authorizes its own payment handler, the payment method manifest should identify it as the default. In this example, the payment handler is identified by the URL https://payments.com/app.json:

{
  "default_applications": ["https://payments.com/app.json"]
}

If the payment method owner wishes to authorize payment handlers from other partner origins, the payment method manifest should identify them as supported_origins:

{
  "supported_origins": ["https://partner1.com", "https://partner2.com"]
}
  • Open URL-based payment method. If the payment method owner wishes to allow open access by all payment handlers, they should use a URL identifier for the payment method and provide the following payment method manifest.
{
  "supported_origins": "*"
}
  • Standardized payment method. By design, standardized payment methods allow any payment handler to service them. This enables payment handler innovation without requiring changes to the merchant site or maintenance of a payment method manifest file.

Note: For related information, see discussion about the iDeal network in light of Payment Request API.

Capability 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 accept credit cards from brand A and debit cards from brand B"). See "Filtering of Payment Instruments" in the Payment Handler API.

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:

  • Allowing the payee to specify which data is required to be able to process the transaction. This information allows the payment app to only request required information from the user, decreasing the risk of abandonment.

Request Data Validation

To ensure the best user experience, browsers and other implementations of Payment Request API may perform validation on a payment method's request data. The Web Payments Working Group has the following expectation:

  • For payment methods identified by URL, browsers will treat payment request data as opaque data and not perform validation.

  • For payment methods defined by W3C (and identified with short strings), browsers may validate data according to the normative statements of the payment method specification. This includes both WebIDL requirements (e.g., enum values) and normative statements in prose (e.g., relationships among fields).

Security and Privacy Considerations

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 or encryption of information in the payment response.
  • regulatory requirements, such as whether data may be stored by a payment app.
  • links for developers to relevant rules defined for the payment method.

Billing and Shipping Addresses

  • Return the minimum amount of address information necessary for the payment method.
  • See the example of Basic Card for usage of a 'redact list'

Payee Identity

Web 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 : ["https://example.com/method1"],
        data : {merchantId : "1234567890"}
      },
      {
        supportedMethods : ["https://example.com/method2"],
        data : {merchantId : "ASDFGHJKL"}
      }
    ],
    shoppingCart)
    .show();

For security reasons, merchant IDs should not be the merchant's acquirer bank merchant ID number.

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 id attribute.

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

  • The payment method may enable payees to provide a URL (in the Payment Request data) so that payment services can send transaction status information asynchronously to the payee. The status information that is useful to communicate (e.g., success, fail, processing, etc.) will depend on the payment method.

  • Parties may secure the callback channel in a variety of ways. Some parties may wish to provide the same data asynchronously that is available synchronously through Payment Request API. To do this securely is likely to involve some form of mutual authentication. Establishing mutual authentication may involve a burden (e.g., key or certificate exchange) that some parties do not wish to bear. Therefore, some payment servers may prefer to send minimal information to the payee, and require the payee to query the payment server for authoritative status information.

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.

Versioning

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 for Payment Method Owners

Payment Method Manifest Files

The Web Payments Working Group is developing a Payment Method Manifest specification to help payment method owners describe how a payment method participates in the Web Payments ecosystem.

Topics to discuss further regarding manifest files:

  • Performance. Web site managers should set up mechanisms such as caching to ensure that payment manifest files are served efficiently, as they may be frequently fetched. In addition to server-side caching, the webserver can signal to the user agent the period of time when it's OK to use the version cached in the user agent. This can be accomplished via HTTP cache headers. If the web server is resource constrained and the manifest is expected to rarely change, the webmaster should set a longer max-age:
Cache-Control: max-age=31540000

If the manifest is expected to change frequently, the webmaster should set a shorter max-age:

Cache-Control: max-age=86400

The user agents should adhere to these directives when determining how long as manifest can be cached.

Just-in-time Registration

In development; see payment handler issue 240 and pull request on Web App Manifest spec. The browser may be able to leverage information in the payment method manifest to propose apps to the user that (1) the merchant accepts but (2) that the user has not yet registered with the browser.

OpenWindow instead of Redirects

Historically, users accessing proprietary payment methods from a merchant site are redirected to a site managed by the payment method owner. After completing payment, the user is redirected to the merchant site. This experience can be disorienting to the uesr.

With Payment Request API and Payment Handler API, we believe we can achieve an improved user experience. Because user agents (through the standard) know that a payment is happening, they can create an improved user experience that does not remove the user so fully from the merchant context. Specifically, payment method owners can use PaymentRequestEvent.openWindow() in a payment handler to open a view of a site, rather than a full redirect. When the user completes payment in the window, it closes and data returns to the merchant through the Payment Request API response.

W3C Publishing Policy for Payment Methods

W3C plans to publish a small number of payment method specifications (such as Basic Card Payment) that capture common practice of existing payment methods. This is to:

  • bootstrap the payment request API ecosystem
  • ensure that the design of payment request API will work in practice with a variety of payment flows
  • provide an example of how to write a payment method specification

The Working Group list of deliverables includes information about payment method specifications in development.

Clone this wiki locally