FAQ (original) (raw)

Please send suggestions or corrections to public-payments-strategy@w3.org.

Table of Contents

• General Questions
• General Payment Method Questions
• General Payment Handler Questions
• Payment Handler Display and Ordering Questions
• Checkout Page Questions
• Backend Questions
• Security Questions
• Payment Scenario Questions
• Deployment and status questions
• Relationship to Other Standards and Technologies
• Rules and Regulations Questions

General Questions

What is the purpose of the Payment Request API?

Making purchases on the web, particularly on mobile, can be a frustrating experience. Every web site has its own flow, and most require users to manually type in the same addresses, contact information, and payment credentials again and again. This can lead to shopping cart abandonment and lost customer loyalty. Likewise, it is difficult and time-consuming for developers to create and maintain checkout pages that support various payment methods.

The Payment Request API (and supporting specifications) enables merchants to create streamlined checkout experiences. Rather than retyping shipping addresses, contact information, payment credentials, and other information again and again across the Web, users can store and reuse information and more quickly and accurately complete online transactions.

In one sentence, how does it work?

Payment Request API enables a user to complete a transaction more easily by reusing information stored in the browser or third party payment handlers.

In a few sentences, how does it work?

When the user presses a button on a checkout page that is connected to the API, the merchant uses the API to request payment. The merchant provides information about price, currency, and a list of accepted payment methods. The merchant can also request that the browser create a streamlined user interface to collect shipping address, contact information, and a small number of additional items from the user.

The browser determines which of the user's "payment handlers" it knows about support the merchants accepted payment methods. The browser displays those matching payment handlers to the user. If the merchant has asked the browser to help collect a shipping address or other data, the browser presents stored data for user selection (or prompts the user to enter new data).

The user selects a payment handler to pay. The payment handler may involve further user interaction (e.g., to authenticate). Upon completion, the payment handler returns data through the API back to the merchant.

What are the primary benefits of the API?

• Improved user experience in a variety of ways including: less typing, consistency across Web sites, consistency across browsers and operating systems, and new browser features to streamline checkout.
• Faster checkout.
• Easier development of checkout pages for merchants or their service providers.
• Improved security. Payment Request API has the potential to reduce opportunities for fraud, and may facilitate the adoption of more secure payment methods.
• Lower liability. In the past, to create a streamlined user experience, merchants needed to store user payment credentials. This is no longer necessary, which may help reduce some merchant liability.
• Supports payment method innovation. By lowering the cost of integrating new payment methods, the payments industry can create and adopt new payment methods more easily, for example, to improve security.

What are the primary risks of the API?

Payment Request API enables merchants to "hand off" the collection of payment credentials to payment handlers. This lowers the burden for merchants to build a checkout experience and the improved user experience is expected to increase conversions. This implies, however, that when they do so, merchants do not control some aspects of the user experience.

What does a merchant need to do to use the API?

At a high level, the API affects the front end (checkout), not back end. Therefore, merchant's should not have to make changes to backend processing of various payment methods.

Whoever provides the merchant's checkout page will replace Web forms with calls to the Payment Request API. The page designer has an opportunity to simplify the checkout experience; see checkout page questions below. Data received through the API is handled the same way it is today (e.g., to process a card payment).

What does a user need to do to use the API?

Users benefit from reusing credentials (such as payment information, shipping address, and contact information) that they have agreed to store in their browser or payment handlers. This implies that users need:

• A browser or other user agent that implements payment request API; see the deployment and status questions
• For payment methods other than basic card, the user will need one or more payment handlers; see general payment handler questions
• The user will then store credentials in their browser or other payment handlers

Then, when visiting a Web site that leverages payment request API, users will have an opportunity to take advantage of the streamlined reuse of stored credentials.

What is the browser's role in this API?

Note: W3C refers to "user agents" in the specification which most of the time means "browsers" but also refers to any other software that implements the API.

Browsers play two roles in the API. The first involves these activities:

• Compute the intersection of the payment methods that are accepted by the merchant and registered by the user.
• Display (native) user interface that allows the user to provide contact information, shipping addresses, and matching payment handlers.
• Act as a conduit for data to and from the merchant, and to and from the user (via payment handlers).

Browsers are also likely to play a second role, acting as payment handlers for a small number of payment methods. As of this writing, the browser makers plan to support Basic Card payments. This means that users will be able to quickly return card information to merchants that has been previously stored in the browser.

What does a payment handler provider need to do to use the API?

At a high level, a payment handler needs to register with a browser to declare which payment method(s) it supports.

