Payment Processing

22 min read

Payment Processing #

Payment processing encompasses the steps spenders and receivers perform to make and accept payments in exchange for products or services. The basic steps have not changed since the dawn of commerce, but the technology has.

Introduction #

This section will explain how receivers and spenders can, respectively, request and make payments using Bitcoin—and how they can deal with complications such as refunds and recurrent rebilling.

Bitcoin Payment Processing

The figure above illustrates payment processing using Bitcoin from a receiver’s perspective, starting with a new order. The following subsections will each Address

A 20-byte hash formatted using base58check to produce either a P2PKH or P2SH Bitcoin address. Currently the most common way users exchange payment information.

Not to be confused with: IP address

the three common steps and the three occasional or optional steps.

It is worth mentioning that each of these steps can be outsourced by using third party APIs and services.

Pricing Orders #

Because of exchange rate variability between Satoshis

Denominations of Bitcoin value, usually measured in fractions of a bitcoin but sometimes measured in multiples of a satoshi. One bitcoin equals 100,000,000 satoshis.

Not to be confused with: Binary bits, a unit of data with two possible values

and national currencies (), many Bitcoin orders are priced in but paid in , necessitating a price conversion.

Exchange rate data is widely available through HTTP-based APIs provided by currency exchanges. Several organizations also aggregate data from multiple exchanges to create index prices, which are also available using HTTP-based APIs.

Any applications which automatically calculate order totals using exchange rate data must take steps to ensure the price quoted reflects the current general market value of Satoshis

Denominations of Bitcoin value, usually measured in fractions of a bitcoin but sometimes measured in multiples of a satoshi. One bitcoin equals 100,000,000 satoshis.

Not to be confused with: Binary bits, a unit of data with two possible values

, or the applications could accept too few for the product or service being sold. Alternatively, they could ask for too many , driving away potential spenders.

To minimize problems, your applications may want to collect data from at least two separate sources and compare them to see how much they differ. If the difference is substantial, your applications can enter a safe mode until a human is able to evaluate the situation.

You may also want to program your applications to enter a safe mode if exchange rates are rapidly increasing or decreasing, indicating a possible problem in the Bitcoin market which could make it difficult to spend any Satoshis

Denominations of Bitcoin value, usually measured in fractions of a bitcoin but sometimes measured in multiples of a satoshi. One bitcoin equals 100,000,000 satoshis.

Not to be confused with: Binary bits, a unit of data with two possible values

received today.

Exchange rates lie outside the control of Bitcoin and related technologies, so there are no new or planned technologies which will make it significantly easier for your program to correctly convert order totals from Fiat

National currencies such as the dollar or euro.

into .

Because the exchange rate fluctuates over time, order totals pegged to Fiat

National currencies such as the dollar or euro.

must expire to prevent spenders from delaying payment in the hope that will drop in price. Most widely-used payment processing systems currently expire their invoices after 10 to 20 minutes.

Shorter expiration periods increase the chance the invoice will expire before payment is received, possibly necessitating manual intervention to request an additional payment or to issue a refund. Longer expiration periods increase the chance that the exchange rate will fluctuate a significant amount before payment is received.

Requesting Payments #

Before requesting payment, your application must create a Bitcoin Address

A 20-byte hash formatted using base58check to produce either a P2PKH or P2SH Bitcoin address. Currently the most common way users exchange payment information.

Not to be confused with: IP address

, or acquire an from another program such as Bitcoin Core. Bitcoin addresses are described in detail in the Transactions guide. Also described in that section are two important reasons to avoid using an more than once—but a third reason applies especially to payment requests:

Using a separate Address

A 20-byte hash formatted using base58check to produce either a P2PKH or P2SH Bitcoin address. Currently the most common way users exchange payment information.

Not to be confused with: IP address

for each incoming payment makes it trivial to determine which customers have paid their payment requests. Your applications need only track the association between a particular and the used in it, and then scan the chain for transactions matching that .

The next subsections will describe in detail the following four compatible ways to give the spender the Address

A 20-byte hash formatted using base58check to produce either a P2PKH or P2SH Bitcoin address. Currently the most common way users exchange payment information.

Not to be confused with: IP address

and amount to be paid. For increased convenience and compatibility, providing all of these options in your payment requests is recommended.

