http-payments.xml

<?xml version="1.0" encoding="utf-8"?>
  <?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
  <!-- generated by https://github.com/cabo/kramdown-rfc2629 version 1.2.7 -->

<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC4648 SYSTEM "https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.4648.xml">
<!ENTITY RFC7231 SYSTEM "https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7231.xml">
<!ENTITY W3C.CR-payment-request-20170921 SYSTEM "https://xml2rfc.tools.ietf.org/public/rfc/bibxml4/reference.W3C.CR-payment-request-20170921.xml">
<!ENTITY W3C.CR-payment-method-id-20170914 SYSTEM "https://xml2rfc.tools.ietf.org/public/rfc/bibxml4/reference.W3C.CR-payment-method-id-20170914.xml">
]>

<?rfc toc="yes"?>
<?rfc sortrefs="yes"?>
<?rfc symrefs="yes"?>
<?rfc comments="yes"?>

<rfc docName="draft-hope-bailie-http-payments-01" category="std">

  <front>
    <title>HTTP-Payments</title>

    <author initials="A." surname="Hope-Bailie" fullname="Adrian Hope-Bailie">
      <organization>Ripple</organization>
      <address>
        <postal>
          <street>315 Montgomery Street</street>
          <city>San Francisco</city>
          <region>CA</region>
          <code>94104</code>
          <country>US</country>
        </postal>
        <phone>-----------------</phone>
        <email>adrian@ripple.com</email>
        <uri>https://www.ripple.com</uri>
      </address>
    </author>

    <date year="2017" month="November" day="03"/>

    <area>dispatch</area>
    
    

    <abstract>


<t>HTTP-Payments describes a mechanism for passing a standardized payment request in the headers of an HTTP 402 response and the expected behaviour of HTTP clients that receive such a response.</t>



    </abstract>


    <note title="Feedback">


<t>This specification is an early experiment in bringing the work of the W3C Web Payments working group to the HTTP protocol. It is maintained at <eref target="https://github.com/adrianhopebailie/http-payments">https://github.com/adrianhopebailie/http-payments</eref>.</t>

<t>The work is inspired by work in the Interledger community on <xref target="HTTP-ILP"></xref></t>


    </note>


  </front>

  <middle>


<section anchor="introduction" title="Introduction">

<t>The W3C Web Payments working group has defined a Web Platform API that is being widely deployed to browsers for requesting a payment. The <xref target="W3C.CR-payment-request-20170921">PaymentRequest API</xref>, defines an interface for a website to pass a payment request to the user agent via this API.</t>

<t>The user agent will then, through interaction with the user, complete or reject the requested payment.</t>

<t>HTTP-Payments describes a manner in which an HTTP server can request payment from a client in the same manner as a website would from a user agent using the W3C APIs.</t>

<t>The critical portion of the payment request is the set of, one or more, supported payment methods and associated payment-method-specific data. HTTP-Payments defines a mechaism by which these are expressed in the response headers of an HTTP request for which the server requires a payment.</t>

<t>In the website and user-agent scenario, when handling the payment request, the user-agent will prompt the user to pick one of the supported payment methods and will then handle the payment in a manner that is appropriate for that payment method. In an HTTP-Payment, the HTTP client will perform this function, likely with no user interaction.</t>

</section>
<section anchor="terminology" title="Terminology">

<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119][].</t>

</section>
<section anchor="payment-methods" title="Payment Methods">

<t>A payment method is a way that the payee can be paid. Examples include, via credit card, bank wire transfer, or Bitcoin.</t>

<t>A payment method is identified by a payment method identifier as specified in the <xref target="W3C.CR-payment-method-id-20170914">Payment Method Identifiers specification</xref>. This is either a standardized short-string, identified in a registry maintained by the W3C Web Payments WG, or a URL.</t>

<t>The most common case will be for the URL form to be used. In cases where there is no authority responsible for the payment method that can host the payment method URL, the WG will consider adding a new identifier for the payment method to the registry.</t>

<t>Payment methods define the data that the payer and payee need to exchange, to complete a payment, and the process by which this occurs.</t>

</section>
<section anchor="http-status-code-402" title="HTTP Status Code 402">

<t>The HTTP Status Code, 402 (Payment Required) is currently defined in <xref target="RFC7231"></xref> as "reserved for future use". Using HTTP-Payment a service MAY respond to any request with the 402 response code and use the "Pay" header to specify the payment request details.</t>

<section anchor="the-pay-header" title="The &quot;Pay&quot; Header">

<t>The body of the "Pay" header is defined as follows:</t>

<figure><artwork type="abnf" align="left" name="pay-header-abnf"><![CDATA[
    Pay = 1#( payment-method-identifier RWS payment-amount RWS payment-address [ RWS
    payment-method-data ] )

    payment-method-identifier = token
    payment-amount = 1*DIGIT
    payment-address = token
    payment-method-data -token

    ;token is defined in [RFC7231](#RFC7231)
]]></artwork></figure>

<t>The Pay field-value consists of a comma-separated list of payment requests for payment using different payment methods accepted by the sender.</t>

<t>The fields in the header are:</t>

<t><list style="symbols">
  <t>payment-method-identifier:
The payment method identifier for the accepted payment method. Either a standardized short-string or a URL.</t>
  <t>payment-amount:
The amount that must be paid, expressed as an integer. The currency, scale and precision of the destination account are expected to be expressed in the account address or interprted from the payment mthod data.</t>
  <t>payment-address:
A payment-method specific payee address. For example, if the payment method is Bitcoin this would be a Bitcoin address.</t>
  <t>payment-method-data:
Optional payment method specific data. This is either a URI identifying the data or, if it is small enough, is the data itself, BASE64URL encoded as described in <xref target="RFC4648"></xref>, Section 5.</t>
</list></t>

