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.
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 SHOULD include:
data parameter of the PaymentRequest constructor.Many payment methods are likely to need to consider these topics in their design and deployment.
Payment Handler EcosystemPayment method owners may take several approaches to deploying a new payment method:
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"]
}
{
"supported_origins": "*"
}
Note: For related information, see discussion about the iDeal network in light of Payment Request API.
Capability Matching Beyond Payment Method Identifier MatchingFor 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.
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:
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).
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:
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:
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 ReconciliationSome 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.
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 FilesThe 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:
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 RegistrationIn 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 RedirectsHistorically, 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 MethodsW3C 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:
The Working Group list of deliverables includes information about payment method specifications in development.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.3