diff --git a/proposals/web-payments-http-api/index.html b/proposals/web-payments-http-api/index.html new file mode 100644 index 0000000..425e6d9 --- /dev/null +++ b/proposals/web-payments-http-api/index.html @@ -0,0 +1,543 @@ + + + + Web Payments HTTP API 1.0 + + + + + + + + + + +
+

+This document outlines how to register payment apps, request payments, +and acknowledge payment requests using a standard HTTP API. +

+
+ +
+ +

There are a number of ways that one may participate in the development of + this specification:

+ + +
+ +
+

Introduction

+ +

+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. +

+
+

How to Read this Document

+ +

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:

+ + +
+
+

Terminology

+ +

+The terminology in this specification's terminology and messages need to be +updated to match the +Payments Architecture document. +

+ +
+
+ +
+ +
+ +
+

Payment Flow Overview

+ +

+The diagram below outlines a basic HTTP client payment flow with no errors. +The basic flow starts out with the payer accessing a protected resource. +The payee provides a location where a payment request for the resource +can be fetched. The payer fetches the payment request, selects +a payment app, and sends the request and the selected app +on to the appropriate payment service provider for processing. The +payment service provider initiates the payment and sends a +payment request acknowledgement back to the payer. The payer +then forwards the payment request acknowledgement back to the +payee. If there are no errors, the payee then grants access to +the resource that was purchased. +

+ +

+The flow below reflects a fairly advanced tokenized payment scenario. We may +want to use a simpler basic credit card flow where the customer doesn't have +a payment service provider and just returns the credit card details to the +merchant. +

+ + + +

+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. +

+ +
    +
  1. +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. +
    2. +
  2. +The payment agent fetches the request from the URL specified +in the Location header in the previous step. +
    3. +
  3. +The payment agent scans the list of previously registered payment apps +and finds matches against acceptedMethods in the +payment request. +
    4. +
  4. +A payment app is selected by the payment agent or the payer. The +process MAY consist of one or more of the following steps: +
      +
    1. +If there is only one app that matches, that is automatically set +to the selected payment app. +
      2. +
    2. +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. +
      3. +
    3. +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 +
      4. +
    4. +If there are no matches, the payer is notified and may be taken to an +alternate flow where a matching payment app is acquired. +
      5. +
    +
    5. +
  5. +If the payment app does not require the payment flow to switch +to a 3rd party payment processor (e.g. cryptocurrency), +then the payment acknowledgement is generated locally and the +payee's software is notified. +
    6. +
  6. +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): +
      +
    1. +The payment agent forwards the request, and +selected payment app via an HTTP POST to the +paymentRequestService in the payment app for approval. +
      2. +
    +
    7. +
  7. +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): +
      +
    1. +The payment agent forwards the request on via an HTTP POST +to the paymentRequestService in the +acceptedMethod (note that the payee +sets this, not the payment app). +
      2. +
    +
    8. +
  8. +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). +
    9. +
  9. +Once the entity in control of the payment flow finalizes the +payment acknowledgement, even if the message is to +acknowledge that the payment failed, the payment acknowledgement +is generated and the payer's payment agent is notified via an HTTP 200 +success 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. +

+

+The diagram below outlines the basic payment flow described above for a +push-based payment. +

+
+ +
+

Detailed Payment Flow

+

+Describe the payment flow in detail here using Adrian's flow diagram and Ian's +steps. +

+ +
+

Payment app Registration

+
    +
  1. +The payer's HTTP client navigates to a payment service provider website +and authenticates itself to fetch a payment app to register: + 
    +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", ...
+
    +
    +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: + 
    +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="
+
    +
    +
    2. +
  2. +The payment service provider MUST respond with the payment app or +an HTTP error code. If successful, something like the following will be +returned: + 
    +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"
+}
+
    +
    3. +
+
+ +
+

Processing a Payment Request

+
    +
  1. +The payer's HTTP client accesses a resource that requires payment: + 
    +GET /movies/dr-strangelove HTTP/1.1
+Host: videos.example.com
+Date: Tue, 07 Jun 2017 21:31:35 GMT
+
    +
    2. +
  2. +The payee server notifies the payer that a payment is required along with a +payment request. + 
    +HTTP/1.1 402 Payment Required
+Date: Tue, 07 Jun 2017 21:31:36 GMT
+Content-Type: application/json
+Content-Length: 873
+
+{
+  "type": "PaymentRequest",
+  "description": "Payment for Dr. Strangelove",
+  "acceptedMethod": {
+    "paymentMethod": "https://payments.example.org/payment-schemes#Visa",
+    "transfer": {
+      "amount": "2.99",
+      "currency": "USD"
+    },
+    "destination": "20389472398"
+  },
+  "paymentCompleteService": "https://videos.example.com/services/paymentComplete?transaction=923847298"
+}
+
    +
    3. +
+
+ +
+

Processing a Payment Acknowledgement

+
    +
  1. +The payment service provider receives a 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",
