Plain Text #

To specify an amount directly for copying and pasting, you must provide the Address, the amount, and the Denomination. An expiration time for the offer may also be specified. For example:

(Note: all examples in this section use Testnet addresses.)

Pay: mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN
Amount: 100 BTC
You must pay by: 2014-04-01 at 23:00 UTC

Indicating the Denomination is critical. As of this writing, popular Bitcoin Wallet software defaults to denominating amounts in either Bitcoins (BTC) , millibitcoins (mBTC) or microbitcoins (uBTC, “bits”). Choosing between each unit is widely supported, but other software also lets its users select Denomination amounts from some preselected (e.g. Table below) or all standard 8 decimal places:

bitcoin: URI #

The “bitcoin:” URI scheme defined in BIP21 eliminates Denomination confusion and saves the spender from copying and pasting two separate values. It also lets the Payment request provide some additional information to the spender. An example:

bitcoin:mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN?amount=100

Only the Address is required, and if it is the only thing specified, wallets will pre-fill a Payment request with it and let the spender enter an amount. The amount specified is always in decimal Bitcoins (BTC).

Two other parameters are widely supported. The “Label” parameter is generally used to provide Wallet software with the recipient’s name. The “Message” parameter is generally used to describe the Payment request to the spender. Both the Label and the Message are commonly stored by the spender’s Wallet software—but they are never added to the actual transaction, so other Bitcoin users cannot see them. Both the Label and the Message must be URI encoded.

All four parameters used together, with appropriate URI encoding, can be seen in the line-wrapped example below.

bitcoin:mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN
?amount=0.10
&Label=Example+Merchant
&Message=Order+of+flowers+%26+chocolates

The URI scheme can be extended, as will be seen in the Payment protocol section below, with both new optional and required parameters. As of this writing, the only widely-used parameter besides the four described above is the Payment protocol’s “r” parameter.

Programs accepting URIs in any form must ask the user for permission before paying unless the user has explicitly disabled prompting (as might be the case for micropayments).

QR Codes #

QR codes are a popular way to exchange “bitcoin:” URIs in person, in images, or in videos. Most mobile Bitcoin Wallet apps, and some desktop wallets, support scanning QR codes to pre-fill their payment screens.

The figure below shows the same “bitcoin:” URI code encoded as four different Bitcoin QR codes at four different error correction levels. The QR code can include the “Label” and “Message” parameters—and any other optional parameters—but they were omitted here to keep the QR code small and easy to scan with unsteady or low-resolution mobile cameras.

Bitcoin QR Codes

The error correction is combined with a checksum to ensure the Bitcoin QR code cannot be successfully decoded with data missing or accidentally altered, so your applications should choose the appropriate level of error correction based on the space you have available to display the code. Low-level damage correction works well when space is limited, and quartile-level damage correction helps ensure fast scanning when displayed on high-resolution screens.

Payment protocol #

Warning: The Payment protocol is considered to be deprecated and will be removed in a later version of Bitcoin Core. The protocol has multiple security design flaws and implementation flaws in some wallets. Users will begin receiving deprecation warnings in Bitcoin Core version 0.18 when using BIP70 URI’s. Merchants should transition away from BIP70 to more secure options such as BIP21. Merchants should never require BIP70 payments and should provide BIP21 fallbacks.

Bitcoin Core 0.9 supports the new Payment protocol. The Payment protocol adds many important features to payment requests:

• Supports X.509 certificates and SSL encryption to verify receivers’ identity and help prevent man-in-the-middle attacks.

• Provides more detail about the requested payment to spenders.

• Allows spenders to submit transactions directly to receivers without going through the Peer-to-Peer network. This can speed up payment processing and work with planned features such as child-pays-for-parent transaction fees and offline NFC or Bluetooth-based payments.

Instead of being asked to pay a meaningless Address, such as “mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN”, spenders are asked to pay the Common Name (CN) description from the receiver’s X.509 certificate, such as “www.bitcoin.org”.

To request payment using the Payment protocol, you use an extended (but backwards-compatible) “bitcoin:” URI. For example:

bitcoin:mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN
?amount=0.10
&Label=Example+Merchant
&Message=Order+of+flowers+%26+chocolates
&r=https://example.com/pay/mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN

None of the parameters provided above, except “r”, are required for the Payment protocol—but your applications may include them for backwards compatibility with Wallet programs which don’t yet handle the Payment protocol.

The “r” parameter tells payment-protocol-aware Wallet programs to ignore the other parameters and fetch a PaymentRequest from the URL provided. The browser, QR code reader, or other program processing the URI opens the spender’s Bitcoin Wallet program on the URI.

BIP70 Payment protocol

The Payment protocol is described in depth in BIP70, BIP71, and BIP72. An example CGI program and description of all the parameters which can be used in the Payment protocol is provided in the Developer Examples Payment protocol subsection. In this subsection, we will briefly describe in story format how the Payment protocol is typically used.

Charlie, the client, is shopping on a website run by Bob, the businessman. Charlie adds a few items to his shopping cart and clicks the “Checkout With Bitcoin” button.

Bob’s server automatically adds the following information to its invoice database:

• The details of Charlie’s order, including items ordered and shipping Address.

• An order total in Satoshis, perhaps created by converting prices in Fiat to prices in Satoshis.

• An expiration time when that total will no longer be acceptable.

• A Pubkey script to which Charlie should send payment. Typically this will be a P2PKH or P2SH Pubkey script containing a unique (never before used) secp256k1 Public key.

After adding all that information to the database, Bob’s server displays a “bitcoin:” URI for Charlie to click to pay.

Charlie clicks on the “bitcoin:” URI in his browser. His browser’s URI handler sends the URI to his Wallet program. The Wallet is aware of the Payment protocol, so it parses the “r” parameter and sends an HTTP GET to that URL looking for a PaymentRequest Message.

The PaymentRequest Message returned may include private information, such as Charlie’s mailing Address, but the Wallet must be able to access it without using prior authentication, such as HTTP cookies, so a publicly accessible HTTPS URL with a guess-resistant part is typically used. The unique Public key created for the Payment request can be used to create a unique identifier. This is why, in the example URI above, the PaymentRequest URL contains the P2PKH Address: https://example.com/pay/mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN

After receiving the HTTP GET to the URL above, the PaymentRequest-generating CGI program on Bob’s webserver takes the unique identifier from the URL and looks up the corresponding details in the database. It then creates a PaymentDetails Message with the following information:

• The amount of the order in Satoshis and the Pubkey script to be paid.

• A memo containing the list of items ordered, so Charlie knows what he’s paying for. It may also include Charlie’s mailing Address so he can double-check it.

• The time the PaymentDetails Message was created plus the time it expires.

• A URL to which Charlie’s Wallet should send its completed transaction.

That PaymentDetails Message is put inside a PaymentRequest Message. The Payment request lets Bob’s server sign the entire Request with the server’s X.509 SSL certificate. (The Payment protocol has been designed to allow other signing methods in the future.) Bob’s server sends the Payment request to Charlie’s Wallet in the reply to the HTTP GET.

Bitcoin Core Showing Validated Payment request

Charlie’s Wallet receives the PaymentRequest Message, checks its Signature, and then displays the details from the PaymentDetails Message to Charlie. Charlie agrees to pay, so the Wallet constructs a payment to the Pubkey script Bob’s server provided. Unlike a traditional Bitcoin payment, Charlie’s Wallet doesn’t necessarily automatically broadcast this payment to the network. Instead, the Wallet constructs a Payment Message and sends it to the URL provided in the PaymentDetails Message as an HTTP POST. Among other things, the Payment Message contains:

• The signed transaction in which Charlie pays Bob.

• An optional memo Charlie can send to Bob. (There’s no guarantee that Bob will read it.)

• A refund Address (Pubkey script) which Bob can pay if he needs to return some or all of Charlie’s Satoshis.

Bob’s server receives the Payment Message, verifies the transaction pays the requested amount to the Address provided, and then broadcasts the transaction to the network. It also replies to the HTTP POSTed Payment Message with a PaymentACK Message, which includes an optional memo from Bob’s server thanking Charlie for his patronage and providing other information about the order, such as the expected arrival date.

