This BIP describes a protocol for communication between a merchant and their customer, enabling
both a better customer experience and better security against man-in-the-middle attacks on
the payment process.
==Motivation==
The current, minimal Bitcoin payment protocol operates as follows:
# Customer adds items to an online shopping basket, and decides to pay using Bitcoin.
# Merchant generates a unique payment address, associates it with the customer's order, and asks the customer to pay.
# Customer copies the Bitcoin address from the merchant's web page and pastes it into whatever wallet they are using OR follows a bitcoin: link and their wallet is launched with the amount to be paid.
# Customer authorizes payment to the merchant's address and broadcasts the transaction through the Bitcoin p2p network.
# Merchant's server detects payment and after sufficient transaction confirmations considers the transaction final.
This BIP extends the above protocol to support several new features:
# Human-readable, secure payment destinations-- customers will be asked to authorize payment to "example.com" instead of an inscrutable, 34-character bitcoin address.
# Secure proof of payment, which the customer can use in case of a dispute with the merchant.
# Resistance from man-in-the-middle attacks that replace a merchant's bitcoin address with an attacker's address before a transaction is authorized with a hardware wallet.
# Payment received messages, so the customer knows immediately that the merchant has received, and has processed (or is processing) their payment.
# Refund addresses, automatically given to the merchant by the customer's wallet software, so merchants do not have to contact customers before refunding overpayments or orders that cannot be fulfilled for some reason.
==Protocol==
This BIP describes payment protocol messages encoded using Google's Protocol
Buffers, authenticated using X.509 certificates, and communicated over
http/https. Future BIPs might extend this payment protocol to other
encodings, PKI systems, or transport protocols.
The payment protocol consists of three messages; PaymentRequest, Payment,
and PaymentACK, and begins with the customer somehow indicating that
they are ready to pay and the merchant's server responding with a
Outputs are used in PaymentRequest messages to specify where a payment (or
part of a payment) should be sent. They are also used in Payment messages
to specify where a refund should be sent.
<pre>
message Output {
optional uint64 amount = 1 [default = 0];
optional bytes script = 2;
}
</pre>
{|
| amount || Number of satoshis (0.00000001 BTC) to be paid
|-
| script || a "TxOut" script where payment should be sent. This will normally be one of the standard Bitcoin transaction scripts (e.g. pubkey OP_CHECKSIG). This is optional to enable future extensions to this protocol that derive Outputs from a master public key and the PaymentRequest data itself.
|}
===PaymentDetails/PaymentRequest===
Payment requests are split into two messages to support future extensibility.
The bulk of the information is contained in the PaymentDetails message. It is
wrapped inside a PaymentRequest message, which contains meta-information
| network || either "main" for payments on the production Bitcoin network, or "test" for payments on test network. If a client receives a PaymentRequest for a network it does not support it must reject the request.
| outputs || one or more outputs where Bitcoins are to be sent. If the sum of outputs.amount is zero, the customer will be asked how much to pay, and the bitcoin client may choose any or all of the Outputs (if there are more than one) for payment. If the sum of outputs.amount is non-zero, then the customer will be asked to pay the sum, and the payment shall be split among the Outputs with non-zero amounts (if there are more than one; Outputs with zero amounts shall be ignored).
| merchant_data || Arbitrary data that may be used by the merchant to identify the PaymentRequest. May be omitted if the merchant does not need to associate Payments with PaymentRequest or if they associate each PaymentRequest with a separate payment address.
| pki_type || public-key infrastructure (PKI) system being used to identify the merchant. All implementation should support "none", "x509+sha256" and "x509+sha1".
| pki_data || PKI-system data that identifies the merchant and can be used to create a digital signature. In the case of X.509 certificates, pki_data contains one or more X.509 certificates (see Certificates section below).
are not serialized (however, setting a field to its default value will cause it to be serialized and will affect
the signature). Before serialization, the signature field must be set to an empty value so that the field is included in the signed PaymentRequest hash but contains no data.
# Display the merchant's identity and ask the customer if they would like to submit payment (e.g. display the "Common Name" in the first X.509 certificate).
PaymentRequest messages larger than 50,000 bytes should be rejected by
the wallet application, to mitigate denial-of-service attacks.
===Payment===
Payment messages are sent after the customer has authorized payment:
<pre>
message Payment {
optional bytes merchant_data = 1;
repeated bytes transactions = 2;
repeated Output refund_to = 3;
optional string memo = 4;
}
</pre>
{|
| merchant_data || copied from PaymentDetails.merchant_data. Merchants may use invoice numbers or any other data they require to match Payments to PaymentRequests. Note that malicious clients may modify the merchant_data, so should be authenticated in some way (for example, signed with a merchant-only key).
|-
| transactions || One or more valid, signed Bitcoin transactions that fully pay the PaymentRequest
| refund_to || One or more outputs where the merchant may return funds, if necessary. The merchant may return funds using these outputs for up to 2 months
after the time of the payment request. After that time has expired, parties must negotiate if returning of funds becomes necessary.
# Broadcast the transactions on the Bitcoin p2p network.
# If PaymentDetails.payment_url is specified, POST a Payment message to that URL. The Payment message is serialized and sent as the body of the POST request.
Errors communicating with the payment_url server should be communicated to the user.
PaymentACK is the final message in the payment protocol; it is sent
from the merchant's server to the bitcoin wallet in response to a
Payment message:
<pre>
message PaymentACK {
required Payment payment = 1;
optional string memo = 2;
}
</pre>
{|
| payment || Copy of the Payment message that triggered this PaymentACK. Clients may ignore this if they implement another way of associating Payments with PaymentACKs.
|-
| memo || UTF-8 encoded note that should be displayed to the customer giving the status of the transaction (e.g. "Payment of 1 BTC for eleven tribbles accepted for processing.")