+  "acceptedMethod": {
+    "paymentMethod": "https://payments.example.org/payment-schemes#Visa",
+    "transfer": {
+      "amount": "2.99",
+      "currency": "USD"
+    },
+    "destination": "20389472398"
+  },
+  "paymentCompleteService": "https://videos.example.com/services/paymentComplete?transaction=923847298"
+}
+
    +
    2. +
  2. +The payment service provider generates a payment acknowledgement +message, which is a [[!JSON-LD]] object that contains enough information to +verify that the transaction has completed in success or failure: + 
    +HTTP/1.1 200 OK
+Date: Tue, 07 Jun 2017 20:51:36 GMT
+Content-Type: application/json
+Content-Length: 623
+
+{
+  "type": "PaymentAcknowledgement",
+  "description": "Payment to ExampleMerch for widgets",
+  "selectedScheme": {
+    "paymentMethod": "https://payments.example.org/payment-schemes#Visa",
+    "status": "authorized",
+    "token": "10025AB",
+    "transfer": {
+      "amount": "2.99",
+      "currency": "USD"
+    },
+    "destination": "20389472398"
+  }
+}
+
    +
    3. +
  3. +The payment acknowledgement is then relayed back to the payer: + 
    +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": "PaymentAcknowledgement",
+  "description": "Payment to ExampleMerch for widgets",
+  "selectedScheme": {
+    "paymentMethod": "https://payments.example.org/payment-schemes#Visa",
+    "status": "authorized",
+    "token": "10025AB",
+    "transfer": {
+      "amount": "2.99",
+      "currency": "USD"
+    },
+    "destination": "20389472398"
+  }
+}
+
    +
    4. +
  4. +The payee validates the payment acknowledgement, sets the appropriate +access control for the resource, and re-directs the payer to the +resource: + 
    +HTTP/1.1 302 Found
+Date: Tue, 07 Jun 2017 20:51:36 GMT
+Location: /movies/dr-strangelove
+
    +
    5. +
+
+ +
+

Message Extensibility

+ +

+One proposal for providing message extensibility is to allow messages to +be interpreted as JSON-LD with a specific context, such as +https://example.org/contexts/web-payments/v1. Doing this would +not only solve message versioning, but it would also enable +decentralized extensibility for all payment messages while ensuring that +there are no clashes in terminology between industry verticals. +

+
+ +
+

Security Considerations

+ +
+

Message Integrity

+

+There are a variety of ways that message integrity can be protected. Which +set of methods will this specification employ. +

+
+ +
+

Message Replay

+

+There are a variety of ways that message replay can be protected against. Which +set of methods will this specification employ. +

+
+
+ +
+ +
+

Acknowledgements

+ +

+The editor would like to thank the Web Payments Community Group, and the +Web Payments Interest Group. +

+ +

+Thanks to the following individuals, in order of their first name, for +their input on the specification: ... +

+ +
+ + + + + + + diff --git a/proposals/web-payments-http-api/spec.css b/proposals/web-payments-http-api/spec.css new file mode 100644 index 0000000..9597ebe --- /dev/null +++ b/proposals/web-payments-http-api/spec.css @@ -0,0 +1,3 @@ +ol.algorithm { counter-reset:numsection; list-style-type: none; } +ol.algorithm li { margin: 0.5em 0; } +ol.algorithm li:before { font-weight: bold; counter-increment: numsection; content: counters(numsection, ".") ") "; } diff --git a/proposals/web-payments-http-api/utils.js b/proposals/web-payments-http-api/utils.js new file mode 100644 index 0000000..e68ee83 --- /dev/null +++ b/proposals/web-payments-http-api/utils.js @@ -0,0 +1,49 @@ +// We should be able to remove terms that are not actually +// referenced from the common definitions +var termNames = [] ; + +function restrictReferences(utils, content) { + var base = document.createElement("div"); + base.innerHTML = content; + + // strategy: Traverse the content finding all of the terms defined + $.each(base.querySelectorAll("dfn"), function(i, item) { + var $t = $(item) ; + var titles = $t.getDfnTitles(); + var n = $t.makeID("dfn", titles[0]); + if (n) { + termNames[n] = $t.parent() ; + } + }); + + // add a handler to come in after all the definitions are resolved + + respecEvents.sub('end', function(message) { + if (message == 'core/link-to-dfn') { + // all definitions are linked + $("a.internalDFN").each(function () { + var $item = $(this) ; + var r = $item.attr('href').replace(/^#/,"") ; + if (termNames[r]) { + delete termNames[r] ; + } + }); + // delete any terms that were not referenced. + Object.keys(termNames).forEach(function(term) { + var $p = $("#"+term) ; + if ($p) { + var tList = $p.getDfnTitles(); + $p.parent().next().remove(); + $p.remove() ; + tList.forEach(function( item ) { + if (respecConfig.definitionMap[item]) { + delete respecConfig.definitionMap[item]; + } + }); + } + }); + } + }); + + return (base.innerHTML); +} \ No newline at end of file