This document outlines how to register payment applications, create payment requests, and reply with payment responses using a standard HTTP API.
Status of This Document
This section describes the status of this document at the time of its publication. Other documents may supersede this document. 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 most effective way to report issues and request features is to engage the working group via the Github
issue tracker for the Working Group. Submitting issues as well as pull requests for changes to the specification are encouraged.
Publication as a First Public Working Draft does not imply endorsement by the W3C Membership. 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 HTTP API enables a web application to initiate payment for a product or service by responding with an HTTP 402 Payment Required response and enough data to initiate and complete a payment flow. The implementation of this feature is expected to be implemented by any HTTP server and client that is interested in executing payments.
1.1 How to Read this Document
This section is non-normative.
This document is a detailed specification for a HyperText Transfer Protocol application programming interface (HTTP API) for executing payments via an HTTP client and server. The document is primarily intended for the following audiences:
Software developers who want to understand the design decisions and algorithms behind the API.
Software developers who want to implement the API.
There are a number of Web Payments messages that are referenced and used in examples in this specification. The normative definition of these messages, as well as how to express them in a variety of syntaxes, is specified in [
The current terminology that is pulled into the HTTP API specification needs some simplification and alignment.
This document attempts to communicate the concepts outlined in the Web Payments space by using specific terms to discuss particular concepts. This terminology is included below and linked to throughout the document to aid the reader:
An entity that receives funds as required by a transaction.
An entity that provides a source of funds as required by a transaction.
[ECB] in a strict sense, a payment is a transfer of funds which discharges an obligation on the part of a payer vis-a-vis a payee. However, in a technical or statistical sense, it is often used as a synonym for transfer order
[EXPERIMENTAL] The payment mediator fulfills a number of roles:
It helps determine which payer payment apps can be used to fulfill the payment request given the payee's accepted payment methods.
It helps the payer choose a payment app (typically with explicit interaction or prior consent).
It passes payment request data to the payer's selected payment app.
A payment mediator thus co-ordinates the flow of messages between the payee, payer, and selected payment app.
[EXPERIMENTAL] A way of paying. A system and set of rules for payments. A payment app may support one or more payment methods. For example, Visa, Mastercard, American Express, bobspay.com are payment methods.
payment method data
[EXPERIMENTAL] The data describing an instance of a payment method. For example, for the Visa payment method this might be the card primary account number (PAN), expiry date, and CVV.
payment method identifier
A string that uniquely identifies a payment method that a user can use to complete a transaction.
A request from a payee to be paid. It contains the details of what to pay and how the payment can be made. How the payment can be made is specified as a list of payment method
identifiers. The payment request MUST contain all of the
payment method data required for each payment method identified in it's set of supported payment methods.
A response to a payment request (normally the result of processing by a payment app). The content of a payment response will be dependant on how the payment is being processed.
2. Payment Flow Overview
The diagram below outlines a basic HTTP client payment flow with no errors. The basic flow starts out with the payer optionally accessing a protected resource and being notified that payment is required. The payee provides a URL where a payment request for the resource can be fetched. The payer fetches the payment request, selects a payment app, and sends the request on to the appropriate
payment app for processing. The payment app initiates the payment and sends a payment response back to the payer. The payer then forwards the payment response back to the payee. If there are no errors, the payee then grants access to the resource that was purchased.
The flow above reflects a pull-based tokenized card payment scenario. There are other flows, like push-based flows, that we may want to demonstrate in this specification as well. Is a tokenized pull-based flow the best exemplary flow to use when introducing the reader to the HTTP API?
3. Detailed Payment Flow
Issue 5: Should PaymentRequest be returned via HTTP 402 response code?
It may be a good idea to return the payment request with the 402 response. The concern is that this would be a misrepresentation of the resource. The counter-argument is that a client shouldn't interpret a 402 response as the resource, and since 402 has not been formally defined yet, we could define it to always come with a payment request response.
The payee's web page requests payment by responding with a 402 Payment Required response code and a URL encoded in the Location header to fetch the request from.
The payment mediator fetches the request from the URL specified in the Location header in the previous step.
The payment mediator scans the list of previously registered payment apps and finds matches against paymentTerms in the payment request.
Issue 6: Payment App selection process should be in Payment App spec
This payment app selection process should probably be moved out into a separate
payment mediator specification and referenced from this specification.
If there is only one app that matches, that is automatically set to the selected payment app.
If there is a pre-existing preference set by the payer that narrows the selection of the payment app to one match, the match is set to the
selected payment app.
If there is more than one potential match, the payer is asked which app they would like to use and the selection is set to the
selected payment app
If there are no matches, the payer is notified and may be taken to an alternate flow where a matching payment app is acquired.
If the payment app does not require the payment flow to switch to a 3rd party payment processor (e.g., cryptocurrency), then the payment response is generated locally and the payee's software is notified.
Issue 7: Further clarify the branching options for the payment flow
Steps 5, 6, and 7 are intended to provide for various flows envisioned by the Web Payments ecosystem. This algorithm is merely a starting point, is very much a work in progress, and is not asserted to be correct at present:
Let "selectedApp" be the payment app selected by the payment mediator.
Let "selectedMethod" be the payment method provided by the payee and selected by the payer.
If selectedMethod.paymentRequestService exists, re-direct the user there (payee-based PSP).
If selectedApp.paymentRequestService exists, re-direct the user there (payer-based PSP).
Otherwise, the payment response can be generated locally (local PSP - Bitcoin and others).
If the app requires the payment flow to switch to a 3rd party payer payment processor (e.g., push-payment like a PayPal/Google Wallet-like app, ACH, ISO20022 style app):
If the app requires the payment flow to switch to a 3rd party payee payment processor (e.g., pull-payment like non-EMV magstripe credit card with embossed PAN and CVV2, or tokenized credit card):
The payment mediator forwards the request on via an HTTP POST to the paymentRequestService in the
paymentTerms (note that the payee sets this, not the payment app).
The payment flow is then transferred to the entity that is going to generate the payment acknowledgment (locally installed payment app, payee's payment service provider, or payer's payment service provider).
Once the entity in control of the payment flow finalizes the
payment response, even if the message is to acknowledge that the payment failed, the payment response is generated and the payer's payment mediator is notified via an HTTP 200 success code.
Issue 8: What is the appropriate HTTP response code for a failed payment?
Returning an HTTP status code of 200 when a payment fails is controversial. The current thinking seems to be that 200 is the right thing to do as the message was processed successfully (that's what the 200 is referring to). The result of processing the message, however, has nuance that may be dependent on the payment method used. As a thought experiment, what should the HTTP response code be in the following cases:
Funds transfer was initiated and completed. Clearly 200, right?
Funds transfer was initiated, but network delay may cause it to fail at a later point in time (ACH, etc.). 102 or 202?
Request for subscription was noted and is setup, but no funds were moved. 200?
Payment submitted to network, but network didn't respond with an auth code. 504?
Cryptocurrency payment was submitted to network but a fork has been detected and it is unclear if we're on the winning or losing fork. 102 or 202?
There are not enough HTTP status codes to try and enumerate the nuanced potential outcomes so the best we can do at present (it seems) is to just report on whether or not the payment request was processed successfully or not and let the payee determine if the outcome of the transaction was valid from their viewpoint. In many nuanced cases, it's up to the payer to decide if it was "successful" or not (like waiting on a certain number of acknowledgments from a blockchain, for example).
Issue 9: Prefer new 'Payment' header instead of 402 response code?
Melvin Carvalho has also raised an issue noting that we may not want to use 402 and the Location header, but rather an additional HTTP header called
Payment that is compatible with multiple 4xx error conditions.
4. Web Payment Operations
4.1 Payment app Registration
The payer's HTTP client navigates to a payment service provider website and authenticates itself to fetch a payment app to register:
Issue 10: What other authentication schemes should be supported for Payment App registration?
While digest authentication is used above, more advanced authentication schemes may also be employed. For example, the mechanism below uses HTTP Signatures and public/private key cryptography to authenticate the client with the server:
Example 2: Authenticated GET of payment app using HTTP Signatures
Issue 11: Should getting a PaymentRequest result in an extra round trip?
It's currently not clear if having an extra round-trip (steps 2 and 3) is beneficial. The alternative is to respond with an HTTP 402 and the payment request (step 4) when the GET for the initial resource is performed. This removes the need to do an extra GET at the expense of providing a little more flexibility wrt. the location of the payment request service. For example, having the Location header enables software developers to split media servers from payment processing servers. That said, there are techniques to do this today without the extra layer of indirection.
Issue 12: Push-based payments should be documented in the HTTP API
The model described here does not explicitly mention "push" payments even though they are supported. While there is nothing in this design that precludes payments pushed from a payer to a payee, it may be helpful to point out explicit support for the scenario as well as an example that illustrates this feature.
The payer's HTTP client accesses the payment request resource:
The paymentRequestService URL, provided in the payment app or the payment request, is used as the HTTP POST endpoint. The payment service provider that is providing the payment app interface receives the payment request, authenticates the payer, and proceeds with the payment:
Example 8: The payment request is POSTed by the payment mediator for processing at the payment app
The editor would like to thank members of the Web Payments Community Group, Web Payments Interest Group, and Web Payments Working Group for the ideas and discussion that culminated in this specification. In addition, thank you to the to the following individuals, in order of their first name, for their input on this specification: LIST_TBD