Native mobile payment handlers register and communicate with browsers through platform-specific mechanisms that are out of scope for W3C.

The Web Payments Working Group is working on a mechanism to enable Web sites to register to handle payments on the user's behalf; this is work in progress.

What are the titles of the specifications?

• Payment Request API: This specification describes an API for browsers and other user agents to allow merchants to easily accept payments from different payment methods with minimal integration. User agents facilitate the payment flow between merchant and user.
• Payment Method Identifiers: This document defines payment method identifiers and how they are used.
• Basic Card Payment: This specification describes the data that the merchant receives from a payment handler for a basic card payment.

The Web Payments Working Group is working on additional specifications, including more payment methods and mechanisms to register Web-based payment handlers.

General Payment Method Questions

What is the difference between a Payment Method and a Payment Handler?

In the Payment Request API ecosystem, we decouple the data required to make a payment from the software used to collect that data and initiate payment processing.

A payment method is characterized by the data that the merchant provides to the payer and receives from the payer in order to be paid.

• Example: For a basic card payment method, the merchant provides no data to the payer and receives from the payer card number, expiration date, etc.
• Example: For a credit transfer payment method, the merchant provides information about the merchant account, etc. and receives from the payer information about processing date, transaction codes, etc.

A payment handler is the software that the user uses to pay. A payment handler may support one or more payment methods. Payment handlers may be implemented using a variety of technologies, including those of native operating systems or Web technologies, or a hybrid. Browsers may also act as payment handlers, storing user credentials such as card information. The Payment Request API and Payment Handler API do not address the internal workings of payment handlers, only how they communicate with the browser.

In general, multiple payment handlers may implement the same payment method. However, there are a important cases where there is only one payment handler authorized to support a (proprietary) payment method.

What is the significance of the Payment Method / Payment Handler distinction?

In cases where multiple payment handlers may service a given payment method (e.g., "basic card"), the merchant does not have to worry about software integration. The merchant requests '''data''' through the Payment Request API. The merchant (or their payment service provider) needs to manage that data on the backend, but there is no additional software integration necessary. In the same way, decoupling frees the user to choose their preferred payment handler.

Can any payment method be used with the API?

By design, yes. Payment Request API is designed to work with a large number of payment methods, including pull methods (such as card payments) and push methods (such as credit transfers).

How are payment methods identified?

Two ways:

• Payment methods defined by W3C are identified by short strings such as "basic-card". Each payment method specification from W3C includes the short string for identifying that payment method.
• Payment methods defined by other parties are identified by URLs. This enables any party to publish a payment method that may be referenced by merchants.

What payment methods is W3C defining?

• Basic Card Payment is in active development by the Web Payments Working Group
• W3C is also discussing proposals for two more payment method specifications for Tokenized Card Payments, Credit Transfers, and Interledger Payments (ILP). As of November 2017, these are not yet formal deliverables of the Web Payments Working Group.

What payment methods are available today to be used with the API?

• The primary payment method is "basic-card". This is being supported by browsers (acting as payment handlers) as well as a number of proprietary payment handlers.
• @@Add more information about proprietary payment methods we know about today.

Can merchants express preferences for payment methods?

They can, although the specifications are silent on how that information is handled.

Can payment method owners control which payment handlers implement their payment methods?

Yes; see the draft Payment Method Manifest specification.

What is necessary to create a payment method that works with Payment Request API?

To create a payment method that can be used with this API, the following information is be required:

• An identifier for the payment method; see the Payment Method Identifier specification.
• A description of data provided by the merchant to the payment handler ("request data") and the data returned by the payment handler to the merchant through the user agent ("response data").

For an example, see the the Basic Card Payment specification illustrates how to write a specification for a payment method. The Working Group anticipates publishing such specifications for a variety of payment methods, but others may also publish their own payment method specifications.

See also the Payment Method Good Practices.

General Payment Handler Questions

Is a payment handler just a digital wallet?

More or less. Because the phrase "digital wallet" means different things to different people, we chose a different term.

How do users get payment handlers?

We expect there to be multiple ways to discover and register payment handlers, including visiting Web sites ("Web-based payment handlers") and downloading payment handlers from mobile operating system stores.

See also work on just-in-time registration.

Are payment handlers native mobile apps or Web apps?

By design, both. The Web Payments Working Group is working on a specification for how Web applications register to handle payment requests. The Web Payments Working Group is not discussing the integration of native payment handlers on proprietary platforms; that is being manged by the owners of those platforms.

How does the browser know which payment handlers the user has?

