Payment hash

Every hop on a Lightning route sees the same payment hash, which is what identifies the payment to each of them. BOLT 11 requires exactly one of them per invoice, written as 52 bech32 characters carrying 256 bits. Showing the matching secret is the only way to claim the money, and holding that secret afterwards is your receipt.

How it works

A payment hash starts life as its opposite: the receiver picks 32 random bytes, called the payment preimage, and publishes only the SHA-256 of them.

That value goes into the invoice under the tag p, which BOLT 11 fixes at a data_length of 52 and requires exactly once. From there it travels down the route inside update_add_htlc, message type 128, whose fields are the channel id, a 64 bit counter, the amount in millisatoshis, the payment_hash itself, a CLTV expiry and a 1366 byte onion. It does double duty in that message: it is also fed to the onion construction as associated data, so the HMACs at every hop commit to it. Replaying an old onion packet against a different payment hash therefore fails at the first node that checks.

Settlement runs the hash backwards. The receiver returns the preimage in update_fulfill_htlc, message type 130, as a bare 32 byte value, and each node upstream passes it back along the same channels. A node handed a preimage that does not SHA-256 to the hash it is holding does not simply ignore it: BOLT 2 says it must either send a warning and close the connection or send an error and fail the channel, because there is no innocent explanation.

On chain the hash is trimmed. The HTLC output script does not contain the 32 byte value at all; it runs an OP_HASH160 comparison against RIPEMD160(payment_hash), a 20 byte commitment, and the spender supplies the preimage in the witness. Two offered HTLCs with the same rounded amount and the same payment hash produce byte-identical outputs even when their expiries differ, which is why BOLT 3 has to specify an ordering rule for them.

One requirement looks odd until you see the attack behind it. A node must accept several HTLCs carrying the same payment hash, and BOLT 2 gives the reason: if duplicates were refused, an attacker could probe with a known hash and learn whether that node was already holding that payment. The separate 64 bit id exists to tell the duplicates apart.

Why this matters when you buy bitcoin

Two of the 63 exchanges reviewed here document a Lightning payout in their fee notes: Strike, whose withdrawal note says wallet withdrawals are supported over Lightning and on-chain, and Coinbase, whose fee table prices a Lightning send at 0.2% of the amount sent.

When one of those payouts stalls, there is no transaction ID to look up, because nothing reached the blockchain. The payment hash is the only string your wallet log and the exchange's back office both hold, so copy it out of the payment detail screen before you close it. A support desk asking for "the transaction ID" of a Lightning withdrawal is asking for this value.

The error you get back will not tell you much, and that is deliberate. BOLT 4 folds five separate problems into one failure code, incorrect_or_unknown_payment_details, numbered PERM|15: the hash is unknown to the final node, the payment secret does not match it, the amount for that hash is too low, the expiry sits too close to the current block height, or required payment metadata is missing. The spec explains the merge. The older split codes let a forwarding node guess where a payment was going by sending the same hash onward at a much lower value and reading the reply. Your wallet is not hiding the reason from you, it was never told, so regenerating the invoice and paying again is the practical response.

The same value stays identical from your node to the recipient's, including across every part of a multi-part payment, which BOLT 4 requires to share a single payment hash. Anyone who sees it twice knows they are looking at one payment. Our Phoenix review quotes ACINQ's own FAQ conceding that it knows the final destination and amount of payments made through the wallet, which is the blunt version of the same exposure, stated by the vendor rather than inferred by us.

Reusing an invoice is worse than useless for a related reason. BOLT 4 leaves a final node that is handed an already-paid hash free either to treat it as unknown or to accept the money, so the outcome of a republished QR code depends on which implementation the receiver happens to run.

Decoding the payment hash in the BOLT 11 donation test vector

The BOLT 11 specification ships a worked donation invoice, and the payment hash inside it is a fixed test value that no wallet should ever produce.

The example is headed "Please make a donation of any amount using payment_hash 0001020304050607080900010203040506070809000102030405060708090102" and the string begins lnbc1pvjluez. After the lnbc prefix and the bech32 separator, pvjluez is the timestamp, 1496314658 seconds since the start of 1970. The payment secret field comes next, and after it the p tag, then p5, which is the length: in bech32 p is 1 and 5 is 20, so the field runs 1 * 32 + 20 = 52 characters. Those characters, qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypq, decode to the hash quoted in that heading.

Nothing about it is private. The spec publishes the private key its examples are signed with, e126f68f7eafcc8b74f54d269fe206be715000f94dac067d1c04a8ca3b2db734, and says every invoice in that section carries the payment secret 1111111111111111111111111111111111111111111111111111111111111111 unless it notes otherwise, so these strings are parser fixtures rather than payment requests. If a wallet or a diagnostic tool ever shows you that hash outside a test suite, something is echoing the spec rather than reporting your payment.

Payment hash vs transaction ID

A payment hash names a Lightning payment; a transaction ID names a transaction that exists on the bitcoin blockchain. Both are 32 bytes and both print as 64 hexadecimal characters, which is how they end up in each other's support forms. A transaction ID is computed from the transaction's own bytes after the fact and can be pasted into any block explorer. A payment hash is chosen by the receiver before the payment exists, never appears in a block when the payment settles normally, and returns nothing from an explorer. An empty search result usually means you have the right value and the wrong tool.

Payment hash vs payment secret

A payment hash and a payment secret are two different 256 bit values in the same invoice, carried in the tags p and s and each encoded as 52 bech32 characters. The hash is necessarily public: every hop has to see it to build its HTLC. The secret is delivered only to the last node, inside the onion, and BOLT 11 states its job in one line, that it "prevents forwarding nodes from probing the payment recipient". A reader that finds no s field must fail the payment outright. The hash is the lock; the secret is evidence that whoever is paying got the invoice from the person who issued it.