Copyright © 2016 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.
This document outlines how to register payment applications, create payment requests, and reply with payment responses using a standard HTTP API.
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 http://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.
This document was published by the Web Payments Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-webpayments-comments@w3.org (subscribe, archives). All comments are welcome.
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 document was produced by a group operating under the 5 February 2004 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 1 September 2015 W3C Process Document.
This section is non-normative.
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.
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:
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:
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?
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.
Location
header to fetch the request
from.
request
from the URL specified in the Location
header in the previous step.
paymentTerms
in the payment request.
request
, via an HTTP POST to the
paymentRequestService
in the payment app for approval.
paymentRequestService
in the
paymentTerms
(note that the payee sets this, not the payment app).
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.
GET /apps/visa HTTP/1.1
Host: mybank.example.org
Date: Tue, 07 Jun 2017 20:51:35 GMT
Accept: application/json
Authorization: Digest username="jdoe", realm="jane@mybank.example.org", ...
GET /apps/visa HTTP/1.1
Host: mybank.example.org
Date: Tue, 07 Jun 2017 20:51:35 GMT
Accept: application/json
Authorization: Signature keyId="https://mybank.example.org/people/jane/keys/42",
algorithm="rsa-sha256",headers="(request-target) host date",
signature="jgSqYK0yKclIHfF9zdApVEbDp5eqj8C4i4X76pE+XHoxugXv7qnVrGR+30bmB
gtpR39I4utq17s9ghz/2QFVxlnToYAvbSVZJ9ulLd1HQBugO0jOyn9sXOtcN7
uNHBjqNCqUsnt0sw/cJA6B6nJZpyNqNyAXKdxZZItOuhIs78w="
HTTP/1.1 200 OK
Date: Tue, 07 Jun 2017 20:51:36 GMT
Content-Type: application/json
Content-Length: 412
{
"type": "PaymentApp",
"paymentMethod": "https://payments.example.org/payment-schemes#Visa",
"label": "ExampleBank Visa Card",
"paymentRequestService": "https://mybank.example.org/services/cards/2745023475"
}
GET /movies/dr-strangelove HTTP/1.1
Host: videos.example.com
Date: Tue, 07 Jun 2017 21:31:35 GMT
Location
header:
HTTP/1.1 402 Payment Required
Date: Tue, 07 Jun 2017 21:31:36 GMT
Location: https://videos.example.com/payment-requests/dr-strangelove
GET /payment-requests/dr-strangelove HTTP/1.1
Host: videos.example.com
Date: Tue, 07 Jun 2017 21:31:37 GMT
HTTP/1.1 200 OK
Date: Tue, 07 Jun 2017 21:31:38 GMT
Content-Type: application/json
Content-Length: 873
{
"type": "PaymentRequest",
"description": "Payment for Dr. Strangelove",
"paymentTerms": {
"paymentMethod": "https://payments.example.org/payment-schemes#Visa",
"paymentAmount": {
"amount": "2.99",
"currency": "USD"
}
},
"paymentCompleteService": "https://videos.example.com/services/paymentComplete?transaction=923847298"
}
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:
POST /services/cards/2745023475 HTTP/1.1
Host: mybank.example.org
Date: Tue, 07 Jun 2017 20:51:35 GMT
Accept: application/json
{
"type": "PaymentRequest",
"description": "Payment for Dr. Strangelove",
"paymentTerms": {
"paymentMethod": "https://payments.example.org/payment-schemes#Visa",
"paymentAmount": {
"amount": "2.99",
"currency": "USD"
}
},
"paymentCompleteService": "https://videos.example.com/services/paymentComplete?transaction=923847298"
}
HTTP/1.1 200 OK
Date: Tue, 07 Jun 2017 20:51:36 GMT
Content-Type: application/json
Content-Length: 623
{
"type": "PaymentResponse",
"description": "Payment to ExampleMerch for widgets",
"paymentTerms": {
"paymentMethod": "https://payments.example.org/payment-schemes#Visa",
"status": "authorized",
"token": "10025AB",
"paymentAmount": {
"amount": "2.99",
"currency": "USD"
}
}
}
paymentCompleteService
URL provided in the initial payment request:
POST /services/paymentComplete?transaction=923847298 HTTP/1.1
Host: videos.example.com
Date: Tue, 07 Jun 2017 20:51:35 GMT
Content-Type: application/json
{
"type": "PaymentResponse",
"description": "Payment to ExampleMerch for widgets",
"paymentTerms": {
"paymentMethod": "https://payments.example.org/payment-schemes#Visa",
"status": "authorized",
"token": "10025AB",
"paymentAmount": {
"amount": "2.99",
"currency": "USD"
}
}
}
HTTP/1.1 302 Found
Date: Tue, 07 Jun 2017 20:51:36 GMT
Cookie: movieToken=2983fhfa92h3iuhf908723nkjcsdh923; Expires=Tue, 08 Jun 2017 20:51:40 GMT
Location: /movies/dr-strangelove
The Working Group is currently in the early stages of the analysis of the security and privacy implications of this specification. The ongoing analysis can be accessed via the Web Payments Working Group Security and Privacy Considerations wiki .
This section is non-normative.
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