Abstract

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.

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.

1. Introduction

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.

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:

Note

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 [ WEBPAYMENTS-HTTP-MESSAGES].

1.2 Terminology

Issue 3: HTTP API terminology needs to be refined

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:

payee
An entity that receives funds as required by a transaction.
payer
An entity that provides a source of funds as required by a transaction.
payment
[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
payment app
A payment app is a component able to process a payment request and return a payment response.
payment mediator
[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.
payment method
[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.
payment request
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.
payment response
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.

Basic tokenized card payment flow
Fig. 1 - A basic tokenized card payment flow.
Issue 4: Overview diagram may be misleading

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.

  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. The payment mediator fetches the request from the URL specified in the Location header in the previous step.
  3. The payment mediator scans the list of previously registered payment apps and finds matches against paymentTerms in the payment request.
  4. A payment app is selected by the payment mediator or the payer. The process MAY consist of one or more of the following steps:
    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.
    1. If there is only one app that matches, that is automatically set to the selected payment app.
    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. 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. 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. 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:
    1. Let "selectedApp" be the payment app selected by the payment mediator.
    2. Let "selectedMethod" be the payment method provided by the payee and selected by the payer.
    3. If selectedMethod.paymentRequestService exists, re-direct the user there (payee-based PSP).
    4. If selectedApp.paymentRequestService exists, re-direct the user there (payer-based PSP).
    5. Otherwise, the payment response can be generated locally (local PSP - Bitcoin and others).
  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 mediator forwards the request, via an HTTP POST to the paymentRequestService in the payment app for approval.
  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 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).
  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. 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:
    1. Funds transfer was initiated and completed. Clearly 200, right?
    2. Funds transfer was initiated, but network delay may cause it to fail at a later point in time (ACH, etc.). 102 or 202?
    3. Request for subscription was noted and is setup, but no funds were moved. 200?
    4. Payment submitted to network, but network didn't respond with an auth code. 504?
    5. 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

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

4.2 Initiating a Payment Request

  1. The payer's HTTP client accesses a resource that requires payment:
    Example 4: Payer requests a resource that requires a payment
    GET /movies/dr-strangelove HTTP/1.1
    Host: videos.example.com
    Date: Tue, 07 Jun 2017 21:31:35 GMT
  2. The payee's HTTP server responds with a 402 Payment Required response and the URL where the payment request may be fetched via the Location header:
    Example 5: Payee responds with 402 Payment Required
    HTTP/1.1 402 Payment Required
    Date: Tue, 07 Jun 2017 21:31:36 GMT
    Location: https://videos.example.com/payment-requests/dr-strangelove
    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.
  3. The payer's HTTP client accesses the payment request resource:
    Example 6: Payer requests a payment request
    GET /payment-requests/dr-strangelove HTTP/1.1
    Host: videos.example.com
    Date: Tue, 07 Jun 2017 21:31:37 GMT
  4. The payee server provides the payment request.
    Example 7: Payee provides the payment request
    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"
    }

4.3 Generating a Payment Response

  1. A payment app is selected by the payment mediator to process the payment request generated in the previous section.
  2. 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
    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"
    }
  3. The payment service provider generates a payment response message that contains enough information to verify that the transaction has completed in success or failure:
    Example 9: The payment response is provided back to the payment mediator from the payment app
    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"
        }
      }
    }
  4. The payment response is then relayed back to the payee by the payment mediator using the paymentCompleteService URL provided in the initial payment request:
    Example 10: The payment response is relayed back to the payee by the payment mediator
    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"
        }
      }
    }
  5. The payee validates the payment response, sets the appropriate access control for the resource, and re-directs the payer to the resource:
    Example 11: The payee grants access to the initially requested resource
    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

4.4 Security and Privacy Considerations

Issue 13: What are the security and privacy implications of the HTTP API?

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 .

A. Acknowledgements

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

B. References

B.1 Normative references

[WEBPAYMENTS-HTTP-MESSAGES]
Manu Sporny; Dave Longley; Shane McCarron. W3C. Web Payments HTTP Messages 1.0. W3C First Public Working Draft. URL: https://www.w3.org/TR/webpayments-http-messages/