All Wallet
Software that stores private keys and monitors the block chain (sometimes as a client of a server that does the processing) to allow users to spend and receive satoshis.
Not to be confused with: HD wallet (a protocol that allows all of a wallet’s keys to be created from a single seed)
software lets its users paste in or manually enter an Address
A 20-byte hash formatted using base58check to produce either a P2PKH or P2SH Bitcoin address. Currently the most common way users exchange payment information.
Not to be confused with: IP address
and amount into a payment screen. This is, of course, inconvenient—but it makes an effective fallback option.
Almost all desktop wallets can associate with “bitcoin:” URIs, so spenders can click a link to pre-fill the payment screen. This also works with many mobile wallets, but it generally does not work with web-based wallets unless the spender installs a browser extension or manually configures a URI handler.
Most mobile wallets support scanning “bitcoin:” URIs encoded in a QR code, and almost all wallets can display them for accepting payment. While also handy for online orders, QR Codes are especially useful for in-person purchases.
Recent Wallet
Software that stores private keys and monitors the block chain (sometimes as a client of a server that does the processing) to allow users to spend and receive satoshis.
Not to be confused with: HD wallet (a protocol that allows all of a wallet’s keys to be created from a single seed)
updates add support for the new Payment protocol
The deprecated protocol defined in BIP70 (and other BIPs) which lets spenders get signed payment details from receivers.
Not to be confused with: IP-to-IP payment protocol (an insecure, discontinued protocol included in early versions of Bitcoin)
providing increased security, authentication of a receiver’s identity using X.509 certificates, and other important features such as refunds.

Warning icon Warning: Special care must be taken to avoid the theft of incoming payments. In particular, private keys should not be stored on web servers, and payment requests should be sent over HTTPS or other secure methods to prevent man-in-the-middle attacks from replacing your Bitcoin Address

A 20-byte hash formatted using base58check to produce either a P2PKH or P2SH Bitcoin address. Currently the most common way users exchange payment information.

Not to be confused with: IP address

with the attacker’s .

Plain Text #

To specify an amount directly for copying and pasting, you must provide the Address

A 20-byte hash formatted using base58check to produce either a P2PKH or P2SH Bitcoin address. Currently the most common way users exchange payment information.

Not to be confused with: IP address

, the amount, and the . An expiration time for the offer may also be specified. For example:

(Note: all examples in this section use Testnet

A global testing environment in which developers can obtain and spend satoshis that have no real-world value on a network that is very similar to the Bitcoin mainnet.

Not to be confused with: Regtest (a local testing environment where developers can control block generation)

addresses.)

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

Indicating the Denomination

Denominations of Bitcoin value, usually measured in fractions of a bitcoin but sometimes measured in multiples of a satoshi. One bitcoin equals 100,000,000 satoshis.

Not to be confused with: Binary bits, a unit of data with two possible values

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

Bitcoins Denominations of Bitcoin value, usually measured in fractions of a bitcoin but sometimes measured in multiples of a satoshi. One bitcoin equals 100,000,000 satoshis. Not to be confused with: Binary bits, a unit of data with two possible values	Unit (Abbreviation)
1.0	bitcoin (BTC)
0.01	bitcent (cBTC)
0.001	millibitcoin (mBTC)
0.000001	microbitcoin (uBTC, “bits”)
0.0000001	finney
0.00000001	satoshi

bitcoin: URI #

The “bitcoin:” URI scheme defined in BIP21 eliminates Denomination

Denominations of Bitcoin value, usually measured in fractions of a bitcoin but sometimes measured in multiples of a satoshi. One bitcoin equals 100,000,000 satoshis.

Not to be confused with: Binary bits, a unit of data with two possible values

confusion and saves the spender from copying and pasting two separate values. It also lets the provide some additional information to the spender. An example:

bitcoin:mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN?amount=100

Only the Address

A 20-byte hash formatted using base58check to produce either a P2PKH or P2SH Bitcoin address. Currently the most common way users exchange payment information.

Not to be confused with: IP address

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

Two other parameters are widely supported. The “Label

The label parameter of a bitcoin: URI which provides the spender with the receiver’s name (unauthenticated).

” parameter is generally used to provide software with the recipient’s name. The “” parameter is generally used to describe the to the spender. Both the and the are commonly stored by the spender’s software—but they are never added to the actual transaction, so other Bitcoin users cannot see them. Both the and the 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
The label parameter of a bitcoin: URI which provides the spender with the receiver’s name (unauthenticated).
=Example+Merchant
&Message
A parameter of bitcoin: URIs which allows the receiver to optionally specify a message to the spender.
=Order+of+flowers+%26+chocolates

The URI scheme can be extended, as will be seen in the Payment protocol

The deprecated protocol defined in BIP70 (and other BIPs) which lets spenders get signed payment details from receivers.

Not to be confused with: IP-to-IP payment protocol (an insecure, discontinued protocol included in early versions of Bitcoin)

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 ’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

Software that stores private keys and monitors the block chain (sometimes as a client of a server that does the processing) to allow users to spend and receive satoshis.

Not to be confused with: HD wallet (a protocol that allows all of a wallet’s keys to be created from a single seed)

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

The label parameter of a bitcoin: URI which provides the spender with the receiver’s name (unauthenticated).

” and “” 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
The deprecated protocol defined in BIP70 (and other BIPs) which lets spenders get signed payment details from receivers.
Not to be confused with: IP-to-IP payment protocol (an insecure, discontinued protocol included in early versions of Bitcoin)
#

Warning icon Warning: The Payment protocol

The deprecated protocol defined in BIP70 (and other BIPs) which lets spenders get signed payment details from receivers.

Not to be confused with: IP-to-IP payment protocol (an insecure, discontinued protocol included in early versions of Bitcoin)

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 deprecated protocol defined in BIP70 (and other BIPs) which lets spenders get signed payment details from receivers.