The Web Payments Working Group is developing a specification that defines how this registration takes place for Web-based payment handlers. The goal of the Web Payments Working Group is to establish a single registration mechanism for user agents on any system.

For payment handlers built with native (proprietary) technology, the browser or underlying operating system determine the registration mechanism, and it may vary from system to system.

How does the browser determine whether a payment handler "matches" for a particular transaction?

Payment Request API defines an algorithm that considers:

• Whether the payment handler supports any of the payment methods accepted by the merchant. The merchant declares which payment methods it supports through a list of payment method identifiers passed through the API.
• In addition, some payment methods enable merchants and payment handlers to describe in more detail the conditions under which they accept or support those payment methods. This "capability" information is also used to determine whether a payment handler matches for a given transaction.
• Browsers may also implement other specifications that have an impact on matching, including Payment Method Manifest.

What payment handlers should a merchant support?

It is not W3C's role to recommend software to merchants. However, we think it is helpful to recast this question as multiple questions:

• What payment methods do I want to accept (e.g., card payments, credit transfers, PayPal, Alipay, etc.)?
  • Merchants make a business decision which payment methods they choose to accept.
• What is necessary to support a particular payment handler?
  • For proprietary payment methods, the payment owner determines the software integration requirements. For payment methods that may be implemented by multiple payment handlers, there is expected to be no software integration beyond handling the data returned by the payment handler through Payment Request API.

What payment handlers work with this API today?

Because the specifications are still in development, there are not many payment handlers today that use the API. We are aware of the following:

• A number of browsers implement "basic card" and thus act as payment handlers for that payment method.
• Some browsers are working to support native payment handlers such as Alipay, Samsung Pay, PayPal, and others

Can payment handlers refuse to handle payments from a particular Web site?

Yes. Once selected by the user and launched, payment handlers can do many things, including notifying the user that the payment handler does not accept payment requests from the site.

How should I design a payment handler that works with this ecosystem?

See Payment Handler Good Practices.

Payment Handler Display and Ordering Questions

How are matching payment handlers displayed to the user?

That depends on the individual browser. Display may vary from browser to browser, from desktop to mobile, and so on.

How do merchants know which payment handlers the user has?

In order to protect user privacy, merchants have access to very limited information about the user's environment. Payment Request API does support a limited query mechanism to let the merchant determine whether the user has "anything" that can be used with Payment Request API, but that does not provide information about specific software. This piece of information enables merchants to detect support for the Payment Request API and therefore show a checkout page that uses the API, or else to create a fallback page if the user is not ready to pay with some payment handler.

Can merchants recommend payment handlers to the user?

Yes, via their Web site, but not through Payment Request API. Until the user has registered a payment handler, it is not eligible to appear in the list of matching payment handlers for a transaction.

Can merchants affect the order of matching payment handlers displayed to the user?

No.

How do browsers determine the display order of matching payment handlers?

Browsers take into account a variety of information to provide the best user experience. This information will include, for example:

• Any user preferences that a particular browser supports; different browsers will provide different options to the user.
• User behavior, such as recently used payment handlers.

Does Payment Request API give merchants with a way to influence which payment handler the user selects?

No.

Does Payment Request API give payment handler providers a way to influence which payment handler the user selects?

Not directly.

Does Payment Request API give browsers a way to influence which payment handler the user selects?

Not directly.

Checkout Page Questions

See also security questions as they relate to checkout pages.

How will checkout pages change as a result of this API?

Merchants can simplify checkout pages in several ways, including:

• They will not need to use the checkout page to collect shipping and other common data; the browser can provide that more quickly if the user has already stored it.
• They will not need to ask users to pick a payment method. Instead, they can provide a single button that causes the browser to display relevant payment handlers.

What does the button look like that merchants will use with this API?

There is no requirement to use a particular button; the API may be used one or more times on a checkout page with different payment methods and different buttons.

W3C may provide a recognizable button so that on sites across the Web, users can predict the user experience they will have when they push that button.

Please see the information about branding.

What is the impact on other buttons one typically sees on a checkout page?

Merchants have the flexibility to use the API in a number of ways.

Some merchants may wish to replace a set of existing buttons (for different payment methods) with a single "Buy" button. With the API, pushing a single "Buy" button causes the browser to display only those payment handlers that can be used with the merchants list of accepted payment methods.

Other merchants may wish to mix existing buttons with a new button for Payment Request API.

How does Payment Request API affect the flow of payment methods I already support?

Today, the flow for users typically involves something like this:

• Scan a list of accepted payment methods (not all of which the user cares about)
• Choose one and continue
• For payment methods that involve launching an app or visiting a Web site, send the user to that app or site, then send them back after payment has been completed.

Payment Request API enables an improved flow:

• User pushes a single buy button (no scanning is required)
• The browser displays the user's payment handlers that can be used for the transaction. Browsers are likely to support user preferences so that, for example, a payment handler is launched automatically on a given Web site. This would further streamline checkout.
• For payment methods that involve launching an app or visiting a Web site, send the user to that app or site, then send them back after payment has been completed. The Web Payments Working Group is discussing, however, how we can improve the user experience by creating a stronger sense of "still being in the merchant context" when using an app or Web site to pay. More work needs to be done on this topic.

Can a checkout page use the Payment Request API even though it is not yet supported by all browsers?

Yes. There are a number of mechanisms available to developers to detect browser support for the API and availability of at least one payment handler. This information can be used by the developer to dynamically adjust the checkout page and provide a fallback ("traditional") checkout page for backwards compatibility. For details, see our developer guide.

Does Payment Request API enable merchants to request a separate billing address?

No, not yet.

canMakePayment() always returns false. Why?

Check the following:

• Does the browser you are testing with have stored cards?
• Are you using a valid SSL Certificate?

Backend Questions

What does a merchant need to do to accept a particular payment method?

The answer depends on the payment method.

For example, if today the merchant collects credit card data through a Web form, the merchant (or payment service provider) will receive the same data through the Payment Request API and will still need to manage it however that is done today.

Other payment methods may involve additional software integration, legal agreements, merchant verification, etc. For example, an organization that owns a proprietary payment method may require software integration beyond what the Payment Request API does.

How does a merchant handle payment response data it receives?

At a high level, the merchant receives the same (or very similar) data through Payment Request API (a JavaScript API) that they would receive through a Web form. Merchants (or their payment service providers) will still need to do what they ordinarily do with that data.

Can merchants who store card on file still use the API?

Yes, it may be useful for the initial data capture.

Security Questions

See also:

• How does Payment Request API affect PCI/DSS compliance?

In what way to the Payment Request API increase security?

• Merchants can achieve a streamlined checkout without storing user credentials (since users store their own credentials). This makes merchants less vulnerable to attacks.
• payment handler selection from native browser chrome should eliminate some malicious behavior that might affect Web pages.
• Payment Request API should make it easier to bring more secure payment methods to the Web, such as tokenized card payments.
• Payment method owners will have standard mechanisms to authorize specific software to implement their payment method, which the browser can verify (namely, a digital signature).

How does the browser store information securely?

That is an implementation detail for each browser. For detailed information, please contact each browser vendor. Here are some starting points for some browsers:

• Chrome
• Firefox
• Webkit/Safari
• Edge

How do payment handlers store information securely?

That is an implementation detail for each payment handler. Storage on the back-end is entirely up to the payment provider.

Is user gesture required to activate Payment Request API?

Yes. PaymentRequest.show() requires user gesture, which means that PaymentRequest.show() should be triggered, for example, via a button event handler.

Do browser implementations enforce this user gesture requirement?

Yes, that is the expectation.

Does the API include user authentication?

No.

There are (at least) two types of user authentication:

• Merchant authentication of the user (e.g., the user logs into their account with the merchant).
• payment handler authentication of the user (e.g., by providing a CVV code, through name/password, or through multi-factor authentication).

Both of these lie outside the scope of the Payment Request API specification.

Note: W3C's Web Authentication Working Group is working on new standards for strong authentication on the Web.

Is Payment Request API called in a Secure Context?

Yes, as indicated by the WebIDL in the specification. See more on definition of Secure Context.

Please note that browser implementations may vary in exactly what they support. For instance, Chrome considers the following to be secure contexts: "https://", "file://", and localhost URLs.

For push payment methods, how does the merchant know the payment response has not been tampered with?

That will depend on the payment method. We imagine different scenarios:

• The merchant and payment service provider can communicate authoritative information out of band.
• Some payment methods may support digitally signing part of the Payment Request API response.

Payment Scenario Questions

Does the API address subscriptions / recurring payments directly?

No, this version of the API does not address subscriptions directly. The API may be used to collect credentials that, in conjunction with an out-of-band agreement, can be used for subscriptions.

The Working Group is also discussing tokenized card payment use cases, including supporting the flow of tokens that may be used for recurring payments.

For push payment methods, how does a merchant know when it has been paid?

That will depend on the payment method. We imagine different scenarios:

