This HTTP header will help newcomers start using Bitcoins, even they don’t know anything about it.
The purpose of the Browser Payment App HTTP Request Header is to inform a web server what payment capabilities a visitor has. By having this information, a web server can adjust the payment handling so it best fits the visitor’s payment capabilities.
The HTTP request header is typical sent by a payment app which has been installed in the visitor’s web browser. Example of such payment app is the Banking App, which is part of the Bitcoin Cheque project.
The payment capabilities provided by a visitor can be used to pay for reading web content at a newspaper or for purchasing goods at a web-shop. The payment can be made in Bitcoin or in other crypto currencies. The payment procedure itself is not a part of this standard document.
The main motivation for having this HTTP header, is for the web server to know whatever the visitor have a payment app installed or not. If the header is missing, then the web server can adjust the page and send the visitor to an alternative payment site. At this site the visitor can make the payment or download a payment app. This is actual an very important feature, as it will give all visitor a possibility to pay, whatever they are using Bitcoin or not. In that way this header can help mass adaptions of Bitcoins.
List your browser HTTP headers
Typical, a Browser Payment App HTTP Request Header looks like this:
This header tells us that the visitor can pay using Cheque Payment Protocol and Payment Cheque holding Bitcoin.
You can list your own browser’s HTTP request header here:
The Browser Payment App HTTP Request Header Standard is based upon the following requirements and premises:
- The HTTP header must inform what payment capabilities a visitor can provide and if the visitor has installed
- a payment app that are using the Cheque Payment Protocol and what versions of Payment Cheque it can handle;
- a payment app supporting the Bitcoin BIP-70 Payment Protocol has been installed;
- a “traditional pre-BIP-70” Bitcoin wallet has been installed;
- and if a visitor has several payment capabilities, the header must be able to inform all capabilities;
- and if several capabilities exist, these must be listed in a prioritize order.
- The HTTP header must inform what currency the visitor can pay and
- all currencies as listed in the ISO 4217 must be supported;
- other crypto-currencies used by the community that is not listed in the ISO 4217 must also be supported;
- if a visitor can pay with several currencies, the header must be able to list all of them;
- and if several currencies are be provided, the header must be able to list them in a prioritized order.
- The web-server must be able to understand if user has no payment capabilities.
- The HTTP header must be compact to reduce the traffic load. (The header will be sent in every HTTP requests.)
- New payment protocols and new cheque specifications may be develop in the future. This standard must allow for a wide variety of developments, both what can be expected and what is of a more unforeseen nature.
- Visitor’s payment app may become outdated and use old versions of the header standard. The web server must be able to read what version the header is.
- Web server may become outdated and visitors may use newer HTTP header versions than what the web server have implemented. If the new release is only of minor matter, the web server should be able to read and understand the previous versions part of it. This can be updates like added currencies, new payment cheque versions etc.
The standard document
Below is the current draft of the standard. It can also be found on Github:
This document defines version 1.0 of the Browser Payment App HTTP Request Header standard.
The purpose of the Browser Payment App HTTP Request Header is to inform a web server of what payment capabilities a visitor has. By having this information, a web server can adjust the payment handling so it best fits the visitor's payment capabilities.
The HTTP request headers are typical sent by a Payment App installed in the visitor's web browser. The purpose of the Payment App is to be able to make payments to a web server. This can be payments for reading web content or for purchasing goods. The payment can be made in Bitcoin or in other crypto currencies. The payment procedure itself is not a part of this standard document.
2 HTTP request header
This chapter defines the Browser Payment App HTTP Request Header.
2.1 Header field name
The header field name shall be "Payment-App".
2.2 Header field values
The header field value is a string of comma separated attributes. The set of attributes can describe one or several payment capabilities.
Each attribute has an attribute key and an attribute value.
For example, this header field value holds four attributes:
Here 'v', 'pp', 'pq', and 'cc' are the Attribute Keys and '1', '1-4', '1;2' and 'BTC' are the attribute values.
The following table lists attribute keys as defined by this standard.
2.2.1 Browser Payment App HTTP Request Header Version attribute - v
This attribute indicates the major version number of the Browser Payment App HTTP Request Header.
This attribute value shall a number.
Note: The version tag consists of a major number and minor number. Major version 1 of this standard shall be compatible with future minor-release of this standard. See chapter 4 for version compatibility details.
2.2.2 Payment Protocols supported attribute - pp
The purpose of this attribute is to indicate what Bitcoin Payment Protocols are supported.
This attribute value shall a number.
If Payment Protocol is set to 3, then it is also required to include the Payment Cheque Specification Version attribute.
The value can be a single number, a comma separated prioritized list of numbers, or a prioritized range of numbers or a combination as described in section Attribute Value listings.
2.2.3 Payment Cheque Specification supported attribute - pq
The purpose of this attribute is to indicate what versions of the Bitcoin Cheque Specification is supported by the browser.
This attribute value shall a number.
When Payment Cheque Specification is set to 1, then also the Payment Currency attribute is required.
Note: Currently only one version of the Payment Cheque Specification exists. If in the future new versions are created, a payment app may support several of them. In case more than one version are supported, the versions must be listed as comma separated list or as a range or as combined list and range.
2.2.4 ISO 4217 Currency code supported attribute - ic
This attribute indicates the currencies that the payment app can provide.
This attribute's value shall be a string consisting of alphanumeric characters of the currency code as specified in ISO 4217.
An payment app may support several currencies. If more than one currency is supported, the currencies must be listed as a comma separated attrbute values.
2.2.5 Community crypto-currency code supported attribute - cc
This attribute indicates the currencies that the payment app can provide. The currency code will be as commonly agreed in the crypto-currency community.
This attribute's value shall be a string consisting alphanumeric characters.
Note: As there is no official list of crypto-currency codes, this attribute is not recommended. If this attribute is used it is recommended to use the crypto-currency codes as listed at https://coinmarketcap.com.
An payment app may support several currencies. If more than one currency is supported, the currencies must be listed as a comma separated list.
2.3 Attribute value listing
If an attribute supports more than one value at a time, these can be listed as comma separated lists or as a range or as a combination of list and range.
The following sections defines the listing rules.
2.3.1 Semi-colon separated list
If an attribute supports several values, these values can be listed by comma separations. If the value can be prioritized or some value are preferred over others, the values listed first have higher priority or are the preferred one.
For example, the following attribute
has two attribute values that indicates possible payment currencies are BTC and ETH. BTC are listed first and therefore is the preferred one.
The purpose of arranging a list as a range is to reduce the payload. If an attribute has several consecutive attribute value, it should be arranged as a range.
Range are only allowed for attribute values of integer number type.
The following is an example of a attribute holding three attribute values; 1, 2 and 3.
If the attribute values shall be prioritized, the values in the range having highest priority shall be listed first. In the following example, attribute value 3 has higher priority than value 2 which again has higher priority than value 1:
2.3.3 Combined lists and ranges
Lists and ranges can be combined. The items coming first has the highest priority.
In the following example, the priority order is 3,2,1,4. 3 has highest priority. 4 has lowest priority:
Note: Item 4 in this example is a Payment Protocol that is currently not defined. It is only included to make up this example.
3 Description of usage
This chapter describes how to use the Browser Payment App HTTP Request Header.
3.1 Announcing payment capabilities
The following example indicates the visitor is capable of paying Payment Cheques holding Bitcoin using the Cheque Payment Protocol:
The folloing example indicates the visitor is capable of paying using Bitcoin Payment Protocol as described in BIP-70. This protcol don't use the Payment Cheque so the pq attribute is not needed. This protocol is for Bitcoin payments only, which makes the ic and cc attrbute redundant and hence these attrbiutes are not needed.
The following example indicates the visitor is capable of using both of the two payments method above. pp attribute 3 is listed first meaning that Cheque Payment is prefered Payment Protocol. The pq and ic attribute is required and only used by pp attribute 3.
3.2 Announcing no payment capability
If no Payment App is installed in a browser or the browser supports no Payment Protocols as defined by this standard, the browser may implement the Browser Payment HTTP Request Header anyway. In this case the Payment Protocol must be set to 0.
The Payment Protocol 0 shall be treated equal as no Browser Payment HTTP Request Header is sent.
3.3 Convert to JSON
The Payment App Browser HTTP Request Header can easily be converted into a JSON format.
This is done bay by taking the HTTP Request Header field value string and make the following string operation on it:
As an example, after the string operations the following HTTP Request Header:
will be converted to this JSON string:
4 Future versions and compatibility
This version of the Browser Payment App HTTP Request Header shall be expected to be compatible with future minor-release updated versions. In future minor-release update of this standard, additional Payment Protocols and Payment Cheque Specifications Attribute Values may be added.
Additional Attribute Keys shall not be added in minor-release updates nor shall the purpose of existing keys be changed. New Attribute Keys will require a major-release update of this standard.
Web Servers implementing this standard and receiving a Browser Payment HTTP Request Header version 1, should be able to handle future and today unknown Attribute Values in an appropriate way. In most cases that may be to reject it and announce to the visitor that it cannot accept that type of payment.