Not to be confused with: IP-to-IP payment protocol (an insecure, discontinued protocol included in early versions of Bitcoin)

. The 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
A computer that connects to the Bitcoin network.
Not to be confused with: Lightweight node, SPV node
-to-Peer
A computer that connects to the Bitcoin network.
Not to be confused with: Lightweight node, SPV node
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

A 20-byte hash formatted using base58check to produce either a P2PKH or P2SH Bitcoin address. Currently the most common way users exchange payment information.

Not to be confused with: IP 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

The deprecated protocol defined in BIP70 (and other BIPs) which lets spenders get signed payment details from receivers.

Not to be confused with: IP-to-IP payment protocol (an insecure, discontinued protocol included in early versions of Bitcoin)

, you use an extended (but backwards-compatible) “bitcoin:” URI. For example:

bitcoin:mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN
?amount=0.10
&Label
The label parameter of a bitcoin: URI which provides the spender with the receiver’s name (unauthenticated).
=Example+Merchant
&Message
A parameter of bitcoin: URIs which allows the receiver to optionally specify a message to the spender.
=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

The deprecated protocol defined in BIP70 (and other BIPs) which lets spenders get signed payment details from receivers.

Not to be confused with: IP-to-IP payment protocol (an insecure, discontinued protocol included in early versions of Bitcoin)

—but your applications may include them for backwards compatibility with programs which don’t yet handle the .

The “r” parameter tells payment-protocol-aware Wallet

Software that stores private keys and monitors the block chain (sometimes as a client of a server that does the processing) to allow users to spend and receive satoshis.

Not to be confused with: HD wallet (a protocol that allows all of a wallet’s keys to be created from a single seed)

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 program on the URI.

BIP70 Payment protocol

The deprecated protocol defined in BIP70 (and other BIPs) which lets spenders get signed payment details from receivers.

Not to be confused with: IP-to-IP payment protocol (an insecure, discontinued protocol included in early versions of Bitcoin)

The Payment protocol

The deprecated protocol defined in BIP70 (and other BIPs) which lets spenders get signed payment details from receivers.