• In some cases (e.g., real-time payments), the merchant can check its account.
• The merchant and payment service provider can communicate authoritative payment status out of band.
• Some payment methods may support digitally signing status information in the Payment Request API response.

Deployment and Status Questions

Who is participating in this work:

• Please see the list of participating organizations.

Which browsers implement this today?

As of September 2017, all major browser vendors are implementing the specifications. The specifications are still drafts, and there is not yet interoperability across browsers and across platforms (e.g., mobile and desktop).

How do I know whether a given browser has implemented Payment Request API?

Through standard JavaScript feature detection. For details, see our developer guide.

How interoperable are implementations today?

The specifications are still drafts, and implementations are still changing. However, there are encouraging signs of early interoperability.

When do you expect broad interoperability?

Interoperability will continue to increase in 2017, especially on mobile. We do not yet have a deep understanding of implementation plans in 2018.

When does W3C expect the standard to be completed?

• As of November 2017, W3C expects Payment Request API to become a W3C Recommendation by mid-2018. That will depend in part on the extent of interoperable implementations.

Is Payment Request API just for the Web?

In theory, no. In practice, we expect it to be mostly implemented by browsers and other Web software.

Relationship to Other Standards and Technologies

Can I use Payment Request API with iframes?

Yes, see section 17 of the specification.

What is the relationship to requestAutocomplete?

The requestAutocomplete() method (aka rAC), a part of the autofill mechanism defined in the HTML specification, was designed to address use cases similar to the core part of the Payment Request API. However, along with the fact that rAC has not been adopted by implementers other than Chrome, rAC is limited in a number of ways compared to the Payment Request API:

• rAC is limited to credit card scenarios (and thus only works with form fields)
• rAC cannot collect a system-level payment mechanism from newer systems like Apple Pay
• rAC was not designed for integration with financial systems or third party software

The Payment Request API endeavors to address these limitations and offer additional functionality.

How will Payment Request API work with 3D Secure v1?

The merchant/processor submits the card details for processing, whether they were collected via Payment Request API or a Web form. In either case, if the subsequent response is a redirect then the user will be redirected.

If the payment is processed within a payment handler and it is a card payment that requires 3D Secure then the payment handler displays a window that renders the redirect URL (as is done with native mobile apps).

How will Payment Request API work with 3D Secure v2?

As of January 2018, the Web Payments Working Group has a 3DS task force to address this questions.

What is the relationship to ISO 20022 messages?

The Payment Request API facilitates data collection and exchange but is agnostic to the data itself. Whether merchants receive data through a Web form or through Payment Request API, they still need to transform it on the backend into the messages and formats required by different payment systems.

W3C's payment method specifications have a slightly closer relationship to ISO 20022 (or other message formats) because they describe the data that flows through the Payment Request API "pipe." W3C is seeking to align the field names in its payment method specifications with those used in other common standards. Please note that strictly speaking it is not required for interoperability because data still needs to be formatted according to the requirements of each payment system. However we do help terminology alignment will make it easier to do so.

Rules and Regulations Questions

What is the impact of the APIs on Merchant-side storage of payment credentials?

Because Basic Card Payment method fosters user-side storage of card information, this can reduce the friction that motivated merchant-side storage, thus freeing merchants from the risk and liability associated with unauthorized access to stored information.

Additionally, web sites that use the Payment Request API for each transaction avoid the friction that can result when users update their credit card numbers and/or expiration dates. From a user’s perspective, this avoids the hassle of having to update a large number of merchant web sites any time they are issued a new card.

Furthermore, enabling the user agent to determine user authentication information relieves the merchant of the duty of ensuring time-local and sufficiently strong authentication. Additionally, browsers and other payment handlers can make use of local affordances such as biometrics and hardware tokens to authenticate users in ways that can be more convenient, more secure, and create less friction for many users and sites.

Who is liable if browser-stored credentials are compromised?

Please consult the relevant rule-making body for the payment method for an answer.

How does Payment Request API affect PCI/DSS compliance?

If the merchant accepts (non-tokenized) card payments, then the Payment Request API is in scope for PCI/DSS. W3C and PCI are in conversation to understand any potential impact of Payment Request API on PCI/DSS compliance. For relevant PCI/DSS good practice (e.g., if using Payment Request API from within an iframe), see PCI FAQ 1292.

If a merchant develops a payment handler that handles card payments what are the merchant’s obligations regarding PCI DSS and PA-DSS for that payment handler?

See PCI FAQ 1283.

Is there an analysis of the work from a regulatory perspective?

See the flow analysis for regulators in development by the Web Payments Interest Group.