Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
172 lines (105 sloc) 9.49 KB

1 Introduction

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:

v:1,pp:1-4,pq:1;2,cc:BTC

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.

Attribute key Required Description
v Mandatory Indicates the major version number of this standard
pp Mandatory Indicates Payment Protocol supported
pq Optional Indicates the Bitcoin Cheque Specification supported by the Payment App.
ic Optional Indicates preferred currency as defined by ISO 4217.
cc Optional Indicates preferred currency as defined by the crypto-currency community.

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.

Version Description
1 HTTP request header is major version 1.

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.

Payment Protocol Description
0 Indicates no Bitcoin Payment is supported.
1 Indicates traditional "Pre-BIP-70" payment is supported
2 Indicates browser supports Bitcoin Payment Protocol as described in BIP-70
3 Indicates browser supports Cheque Payment Protocol

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.

Payment Cheque Spec. Ver. Description
1 Indicates Payment Cheque Specification Version 1 is supported.

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

cc:BTC,ETH

has two attribute values that indicates possible payment currencies are BTC and ETH. BTC are listed first and therefore is the preferred one.

2.3.2 Ranges

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.

pp=1-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:

pp=3-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:

pp=3-1,4

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:

v:1,pp:3,pq:1,ic:XBT

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.

v:1,pp:1

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.

v:1,pp:3;1,pq:1,ic:XBT

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:

  • Prefix the string with a start curly brace and quotation mark ({")
  • Postfix the string with a quotation mark and end curly brace ("})
  • Replace colon (:) with quotation mark, colon and quotation mark (":")
  • Replace comma (,) with quotation mark, comma and quotation mark (",")

As an example, after the string operations the following HTTP Request Header:

v:1,pp:3-2,pq:1,cc:BTC;ETH

will be converted to this JSON string:

{"v":"1","pp":"3-2","pq":"1","cc":"BTC;ETH"}

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.

You can’t perform that action at this time.