Copyright © 2022 W3C ® ( MIT , ERCIM , Keio , Beihang ).W3C liability , trademark and permissive document license rules apply.This specification defines capabilities that enable Web applications to handle requests for payment.This section describes the status of this document at the time of its publication.A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.The Web Payments Working Group maintains a list of all bug reports that the group has not yet addressed .This draft highlights some of the pending issues that are still to be discussed in the working group.
No decision has been taken on the outcome of these issues including whether they are valid.Pull requests with proposed specification text for outstanding issues are strongly encouraged.This document was published by the Web Payments Working Group as a Working Draft using the Recommendation track .Publication as a Working Draft does not imply endorsement by W3C and its Members.This is a draft document and may be updated, replaced or obsoleted by other documents at any time.
It is inappropriate to cite this document as other than work in progress.This document was produced by a group operating under the W3C Patent Policy .W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent.An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy .
This document is governed by the 2 November 2021 W3C Process Document .This section is non-normative.This specification defines a number of new features to allow web applications to handle requests for payments on behalf of users: PaymentRequestEvent PaymentRequestEvent PaymentManager PaymentInstrument PaymentRequestEvent This specification does not address how software built with operating-system specific mechanisms (i.e., “native apps”) handle payment requests.In this document we envision the following flow: PaymentManager method name PaymentHandlerResponse CanMakePaymentEvent instruments PaymentRequestEvent PaymentRequestEvent An origin may implement a payment app with more than one service worker and therefore multiple [payment handlers](#dfn-payment-handler) may be registered per origin.
The handler that is invoked is determined by the selection made by the user of a [payment instrument](#dom-paymentmanager-instruments).The service worker which stored the [payment instrument](#dom-paymentmanager-instruments) with its [PaymentManager](#dom-serviceworkerregistration-paymentmanager) is the one that will be invoked.This section is non-normative.A payment handler is a Web application that can handle a request for payment on behalf of the user.
The logic of a payment handler is driven by the payment methods that it supports.Some payment methods expect little to no processing by the payment handler which simply returns payment card details in the response.It is then the job of the payee website to process the payment using the returned data as input.In contrast, some payment methods, such as a crypto-currency payments or bank originated credit transfers, require that the payment handler initiate processing of the payment.
In such cases the payment handler will return a payment reference, endpoint URL or some other data that the payee website can use to determine the outcome of the payment (as opposed to processing the payment itself).Handling a payment request may include numerous interactions: with the user through a new window or other APIs (such as Web Cryptography API ) or with other services and origins through web requests or other means.
This specification does not address these activities that occur between the payment handler accepting the [ and the payment handler returning a response.All of these activities which may be required to configure the payment handler and handle the payment request, are left to the implementation of the payment handler, including: PaymentRequestEvent](#dom-paymentrequestevent) Thus, an origin will rely on many other Web technologies defined elsewhere for lifecycle management, security, user authentication, user interaction, and so on.
This section is non-normative.This section is non-normative.This specification does not address how third-party mobile payment apps interact (through proprietary mechanisms) with user agents, or how user agents themselves provide simple payment app functionality.
One registers a payment handler with the user agent when assigning the first [ to it through the PaymentInstrument](#dom-paymentinstrument) set ()method.
[WebIDL] partial interface [{ [] ServiceWorkerRegistration [SameObject]] readonly attribute PaymentManager [; };] paymentManager The paymentManager attribute exposes payment handler functionality in the service worker.[WebIDL] [ [SecureContext], [Exposed]=(Window,Worker)] interface [{ [] PaymentManager [SameObject]] readonly attribute PaymentInstruments [; attribute] instruments [DOMString] [; };] userHint The [ is used by PaymentManager](#dom-paymentmanager) This attribute allows manipulation of payment instruments associated with a service worker (and therefore its payment handler).To be a candidate payment handler, a handler must have at least one registered payment instrument to present to the user.That instrument needs to match the payment methods specified by the payment request.
When displaying payment handler name and icon, the user agent may use this string to improve the user experience.For example, a user hint of “**** 1234” can remind the user that a particular card is available through this payment handler.
When a agent displays all payment instruments available through a payment handler, it may cause confusion to display the additional hint.[WebIDL] [ [SecureContext], [Exposed]=(Window,Worker)] interface [{] PaymentInstruments [Promise] [(] delete [DOMString]instrumentKey); [Promise] [(] get [DOMString]instrumentKey); [Promise] > [();] keys [Promise] [(] has [DOMString]instrumentKey); [Promise] [(] set [DOMString]instrumentKey, [details);] PaymentInstrument [Promise] [(); };] clear The [ interface represents a collection of payment instruments, each uniquely identified by an instrumentKey.The instrumentKey identifier will be passed to the payment handler to indicate the PaymentInstruments](#dom-paymentinstruments) PaymentInstrument When called, this method executes the following steps: PaymentInstrument When called, this method executes the following steps: PaymentInstrument PaymentInstrument undefined.When called, this method executes the following steps: PaymentInstrument When called, this method executes the following steps: PaymentInstrument When called, this method executes the following steps: PaymentInstrument Promise InvalidStateError DOMException Promise NotAllowedError icons icons icons [[fetchedImage]] PaymentInstrument PaymentInstrument PaymentInstrument When called, this method executes the following steps: PaymentInstrument [WebIDL] dictionary [{ required] PaymentInstrument [DOMString] [;] name [sequence] ] ImageObject [;] icons [DOMString] [; };] method namemember name PaymentInstrument iconsmember icons methodmember method [WebIDL] dictionary [{ required] ImageObject [USVString] [;] src [DOMString] [;] sizes [DOMString] [; };] type srcmember src ImageObject sizesmember sizes ImageObject element, which is a string consisting of an [link] sizes typemember type ImageObject When this algorithm with inputImages parameter is invoked, the user agent must run the following steps: ImageObject type ImageObject sizes ImageObject src ImageObject ImageObject src According to the step 2.3, it is also possible to use the relative url for image.[.The following examples illustrate how relative URL resolution works in different execution contexts.src](#dom-imageobject-src) // In this example, code is located in https://www.example.com/register/sw.js const instrumentKey = “c8126178-3bba-4d09-8f00-0771bcfd3b11”; await self.registration.paymentManager.paymentInstruments.set({ instrumentKey, { name: “My Bob Pay Account: [email protected]”, method: “https://bobpay.com“, icons: [{ src: “../bobpay/icon/lowres.webp”, sizes: “48×48”, type: “image/webp” }] }); const storedInstrument = await registration.paymentManager.paymentInstruments.get(instrumentKey); // storedInstrument.icons[0].src == “https://www.example.com/bobpay/icon/lowres.webp”; This section is non-normative.
The following example shows how to register a payment handler: button.addEventListener(“click”, async() => { if (!window.PaymentManager) { return; // not supported, so bail out.} navigator.serviceWorker.register(“/sw.js”); const registration = await navigator.serviceWorker.ready; // Excellent, we got it! Let’s now set up the user’s payment // instruments.await addInstruments(registration); }, { once: true }); function addInstruments(registration) { return Promise.all([ registration.paymentManager.instruments.set( “dc2de27a-ca5e-4fbd-883e-b6ded6c69d4f”, { name: “My Example Pay Account: [email protected]”, method: “https://example.com/pay”, }), registration.paymentManager.instruments.set( “c8126178-3bba-4d09-8f00-0771bcfd3b11”, { name: “My Bob Pay Account: [email protected]”, method: “https://bobpay.com” }), ]); }; If the [payment handler](#dfn-payment-handler) supports [, the CanMakePaymentEvent](#dom-canmakepaymentevent) Implementations may impose a timeout for developers to respond to the [.If the timeout expires, then the implementation will behave as if CanMakePaymentEvent](#dom-canmakepaymentevent) respondWith ()was called with false.[WebIDL] partial interface [{ attribute] ServiceWorkerGlobalScope [EventHandler] [; };] oncanmakepayment The [ attribute is an oncanmakepayment](#dom-serviceworkerglobalscope-oncanmakepayment) The [ is used to check whether the payment handler is able to respond to a payment request.
CanMakePaymentEvent](#dom-canmakepaymentevent) [WebIDL] [ [Exposed]=ServiceWorker] interface [:] CanMakePaymentEvent [ExtendableEvent]{ constructor( [DOMString]type); [undefined] [(] respondWith [Promise] canMakePaymentResponse); }; This method is used by the payment handler to indicate whether it can respond to a payment request.Upon receiving a PaymentRequest , the [user agent](#dfn-user-agents) MUST run the following steps: CanMakePaymentEvent ServiceWorkerRegistration Fire Functional Event ” canmakepayment” using [ on registration.
CanMakePaymentEvent](#dom-canmakepaymentevent) CanMakePaymentEvent This section is non-normative.This example shows how to write a service worker that listens to the [.When a CanMakePaymentEvent](#dom-canmakepaymentevent) CanMakePaymentEvent Given a PaymentMethodData and a [ that match on PaymentInstrument](#dom-paymentinstrument) trueif this instrument can be used for payment: PaymentInstrument ServiceWorkerRegistration “*”string true.CanMakePaymentEvent CanMakePaymentEvent false.Once the user has selected an Instrument, the user agent fires a [ and uses the subsequent PaymentRequestEvent](#dom-paymentrequestevent) PaymentHandlerResponse Payment Request API supports delegation of responsibility to manage an abort to a payment app.There is a proposal to add a paymentRequestAborted event to the Payment Handler interface.The event will have a respondWith method that takes a boolean parameter indicating if the paymentRequest has been successfully aborted.
ServiceWorkerGlobalScope This specification extends the interface.
ServiceWorkerGlobalScope [WebIDL] partial interface [{ attribute] ServiceWorkerGlobalScope [EventHandler] [; };] onpaymentrequest The [ attribute is an onpaymentrequest](#dom-serviceworkerglobalscope-onpaymentrequest) PaymentRequestEvent The PaymentRequestDetailsUpdate contains the updated total (optionally with modifiers) and possible errors resulting from user selection of a payment method.[WebIDL] dictionary [{] PaymentRequestDetailsUpdate [DOMString] [;] error [;] total [sequence] [;] modifiers [object] [; };] paymentMethodErrors A human readable string that explains why the user selected payment method cannot be used.
Updated total based on the changed payment method.The total can change, for example, because the billing address of the payment method selected by the user changes the Value Added Tax (VAT).Updated modifiers based on the changed payment method.For example, if the overall total has increased by €1.00 based on the billing or shipping address, then the totals specified in each of the modifiers should also increase by €1.00.
Validation errors for the payment method, if any.The PaymentRequestEvent represents the data and methods available to a Payment Handler after selection by the user.
The user agent communicates a subset of data available from the PaymentRequest to the Payment Handler.[WebIDL] [ [Exposed]=ServiceWorker] interface [:] PaymentRequestEvent [ExtendableEvent]{ constructor( [DOMString]type, optional [eventInitDict = {}); readonly attribute] PaymentRequestEventInit [USVString] [; readonly attribute] topOrigin [USVString] [; readonly attribute] paymentRequestOrigin [DOMString] [; readonly attribute] paymentRequestId [FrozenArray] [; readonly attribute] methodData [object] [; readonly attribute] total [FrozenArray] [;] modifiers [Promise] [(] openWindow [USVString]url); [Promise] ] PaymentRequestDetailsUpdate [(] changePaymentMethod [DOMString]methodName, optional [object]? methodDetails = null); [undefined] [(] respondWith [Promise] handlerResponsePromise); };] PaymentHandlerResponse Returns a string that indicates the origin of the top level [payee](#dfn-payee) web page.This attribute is initialized by [Handling a PaymentRequestEvent](#dfn-handling-a-paymentrequestevent).Returns a string that indicates the origin where a PaymentRequest was initialized.When a PaymentRequest is initialized in the [, the attributes have the same value, otherwise the attributes have different values.For example, when a topOrigin](#dom-paymentrequestevent-toporigin) topOrigin When getting, the [ attribute returns the paymentRequestId](#dom-paymentrequestevent-paymentrequestid) [[details]] PaymentRequestEvent This attribute contains PaymentMethodData dictionaries containing the payment method identifiers for the payment methods that the web site accepts and any associated payment method specific data.It is populated from the PaymentRequest using the [MethodData Population Algorithm](#dfn-methoddata-population-algorithm) defined below.This attribute indicates the total amount being requested for payment.
It is of type PaymentCurrencyAmount dictionary as defined in [ [payment-request](#bib-payment-request)], and initialized with a copy of the [ field of the total](#dom-paymentrequestevent-total) This sequence of PaymentDetailsModifier dictionaries contains modifiers for particular payment method identifiers (e.g., if the payment amount or currency type varies based on a per-payment-method basis).It is populated from the PaymentRequest using the [Modifiers Population Algorithm](#dfn-modifiers-population-algorithm) defined below.This method is used by the payment handler to show a window to the user.When called, it runs the [open window algorithm](#dfn-open-window-algorithm).
This method is used by the payment handler to get updated total given such payment method details as the billing address.When called, it runs the [change payment method algorithm](#dfn-change-payment-method-algorithm).This method is used by the payment handler to provide a [ when the payment successfully completes.When called, it runs the PaymentHandlerResponse](#dom-paymenthandlerresponse) Should payment apps receive user data stored in the user agent upon explicit consent from the user? The payment app could request permission either at installation or when the payment app is first invoked.
[WebIDL] dictionary [:] PaymentRequestEventInit [ExtendableEventInit]{ [USVString] [;] topOrigin [USVString] [;] paymentRequestOrigin [DOMString] [;] paymentRequestId [sequence] [;] methodData [;] total [sequence] [; };] modifiers The topOrigin, paymentRequestOrigin, paymentRequestId, methodData, total, and modifiers members share their definitions with those defined for PaymentRequestEvent To initialize the value of the [, the user agent MUST perform the following steps or their equivalent: methodData](#dom-paymentrequestevent-methoddata) PaymentInstrument instruments method methodData To initialize the value of the [, the user agent MUST perform the following steps or their equivalent: modifiers](#dom-paymentrequestevent-modifiers) PaymentInstrument instruments method modifiers total total modifiers Instances of [ are created with the internal slots in the following table: PaymentRequestEvent](#dom-paymentrequestevent) |Internal Slot||Default Value||Description (non-normative)| |[[windowClient]]||null||The currently active WindowClient.This is set if a payment handler is currently showing a window to the user.
Otherwise, it is null.| |[[fetchedImage]]||undefined|| This value is a result of | Upon receiving a PaymentRequest by way of PaymentRequest.show() and subsequent user selection of a payment instrument, the [user agent](#dfn-user-agents) MUST run the following steps: ServiceWorkerRegistration PaymentInstrument Promise InvalidStateError DOMException Fire Functional Event ” paymentrequest” using [ on registration with the following properties: PaymentRequestEvent](#dom-paymentrequestevent) topOrigin paymentRequestOrigin methodData modifiers total paymentRequestId Then run the following steps in parallel, with dispatchedEvent: PaymentHandlerResponse Promise OperationError DOMException An invoked payment handler may or may not need to display information about itself or request user input.Some examples of potential payment handler display include: A [payment handler](#dfn-payment-handler) that requires visual display and user interaction, may call openWindow() to display a page to the user.
Since user agents know that this method is connected to the [, they SHOULD render the window in a way that is consistent with the flow and not confusing to the user.The resulting window client is bound to the tab/window that initiated the PaymentRequestEvent](#dom-paymentrequestevent) This algorithm resembles the [Open Window Algorithm](#dfn-open-window-algorithm) in the Service Workers specification.Should we refer to the Service Workers specification instead of copying their steps? PaymentRequestEvent isTrusted Promise InvalidStateError DOMException PaymentRequestEvent Promise about:blank, return a Promise TypeError Promise Promise [[windowClient]] [[windowClient]] InvalidStateError DOMException [[windowClient]] PaymentRequestEvent This section is non-normative.This example shows how to write a service worker that listens to the [.
When a PaymentRequestEvent](#dom-paymentrequestevent) PaymentRequestEvent async function getPaymentResponseFromWindow() { return new Promise((resolve, reject) => { self.addEventListener(“message”, listener = e => { self.removeEventListener(“message”, listener); if (!e.data || !e.data.methodName) { reject(); return; } resolve(e.data); }); }); } self.addEventListener(“paymentrequest”, e => { e.respondWith((async() => { // Open a new window for providing payment UI to user.const windowClient = await e.openWindow(“payment_ui.html”); // Send data to the opened window.windowClient.postMessage({ total: e.total, modifiers: e.modifiers }); // Wait for a payment response from the opened window.return await getPaymentResponseFromWindow(); })()); }); Using the simple scheme described above, a trivial HTML page that is loaded into the [payment handler window](#dfn-payment-handler-window) might look like the following: Cardholder Name: Card Number: Expiration Month: Expiration Year: Security Code: [WebIDL] dictionary [{] PaymentHandlerResponse [DOMString] [;] methodName [object] [; };] details The payment method identifier for the payment method that the user selected to fulfil the transaction.
A JSON-serializable object that provides a payment method specific message used by the merchant to process the transaction and determine successful fund transfer.The user agent receives a successful response from the payment handler through resolution of the Promise provided to the [ function of the corresponding respondWith](#dom-paymentrequestevent-respondwith) PaymentRequestEvent PaymentHandlerResponse If the Promise is rejected, the user agent MUST run the payment app failure algorithm.
The exact details of this algorithm are left to implementers.Acceptable behaviors include, but are not limited to: When this algorithm is invoked with methodName and methodDetails parameters, the user agent MUST run the following steps: null.InvalidStateError DOMException PaymentRequestDetailsUpdate When this algorithm is invoked with event and handlerResponsePromise parameters, the user agent MUST run the following steps: isTrusted DOMException InvalidStateError DOMException [[respondWithCalled]] InvalidStateError DOMException [[respondWithCalled]] PaymentHandlerResponse methodName methodData details The following example shows how to respond to a payment request: paymentRequestEvent.respondWith(new Promise(function(accept,reject) { /* …processing may occur here …*/ accept({ methodName: “https://example.com/pay”, details: { cardHolderName: “John Smith”, cardNumber: “1232343451234”, expiryMonth: “12”, expiryYear : “2020”, cardSecurityCode: “123” }, }); })); [ [payment-request](#bib-payment-request)] defines an ID that parties in the ecosystem (including payment app providers and payees) can use for reconciliation after network or other failures.CanMakePaymentEvent CanMakePaymentEvent CanMakePaymentEvent CanMakePaymentEvent CanMakePaymentEvent set() set() set() CanMakePaymentEvent respondWith() false.
We acknowledge a consequent risk: if an entity controls both the origin of the Payment Request API call and the origin of the payment handler, that entity may be able to deduce that the user may be in private browsing mode.This section is non-normative.
When ordering payment handlers and payment instruments, the user agent is expected to honor user preferences over other preferences.User agents are expected to permit manual configuration options, such as setting a preferred payment handler or instrument display order for an origin, or for all origins.User experience details are left to implementers.This specification relies on several other underlying specifications.are defined by [ [JSON.stringify] , [ServiceWorkerRegistration] , [ServiceWorkerGlobalScope] As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative.
Everything else in this specification is normative.The key words MAY, MUST, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [ [RFC2119](#bib-rfc2119)] [ [RFC8174](#bib-rfc8174)] when, and only when, they appear in all capitals, as shown here.There is only one class of product that can claim conformance to this specification: a user agent.User agents MAY implement algorithms given in this specification in any way desired, so long as the end result is indistinguishable from the result that would be obtained by the specification’s algorithms.User agents MAY impose implementation-specific limits on otherwise unconstrained inputs, e.g., to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.
When an input exceeds implementation-specific limit, the user agent MUST throw, or, in the context of a promise, reject with, a optionally informing the developer of how a particular input exceeded an implementation-specific limit.TypeError [WebIDL] partial interface [{ [] ServiceWorkerRegistration [SameObject]] readonly attribute PaymentManager [; }; [] paymentManager [SecureContext], [Exposed]=(Window,Worker)] interface [{ [] PaymentManager [SameObject]] readonly attribute PaymentInstruments [; attribute] instruments [DOMString] [; }; [] userHint [SecureContext], [Exposed]=(Window,Worker)] interface [{] PaymentInstruments [Promise] [(] delete [DOMString]instrumentKey); [Promise] [(] get [DOMString]instrumentKey); [Promise] > [();] keys [Promise] [(] has [DOMString]instrumentKey); [Promise] [(] set [DOMString]instrumentKey, [details);] PaymentInstrument [Promise] [(); }; dictionary] clear [{ required] PaymentInstrument [DOMString] [;] name [sequence] ] ImageObject [;] icons [DOMString] [; }; dictionary] method [{ required] ImageObject [USVString] [;] src [DOMString] [;] sizes [DOMString] [; }; partial interface] type [{ attribute] ServiceWorkerGlobalScope [EventHandler] [; }; [] oncanmakepayment [Exposed]=ServiceWorker] interface [:] CanMakePaymentEvent [ExtendableEvent]{ constructor( [DOMString]type); [undefined] [(] respondWith [Promise] canMakePaymentResponse); }; partial interface [{ attribute] ServiceWorkerGlobalScope [EventHandler] [; }; dictionary] onpaymentrequest [{] PaymentRequestDetailsUpdate [DOMString] [;] error [;] total [sequence] [;] modifiers [object] [; }; [] paymentMethodErrors [Exposed]=ServiceWorker] interface [:] PaymentRequestEvent [ExtendableEvent]{ constructor( [DOMString]type, optional [eventInitDict = {}); readonly attribute] PaymentRequestEventInit [USVString] [; readonly attribute] topOrigin [USVString] [; readonly attribute] paymentRequestOrigin [DOMString] [; readonly attribute] paymentRequestId [FrozenArray] [; readonly attribute] methodData [object] [; readonly attribute] total [FrozenArray] [;] modifiers [Promise] [(] openWindow [USVString]url); [Promise] ] PaymentRequestDetailsUpdate [(] changePaymentMethod [DOMString]methodName, optional [object]? methodDetails = null); [undefined] [(] respondWith [Promise] handlerResponsePromise); }; dictionary] PaymentHandlerResponse [:] PaymentRequestEventInit [ExtendableEventInit]{ [USVString] [;] topOrigin [USVString] [;] paymentRequestOrigin [DOMString] [;] paymentRequestId [sequence] [;] methodData [;] total [sequence] [; }; dictionary] modifiers [{] PaymentHandlerResponse [DOMString] [;] methodName [object] [; };] details Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in: Referenced in:.