Not to be confused with: IP-to-IP payment protocol (an insecure, discontinued protocol included in early versions of Bitcoin)

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 is provided in the Developer Examples subsection. In this subsection, we will briefly describe in story format how the 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
A 20-byte hash formatted using base58check to produce either a P2PKH or P2SH Bitcoin address. Currently the most common way users exchange payment information.
Not to be confused with: IP address
.
An order total in Satoshis
Denominations of Bitcoin value, usually measured in fractions of a bitcoin but sometimes measured in multiples of a satoshi. One bitcoin equals 100,000,000 satoshis.
Not to be confused with: Binary bits, a unit of data with two possible values
, perhaps created by converting prices in Fiat
National currencies such as the dollar or euro.
to prices in Satoshis
Denominations of Bitcoin value, usually measured in fractions of a bitcoin but sometimes measured in multiples of a satoshi. One bitcoin equals 100,000,000 satoshis.
Not to be confused with: Binary bits, a unit of data with two possible values
.
An expiration time when that total will no longer be acceptable.
A Pubkey script
A script included in outputs which sets the conditions that must be fulfilled for those satoshis to be spent. Data for fulfilling the conditions can be provided in a signature script. Pubkey Scripts are called a scriptPubKey in code.
Not to be confused with: Pubkey (a public key, which can be used as part of a pubkey script but don’t provide a programmable authentication mechanism), Signature script (a script that provides data to the pubkey script)
to which Charlie should send payment. Typically this will be a P2PKH or P2SH Pubkey script
A script included in outputs which sets the conditions that must be fulfilled for those satoshis to be spent. Data for fulfilling the conditions can be provided in a signature script. Pubkey Scripts are called a scriptPubKey in code.
Not to be confused with: Pubkey (a public key, which can be used as part of a pubkey script but don’t provide a programmable authentication mechanism), Signature script (a script that provides data to the pubkey script)
containing a unique (never before used) secp256k1 Public key
The public portion of a keypair which can be used to verify signatures made with the private portion of the keypair.
Not to be confused with: Private key (data from which the public key is derived), Parent key (a key used to create child keys, not necessarily a 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

Software that stores private keys and monitors the block chain (sometimes as a client of a server that does the processing) to allow users to spend and receive satoshis.

Not to be confused with: HD wallet (a protocol that allows all of a wallet’s keys to be created from a single seed)

program. The is aware of the , so it parses the “r” parameter and sends an HTTP GET to that URL looking for a PaymentRequest .

The PaymentRequest Message

A parameter of bitcoin: URIs which allows the receiver to optionally specify a message to the spender.

returned may include private information, such as Charlie’s mailing , but the 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 created for the can be used to create a unique identifier. This is why, in the example URI above, the PaymentRequest URL contains the P2PKH : 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

A parameter of bitcoin: URIs which allows the receiver to optionally specify a message to the spender.

with the following information:

The amount of the order in Satoshis
Denominations of Bitcoin value, usually measured in fractions of a bitcoin but sometimes measured in multiples of a satoshi. One bitcoin equals 100,000,000 satoshis.
Not to be confused with: Binary bits, a unit of data with two possible values
and the Pubkey script
A script included in outputs which sets the conditions that must be fulfilled for those satoshis to be spent. Data for fulfilling the conditions can be provided in a signature script. Pubkey Scripts are called a scriptPubKey in code.
Not to be confused with: Pubkey (a public key, which can be used as part of a pubkey script but don’t provide a programmable authentication mechanism), Signature script (a script that provides data to 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
A 20-byte hash formatted using base58check to produce either a P2PKH or P2SH Bitcoin address. Currently the most common way users exchange payment information.
Not to be confused with: IP address
so he can double-check it.
The time the PaymentDetails Message
A parameter of bitcoin: URIs which allows the receiver to optionally specify a message to the spender.
was created plus the time it expires.
A URL to which Charlie’s Wallet
Software that stores private keys and monitors the block chain (sometimes as a client of a server that does the processing) to allow users to spend and receive satoshis.
Not to be confused with: HD wallet (a protocol that allows all of a wallet’s keys to be created from a single seed)
should send its completed transaction.

That PaymentDetails Message

A parameter of bitcoin: URIs which allows the receiver to optionally specify a message to the spender.

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

Bitcoin Core Showing Validated Payment request

The deprecated protocol defined in BIP70 (and other BIPs) which lets spenders get signed payment details from receivers.

Not to be confused with: IP-to-IP payment protocol (an insecure, discontinued protocol included in early versions of Bitcoin)

Charlie’s Wallet

Software that stores private keys and monitors the block chain (sometimes as a client of a server that does the processing) to allow users to spend and receive satoshis.

Not to be confused with: HD wallet (a protocol that allows all of a wallet’s keys to be created from a single seed)

receives the PaymentRequest , checks its , and then displays the details from the PaymentDetails to Charlie. Charlie agrees to pay, so the constructs a payment to the Bob’s server provided. Unlike a traditional Bitcoin payment, Charlie’s doesn’t necessarily automatically broadcast this payment to the network. Instead, the constructs a Payment and sends it to the URL provided in the PaymentDetails as an HTTP POST. Among other things, the Payment 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
A 20-byte hash formatted using base58check to produce either a P2PKH or P2SH Bitcoin address. Currently the most common way users exchange payment information.
Not to be confused with: IP address
(Pubkey script
A script included in outputs which sets the conditions that must be fulfilled for those satoshis to be spent. Data for fulfilling the conditions can be provided in a signature script. Pubkey Scripts are called a scriptPubKey in code.
Not to be confused with: Pubkey (a public key, which can be used as part of a pubkey script but don’t provide a programmable authentication mechanism), Signature script (a script that provides data to the pubkey script)
) which Bob can pay if he needs to return some or all of Charlie’s Satoshis
Denominations of Bitcoin value, usually measured in fractions of a bitcoin but sometimes measured in multiples of a satoshi. One bitcoin equals 100,000,000 satoshis.
Not to be confused with: Binary bits, a unit of data with two possible values
.

Bob’s server receives the Payment Message

A parameter of bitcoin: URIs which allows the receiver to optionally specify a message to the spender.

, verifies the transaction pays the requested amount to the provided, and then broadcasts the transaction to the network. It also replies to the HTTP POSTed Payment with a PaymentACK , 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

Software that stores private keys and monitors the block chain (sometimes as a client of a server that does the processing) to allow users to spend and receive satoshis.

Not to be confused with: HD wallet (a protocol that allows all of a wallet’s keys to be created from a single seed)

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 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

A cryptographically-verifiable receipt created using parts of a payment request and a confirmed transaction.

out of the various signed or otherwise-proven information.

The PaymentDetails Message
A parameter of bitcoin: URIs which allows the receiver to optionally specify a message to the spender.
signed by Bob’s webserver proves Charlie received an invoice to pay a specified Pubkey script
A script included in outputs which sets the conditions that must be fulfilled for those satoshis to be spent. Data for fulfilling the conditions can be provided in a signature script. Pubkey Scripts are called a scriptPubKey in code.
Not to be confused with: Pubkey (a public key, which can be used as part of a pubkey script but don’t provide a programmable authentication mechanism), Signature script (a script that provides data to the pubkey script)
for a specified number of Satoshis
Denominations of Bitcoin value, usually measured in fractions of a bitcoin but sometimes measured in multiples of a satoshi. One bitcoin equals 100,000,000 satoshis.
Not to be confused with: Binary bits, a unit of data with two possible values
for goods specified in the memo field.
The Bitcoin Block
One or more transactions prefaced by a block header and protected by proof of work. Blocks are the data stored on the block chain.
chain can prove that the Pubkey script
A script included in outputs which sets the conditions that must be fulfilled for those satoshis to be spent. Data for fulfilling the conditions can be provided in a signature script. Pubkey Scripts are called a scriptPubKey in code.
Not to be confused with: Pubkey (a public key, which can be used as part of a pubkey script but don’t provide a programmable authentication mechanism), Signature script (a script that provides data to the pubkey script)
specified by Bob was paid the specified number of Satoshis
Denominations of Bitcoin value, usually measured in fractions of a bitcoin but sometimes measured in multiples of a satoshi. One bitcoin equals 100,000,000 satoshis.
Not to be confused with: Binary bits, a unit of data with two possible values
.

If a refund needs to be issued, Bob’s server can safely pay the refund-to Pubkey script

A script included in outputs which sets the conditions that must be fulfilled for those satoshis to be spent. Data for fulfilling the conditions can be provided in a signature script. Pubkey Scripts are called a scriptPubKey in code.

Not to be confused with: Pubkey (a public key, which can be used as part of a pubkey script but don’t provide a programmable authentication mechanism), Signature script (a script that provides data to the pubkey script)

provided by Charlie. See the Refunds section below for more details.

Verifying Payment #

As explained in the Transactions and Block

One or more transactions prefaced by a block header and protected by proof of work. Blocks are the data stored on the block chain.

Chain sections, broadcasting a transaction to the network doesn’t ensure that the receiver gets paid. A malicious spender can create one transaction that pays the receiver and a second one that pays the same back to himself. Only one of these transactions will be added to the chain, and nobody can say for sure which one it will be.

Two or more transactions spending the same Input

An input in a transaction which contains three fields: an outpoint, a signature script, and a sequence number. The outpoint references a previous output and the signature script allows spending it.

are commonly referred to as a .

Once the transaction is included in a Block

One or more transactions prefaced by a block header and protected by proof of work. Blocks are the data stored on the block chain.

, double spends are impossible without modifying chain history to replace the transaction, which is quite difficult. Using this system, the Bitcoin protocol can give each of your transactions an updating confidence score based on the number of blocks which would need to be modified to replace a transaction. For each , the transaction gains one confirmation. Since modifying blocks is quite difficult, higher confirmation scores indicate greater protection.

0 Confirmations

A score indicating the number of blocks on the best block chain that would need to be modified to remove or modify a particular transaction. A confirmed transaction has a confirmation score of one or higher.

: The transaction has been broadcast but is still not included in any . Zero confirmation transactions (unconfirmed transactions) should generally not be trusted without risk analysis. Although miners usually confirm the first transaction they receive, fraudsters may be able to manipulate the network into including their version of a transaction.

1 confirmation: The transaction is included in the latest Block

One or more transactions prefaced by a block header and protected by proof of work. Blocks are the data stored on the block chain.

and double-spend risk decreases dramatically. Transactions which pay sufficient transaction fees need 10 minutes on average to receive one confirmation. However, the most recent gets replaced fairly often by accident, so a is still a real possibility.

2 Confirmations

: The most recent was chained to the which includes the transaction. As of March 2014, two replacements were exceedingly rare, and a two replacement attack was impractical without expensive equipment.

6 Confirmations

: The network has spent about an hour working to protect the transaction against double spends and the transaction is buried under six blocks. Even a reasonably lucky attacker would require a large percentage of the total network hashing power to replace six blocks. Although this number is somewhat arbitrary, software handling high-value transactions, or otherwise at risk for fraud, should wait for at least six before treating a payment as accepted.

Bitcoin Core provides several RPCs which can provide your program with the Confirmation score

for transactions in your or arbitrary transactions. For example, the “listunspent” RPC provides an array of every satoshi you can spend along with its .

Although Confirmations

provide excellent double-spend protection most of the time, there are at least three cases where double-spend risk analysis can be required:

In the case when the program or its user cannot wait for a confirmation and wants to accept unconfirmed payments.
In the case when the program or its user is accepting high value transactions and cannot wait for at least six Confirmations
A score indicating the number of blocks on the best block chain that would need to be modified to remove or modify a particular transaction. A confirmed transaction has a confirmation score of one or higher.
or more.
In the case of an implementation bug or prolonged attack against Bitcoin which makes the system less reliable than expected.

An interesting source of double-spend risk analysis can be acquired by connecting to large numbers of Bitcoin peers to track how transactions and blocks differ from each other. Some third-party APIs can provide you with this type of service.

For example, unconfirmed transactions can be compared among all connected peers to see if any UTXO

An Unspent Transaction Output (UTXO) that can be spent as an input in a new transaction.

Not to be confused with: Output (any output, whether spent or not. Outputs are a superset of UTXOs)

is used in multiple unconfirmed transactions, indicating a double-spend attempt, in which case the payment can be refused until it is confirmed. Transactions can also be ranked by their to estimate the amount of time until they’re added to a .

Another example could be to detect a Fork

When two or more blocks have the same block height, forking the block chain. Typically occurs when two or more miners find blocks at nearly the same time. Can also happen as part of an attack.

Not to be confused with: Hard fork (a change in consensus rules that breaks security for nodes that don’t upgrade), Soft fork (a change in consensus rules that weakens security for nodes that don’t upgrade), Software fork (when one or more developers permanently develops a codebase separately from other developers), Git fork (when one or more developers temporarily develops a codebase separately from other developers)

when multiple peers report differing hashes at the same . Your program can go into a safe mode if the extends for more than two blocks, indicating a possible problem with the chain. For more details, see the Detecting Forks subsection.

Another good source of double-spend protection can be human intelligence. For example, fraudsters may act differently from legitimate customers, letting savvy merchants manually flag them as high risk. Your program can provide a safe mode which stops automatic payment acceptance on a global or per-customer basis.

Issuing Refunds #

Occasionally receivers using your applications will need to issue refunds. The obvious way to do that, which is very unsafe, is simply to return the Satoshis

Denominations of Bitcoin value, usually measured in fractions of a bitcoin but sometimes measured in multiples of a satoshi. One bitcoin equals 100,000,000 satoshis.

Not to be confused with: Binary bits, a unit of data with two possible values

to the from which they came. For example:

Alice wants to buy a widget from Bob, so Bob gives Alice a price and Bitcoin Address
A 20-byte hash formatted using base58check to produce either a P2PKH or P2SH Bitcoin address. Currently the most common way users exchange payment information.
Not to be confused with: IP address
.
Alice opens her Wallet
Software that stores private keys and monitors the block chain (sometimes as a client of a server that does the processing) to allow users to spend and receive satoshis.
Not to be confused with: HD wallet (a protocol that allows all of a wallet’s keys to be created from a single seed)
program and sends some Satoshis
Denominations of Bitcoin value, usually measured in fractions of a bitcoin but sometimes measured in multiples of a satoshi. One bitcoin equals 100,000,000 satoshis.
Not to be confused with: Binary bits, a unit of data with two possible values
to that Address
A 20-byte hash formatted using base58check to produce either a P2PKH or P2SH Bitcoin address. Currently the most common way users exchange payment information.
Not to be confused with: IP address
. Her Wallet
Software that stores private keys and monitors the block chain (sometimes as a client of a server that does the processing) to allow users to spend and receive satoshis.
Not to be confused with: HD wallet (a protocol that allows all of a wallet’s keys to be created from a single seed)
program automatically chooses to spend those Satoshis
Denominations of Bitcoin value, usually measured in fractions of a bitcoin but sometimes measured in multiples of a satoshi. One bitcoin equals 100,000,000 satoshis.
Not to be confused with: Binary bits, a unit of data with two possible values
from one of its unspent outputs, an Output
An output in a transaction which contains two fields: a value field for transferring zero or more satoshis and a pubkey script for indicating what conditions must be fulfilled for those satoshis to be further spent.
Not to be confused with: Outpoint (a reference to a particular output)
corresponding to the Bitcoin Address
A 20-byte hash formatted using base58check to produce either a P2PKH or P2SH Bitcoin address. Currently the most common way users exchange payment information.
Not to be confused with: IP address
mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN.
Bob discovers Alice paid too many Satoshis
Denominations of Bitcoin value, usually measured in fractions of a bitcoin but sometimes measured in multiples of a satoshi. One bitcoin equals 100,000,000 satoshis.
Not to be confused with: Binary bits, a unit of data with two possible values
. Being an honest fellow, Bob refunds the extra Satoshis
Denominations of Bitcoin value, usually measured in fractions of a bitcoin but sometimes measured in multiples of a satoshi. One bitcoin equals 100,000,000 satoshis.
Not to be confused with: Binary bits, a unit of data with two possible values
to the mjSk… Address
A 20-byte hash formatted using base58check to produce either a P2PKH or P2SH Bitcoin address. Currently the most common way users exchange payment information.
Not to be confused with: IP address
.

This seems like it should work, but Alice is using a centralized multi-user web Wallet

Software that stores private keys and monitors the block chain (sometimes as a client of a server that does the processing) to allow users to spend and receive satoshis.

Not to be confused with: HD wallet (a protocol that allows all of a wallet’s keys to be created from a single seed)

which doesn’t give unique addresses to each user, so it has no way to know that Bob’s refund is meant for Alice. Now the refund is a unintentional donation to the company behind the centralized , unless Alice opens a support ticket and proves those were meant for her.

This leaves receivers only two correct ways to issue refunds:

If an Address
A 20-byte hash formatted using base58check to produce either a P2PKH or P2SH Bitcoin address. Currently the most common way users exchange payment information.
Not to be confused with: IP address
was copy-and-pasted or a basic “bitcoin:” URI was used, contact the spender directly and ask them to provide a refund Address
A 20-byte hash formatted using base58check to produce either a P2PKH or P2SH Bitcoin address. Currently the most common way users exchange payment information.
Not to be confused with: IP address
.
If the Payment protocol
The deprecated protocol defined in BIP70 (and other BIPs) which lets spenders get signed payment details from receivers.
Not to be confused with: IP-to-IP payment protocol (an insecure, discontinued protocol included in early versions of Bitcoin)
was used, send the refund to the Output
An output in a transaction which contains two fields: a value field for transferring zero or more satoshis and a pubkey script for indicating what conditions must be fulfilled for those satoshis to be further spent.
Not to be confused with: Outpoint (a reference to a particular output)
listed in the refund_to field of the Payment Message
A parameter of bitcoin: URIs which allows the receiver to optionally specify a message to the spender.
.

Note: it would be wise to contact the spender directly if the refund is being issued a long time after the original payment was made. This allows you to ensure the user still has access to the key or keys for the refund_to Address

A 20-byte hash formatted using base58check to produce either a P2PKH or P2SH Bitcoin address. Currently the most common way users exchange payment information.

Not to be confused with: IP address

Disbursing Income (Limiting Forex Risk) #

Many receivers worry that their Satoshis

Denominations of Bitcoin value, usually measured in fractions of a bitcoin but sometimes measured in multiples of a satoshi. One bitcoin equals 100,000,000 satoshis.

Not to be confused with: Binary bits, a unit of data with two possible values

will be less valuable in the future than they are now, called foreign exchange (forex) risk. To limit forex risk, many receivers choose to disburse newly-acquired payments soon after they’re received.

If your application provides this business logic, it will need to choose which outputs to spend first. There are a few different algorithms which can lead to different results.

A Merge
Spending, in the same transaction, multiple outputs which can be traced back to different previous spenders, leaking information about how many satoshis you control.
avoidance algorithm makes it harder for outsiders looking at Block
One or more transactions prefaced by a block header and protected by proof of work. Blocks are the data stored on the block chain.
chain data to figure out how many Satoshis
Denominations of Bitcoin value, usually measured in fractions of a bitcoin but sometimes measured in multiples of a satoshi. One bitcoin equals 100,000,000 satoshis.
Not to be confused with: Binary bits, a unit of data with two possible values
the receiver has earned, spent, and saved.
A last-in-first-out (LIFO) algorithm spends newly acquired Satoshis
Denominations of Bitcoin value, usually measured in fractions of a bitcoin but sometimes measured in multiples of a satoshi. One bitcoin equals 100,000,000 satoshis.
Not to be confused with: Binary bits, a unit of data with two possible values
while there’s still Double spend
A transaction that uses the same input as an already broadcast transaction. The attempt of duplication, deceit, or conversion, will be adjudicated when only one of the transactions is recorded in the blockchain.
risk, possibly pushing that risk on to others. This can be good for the receiver’s balance sheet but possibly bad for their reputation.
A first-in-first-out (FIFO) algorithm spends the oldest Satoshis
Denominations of Bitcoin value, usually measured in fractions of a bitcoin but sometimes measured in multiples of a satoshi. One bitcoin equals 100,000,000 satoshis.
Not to be confused with: Binary bits, a unit of data with two possible values
first, which can help ensure that the receiver’s payments always confirm, although this has utility only in a few edge cases.

Merge
Spending, in the same transaction, multiple outputs which can be traced back to different previous spenders, leaking information about how many satoshis you control.
Avoidance #

When a receiver receives Satoshis

Denominations of Bitcoin value, usually measured in fractions of a bitcoin but sometimes measured in multiples of a satoshi. One bitcoin equals 100,000,000 satoshis.

Not to be confused with: Binary bits, a unit of data with two possible values

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

However, if the receiver spends Satoshis

Denominations of Bitcoin value, usually measured in fractions of a bitcoin but sometimes measured in multiples of a satoshi. One bitcoin equals 100,000,000 satoshis.

Not to be confused with: Binary bits, a unit of data with two possible values

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

Merge

Spending, in the same transaction, multiple outputs which can be traced back to different previous spenders, leaking information about how many satoshis you control.

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

Spending, in the same transaction, multiple outputs which can be traced back to different previous spenders, leaking information about how many satoshis you control.

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

More advanced Merge

Spending, in the same transaction, multiple outputs which can be traced back to different previous spenders, leaking information about how many satoshis you control.

avoidance strategies largely depend on enhancements to the 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
An output in a transaction which contains two fields: a value field for transferring zero or more satoshis and a pubkey script for indicating what conditions must be fulfilled for those satoshis to be further spent.
Not to be confused with: Outpoint (a reference to a particular output)
from one Unconfirmed transaction
A score indicating the number of blocks on the best block chain that would need to be modified to remove or modify a particular transaction. A confirmed transaction has a confirmation score of one or higher.
in a second transaction, the second transaction becomes invalid if Transaction malleability
The ability of someone to change (mutate) unconfirmed transactions without making them invalid, which changes the transaction’s txid, making child transactions invalid.
Not to be confused with: BIP62 (a proposal for an optional new transaction version that reduces the set of known mutations for common transactions)
changes the first transaction.
If you spend an Output
An output in a transaction which contains two fields: a value field for transferring zero or more satoshis and a pubkey script for indicating what conditions must be fulfilled for those satoshis to be further spent.
Not to be confused with: Outpoint (a reference to a particular output)
from one Unconfirmed transaction
A score indicating the number of blocks on the best block chain that would need to be modified to remove or modify a particular transaction. A confirmed transaction has a confirmation score of one or higher.
in a second transaction and the first transaction’s Output
An output in a transaction which contains two fields: a value field for transferring zero or more satoshis and a pubkey script for indicating what conditions must be fulfilled for those satoshis to be further spent.
Not to be confused with: Outpoint (a reference to a particular output)
is successfully double spent to another Output
An output in a transaction which contains two fields: a value field for transferring zero or more satoshis and a pubkey script for indicating what conditions must be fulfilled for those satoshis to be further spent.
Not to be confused with: Outpoint (a reference to a particular 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

A parameter of bitcoin: URIs which allows the receiver to optionally specify a message to the spender.

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

A transaction that uses the same input as an already broadcast transaction. The attempt of duplication, deceit, or conversion, will be adjudicated when only one of the transactions is recorded in the blockchain.

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:

Blocks	Chance of successful modification
5	17.73523%
10	4.16605%
15	1.01008%
20	0.24804%
25	0.06132%
30	0.01522%
35	0.00379%
40	0.00095%
45	0.00024%
50	0.00006%

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.

Rebilling Recurring Payments #

Automated recurring payments are not possible with decentralized Bitcoin wallets. Even if a Wallet

Software that stores private keys and monitors the block chain (sometimes as a client of a server that does the processing) to allow users to spend and receive satoshis.

Not to be confused with: HD wallet (a protocol that allows all of a wallet’s keys to be created from a single seed)

supported automatically sending non-reversible payments on a regular schedule, the user would still need to start the program at the appointed time, or leave it running all the time unprotected by encryption.

This means automated recurring Bitcoin payments can only be made from a centralized server which handles Satoshis

Denominations of Bitcoin value, usually measured in fractions of a bitcoin but sometimes measured in multiples of a satoshi. One bitcoin equals 100,000,000 satoshis.

Not to be confused with: Binary bits, a unit of data with two possible values

on behalf of its spenders. In practice, receivers who want to set prices in terms must also let the same centralized server choose the appropriate exchange rate.

Non-automated rebilling can be managed by the same mechanism used before credit-card recurring payments became common: contact the spender and ask them to pay again—for example, by sending them a PaymentRequest “bitcoin:” URI in an HTML email.

In the future, extensions to the Payment protocol

The deprecated protocol defined in BIP70 (and other BIPs) which lets spenders get signed payment details from receivers.

Not to be confused with: IP-to-IP payment protocol (an insecure, discontinued protocol included in early versions of Bitcoin)

and new features may allow some programs to manage a list of recurring transactions. The spender will still need to start the program on a regular basis and authorize payment—but it should be easier and more secure for the spender than clicking an emailed invoice, increasing the chance receivers get paid on time.

0 replies

Want to join the discussion?
Feel free to contribute!

Developer Guides

Reference

Examples

Payment Processing

Payment Processing #

Introduction #

Pricing Orders #

Requesting Payments #

Plain Text #

bitcoin: URI #

QR Codes #

Payment protocol
The deprecated protocol defined in BIP70 (and other BIPs) which lets spenders get signed payment details from receivers.
Not to be confused with: IP-to-IP payment protocol (an insecure, discontinued protocol included in early versions of Bitcoin)
#

Verifying Payment #

Issuing Refunds #

Disbursing Income (Limiting Forex Risk) #

Merge
Spending, in the same transaction, multiple outputs which can be traced back to different previous spenders, leaking information about how many satoshis you control.
Avoidance #

Last In, First Out (LIFO) #

First In, First Out (FIFO) #

Rebilling Recurring Payments #

Leave a Reply

Leave a Reply Cancel reply

Social Media

Sitemap

Useful links

Subscribe to the Newsletter

Payment Processing #

Introduction #

Pricing Orders #

Requesting Payments #

Plain Text #

bitcoin: URI #

QR Codes #

Payment protocolThe deprecated protocol defined in BIP70 (and other BIPs) which lets spenders get signed payment details from receivers.Not to be confused with: IP-to-IP payment protocol (an insecure, discontinued protocol included in early versions of Bitcoin) #

Verifying Payment #

Issuing Refunds #

Disbursing Income (Limiting Forex Risk) #

MergeSpending, in the same transaction, multiple outputs which can be traced back to different previous spenders, leaking information about how many satoshis you control. Avoidance #

Last In, First Out (LIFO) #

First In, First Out (FIFO) #

Rebilling Recurring Payments #

Leave a Reply

Leave a Reply Cancel reply

Share This Article :

Social Media

Sitemap

Useful links

Subscribe to the Newsletter

Payment protocol
The deprecated protocol defined in BIP70 (and other BIPs) which lets spenders get signed payment details from receivers.
Not to be confused with: IP-to-IP payment protocol (an insecure, discontinued protocol included in early versions of Bitcoin)
#

Merge
Spending, in the same transaction, multiple outputs which can be traced back to different previous spenders, leaking information about how many satoshis you control.
Avoidance #