</section>
<section anchor="the-pay-token-header" title="The &quot;Pay-Token&quot; Header">

<t>An HTTP client that makes a paid-HTTP request, after paying for the request to be processed, MAY attach a "Pay-Token" header with a token referencing the payment.</t>

<t>This mechanism can be employed by services wishing to accept payments without binding these to an HTTP session.</t>

<figure><artwork type="abnf" align="left" name="pay-token-header-abnf"><![CDATA[
    Pay-Token = token
]]></artwork></figure>

</section>
<section anchor="the-pay-balance-header" title="The &quot;Pay-Balance&quot; Header">

<t>Ann HTTP Service that accepts payments may respond to any request with a "Pay-Balance" header. This contains an integer indicating the current balance of paid credit the client has with the HTTP service.</t>

<figure><artwork type="abnf" align="left" name="pay-balance-header-abnf"><![CDATA[
    Pay-Balance = 1*DIGIT
]]></artwork></figure>

</section>
<section anchor="flow" title="Flow">

<t>Upon receipt of a 402 response, an HTTP client MUST look for any "Pay" headers and parse these. The client can discard all headers for which it is not equipped to make a payment (i.e. filter on payment-method-identifier)</t>

<t>The client MUST then select the header that is preferred for processing based upon external interactions (such as with a human user) or pre-configured rules. The client MUST attempt to make a payment using the payment method identified in the header, for the amount specified, and to the destination address specified.</t>

<t>The payment-method specific data SHOULD be sufficient for the system processing the payment to reconcile the payment with the original HTTP request.</t>

<t>The client SHOULD receive a token in return for completeing the payment. If the payment method used does return a token to the payer, it MUST pass this token in subsequent HTTP requests.</t>

<t>The token MUST be passed in the "Pay-Token" header, BASE64URL encoded as described in <xref target="RFC4648"></xref>, Section 5.</t>

<t>The HTTP service MUST process the "Pay-Token" header and use this to reconcile this HTTP request with the payment received prior.</t>

</section>
<section anchor="example" title="Example">

<t>Client requests access to a paid resource:</t>

<figure><artwork type="http" align="left" name="example-request"><![CDATA[
    POST /upload HTTP/1.1
    Host: myservice.example
]]></artwork></figure>

<t>Server responds with payment request (and optionally indicates that the client has a zero balance):</t>

<figure><artwork type="http" align="left" name="example-402-response"><![CDATA[
    HTTP/1.1 402 Payment Required
    Pay: http://interledger.org 10 us.nexus.ankita.~recv.filepay SkTcFTZCBKgP6A6QOUVcwWCCg
    Pay-Balance: 0
]]></artwork></figure>

<t>Client makes the payment through an appropriate payment side-channel and then attempts the request again:</t>

<figure><artwork type="http" align="left" name="example-request-2"><![CDATA[
    POST /upload HTTP/1.1
    Host: myservice.example
    Pay-Token: 7y0SfeN7lCuq0GFF5UsMYZofIjJ7LrvPvsePVWSv450
]]></artwork></figure>

<t>Server responds:</t>

<figure><artwork type="http" align="left" name="example-200-response"><![CDATA[
    HTTP/1.1 200 Success
    Pay-Balance: 0  
]]></artwork></figure>

</section>
</section>


  </middle>

  <back>

    <references title='Normative References'>

&RFC4648;
&RFC7231;
&W3C.CR-payment-request-20170921;
&W3C.CR-payment-method-id-20170914;


    </references>

    <references title='Informative References'>

<reference anchor="HTTP-ILP" target="https://github.com/interledger/rfcs/blob/master/0014-http-ilp/0014-http-ilp.md">
  <front>
    <title>HTTP-ILP</title>
    <author >
      <organization>Interledger Community Group</organization>
    </author>
    <date year="2017" month="October"/>
  </front>
</reference>


    </references>


<section anchor="security-considerations" title="Security Considerations">

<t>Payment information MUST not be exchanged on a connection that is not secured end-to-end. Servers that receive any HTTP payment header over an insecure connection should reject the request. Clients that receive any HTTP Payment headers over an insecure connection MUST ignore the headers.</t>

</section>
<section anchor="iana-considerations" title="IANA Considerations">

<section anchor="header-field-registration" title="Header Field Registration">

<t>HTTP header fields are registered within the "Message Headers"
   registry maintained at
   <eref target="http://www.iana.org/assignments/message-headers/">http://www.iana.org/assignments/message-headers/</eref>.</t>

<t>This document defines the following new HTTP header fields.</t>

<texttable>
      <ttcol align='left'>Header Field Name</ttcol>
      <ttcol align='left'>Protocol</ttcol>
      <ttcol align='left'>Status</ttcol>
      <ttcol align='left'>Reference</ttcol>
      <c>Pay</c>
      <c>http</c>
      <c>?</c>
      <c>This Document</c>
      <c>Pay-Token</c>
      <c>http</c>
      <c>?</c>
      <c>This Document</c>
      <c>Pay-Balance</c>
      <c>http</c>
      <c>?</c>
      <c>This Document</c>
</texttable>

<t>The change controller is: "IETF (iesg@ietf.org) - Internet
   Engineering Task Force".</t>

</section>
<section anchor="payment-method-identifier-short-string-registry" title="Payment Method Identifier Short-string Registry">

<t>The W3C maintains a registry of standardized short-string payment method identifiers as part of the <xref target="W3C.CR-payment-method-id-20170914">Payment Method Identifier</xref> specification. If standardized short-string identifiers are to be used for HTTP-Payments this may be better served as an IANA registry.</t>

</section>
</section>


  </back>

<!-- ##markdown-source:
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

-->

</rfc>