Charlie’s Wallet sees the PaymentACK and tells Charlie that the payment has been sent. The PaymentACK doesn’t mean that Bob has verified Charlie’s payment—see the Verifying Payment subsection below—but it does mean that Charlie can go do something else while the transaction gets confirmed. After Bob’s server verifies from the Block chain that Charlie’s transaction has been suitably confirmed, it authorizes shipping Charlie’s order.

In the case of a dispute, Charlie can generate a cryptographically proven Receipt out of the various signed or otherwise-proven information.

• The PaymentDetails Message signed by Bob’s webserver proves Charlie received an invoice to pay a specified Pubkey script for a specified number of Satoshis for goods specified in the memo field.

• The Bitcoin Block chain can prove that the Pubkey script specified by Bob was paid the specified number of Satoshis.

If a refund needs to be issued, Bob’s server can safely pay the refund-to Pubkey script provided by Charlie. See the Refunds section below for more details.

Merge Avoidance #

When a receiver receives Satoshis in an Output, the spender can track (in a crude way) how the receiver spends those Satoshis. But the spender can’t automatically see other Satoshis paid to the receiver by other spenders as long as the receiver uses unique addresses for each transaction.

However, if the receiver spends Satoshis from two different spenders in the same transaction, each of those spenders can see the other spender’s payment. This is called a Merge, and the more a receiver merges outputs, the easier it is for an outsider to track how many Satoshis the receiver has earned, spent, and saved.

Merge avoidance means trying to avoid spending unrelated outputs in the same transaction. For persons and businesses which want to keep their transaction data secret from other people, it can be an important strategy.

A crude Merge avoidance strategy is to try to always pay with the smallest Output you have which is larger than the amount being requested. For example, if you have four outputs holding, respectively, 100, 200, 500, and 900 Satoshis, you would pay a bill for 300 Satoshis with the 500-satoshi Output. This way, as long as you have outputs larger than your bills, you avoid merging.

More advanced Merge avoidance strategies largely depend on enhancements to the Payment protocol which will allow payers to avoid merging by intelligently distributing their payments among multiple outputs provided by the receiver.

Last In, First Out (LIFO) #

Outputs can be spent as soon as they’re received—even before they’re confirmed. Since recent outputs are at the greatest risk of being double-spent, spending them before older outputs allows the spender to hold on to older confirmed outputs which are much less likely to be double-spent.

There are two closely-related downsides to LIFO:

• If you spend an Output from one Unconfirmed transaction in a second transaction, the second transaction becomes invalid if Transaction malleability changes the first transaction.

• If you spend an Output from one Unconfirmed transaction in a second transaction and the first transaction’s Output is successfully double spent to another Output, the second transaction becomes invalid.

In either of the above cases, the receiver of the second transaction will see the incoming transaction notification disappear or turn into an error Message.

Because LIFO puts the recipient of secondary transactions in as much double-spend risk as the recipient of the primary transaction, they’re best used when the secondary recipient doesn’t care about the risk—such as an exchange or other service which is going to wait for six Confirmations whether you spend old outputs or new outputs.

LIFO should not be used when the primary transaction recipient’s reputation might be at stake, such as when paying employees. In these cases, it’s better to wait for transactions to be fully verified (see the Verification subsection above) before using them to make payments.

First In, First Out (FIFO) #

The oldest outputs are the most reliable, as the longer it’s been since they were received, the more blocks would need to be modified to Double spend them. However, after just a few blocks, a point of rapidly diminishing returns is reached. The original Bitcoin paper predicts the chance of an attacker being able to modify old blocks, assuming the attacker has 30% of the total network hashing power:

FIFO does have a small advantage when it comes to transaction fees, as older outputs may be eligible for inclusion in the 50,000 bytes set aside for no-fee-required high-priority transactions by miners running the default Bitcoin Core codebase. However, with transaction fees being so low, this is not a significant advantage.

The only practical use of FIFO is by receivers who spend all or most of their income within a few blocks, and who want to reduce the chance of their payments becoming accidentally invalid. For example, a receiver who holds each payment for six Confirmations, and then spends 100% of verified payments to vendors and a savings account on a bi-hourly schedule.