Glossary / Lightning & layer 2
Payment secret
- What is a payment secret?
- A payment secret is a 32 byte value the recipient generates per invoice and requires back in the final onion payload, so knowing the payment hash alone does not make you the payer.
Lightning's payment secret works as a per-invoice password that the payer echoes back before the receiving node accepts the money. BOLT 11 gives it the tag letter s, fixes its length at 52 bech32 characters, and tells a reader to fail any invoice arriving without one. For you, it is why a routing node that saw your payment hash cannot tell the payment ended at your wallet.
How it works
A payment secret is minted by the receiving wallet, never by the payer, and it stays sealed inside the onion until the payment reaches its last hop.
BOLT 11 defines it as tagged field type 16, written with the letter s and a fixed data_length of 52. Those 52 bech32 characters carry 260 bits, a 32 byte value plus padding, and an invoice writer must include exactly one. A reader must fail the payment if a fixed-length field is the wrong length, and again if no valid s field is present.
The payer copies the value into the onion payload for the last node, which BOLT 4 calls TLV record type 8, payment_data, holding the 32 byte secret and a total_msat figure. Only the destination can peel that layer, so intermediate hops never see it, unlike the payment hash they all lock their HTLCs to.
The check at the far end is deliberately uninformative. A secret that does not match the one expected for that payment hash, or that is required and absent, fails the HTLC with incorrect_or_unknown_payment_details, error PERM|15, the same answer an unknown payment hash gets. BOLT 4 explains the merge: the older pair, PERM|16 incorrect_payment_amount and 17 final_expiry_too_soon, let a forwarding node re-send payments with the same hash at much lower values and read the reply to confirm it had found the destination.
Support is no longer negotiated. BOLT 9 lists feature bits 14 and 15, payment_secret, as ASSUMED, and bits 16 and 17, basic_mpp, depend on it.
Where you see it
You can spot a payment secret in a modern lnbc string as the run that begins sp5 and continues for 52 characters of bech32.
In the BOLT 11 test vectors that run is zyg3 repeated twelve times and then zygs, encoding a secret whose 32 bytes are every one 0x11. You never type a payment secret: only the invoice writer and the paying wallet ever handle the value.
Where the field earns its keep is multi-part payments. When no single route holds enough liquidity and the invoice offers basic_mpp, BOLT 4 lets a wallet split the amount across several HTLCs sharing one payment hash, and every part must carry the secret and should agree on total_msat. The receiver settles nothing until the total arrives, and should wait at least 60 seconds after the first HTLC before failing the set with an mpp_timeout. So a larger Lightning withdrawal from a Lightning-first app such as Strike that sits pending for a minute and then bounces back can be an incomplete HTLC set expiring rather than money lost. Whether your own wallet assembles those parts, as Phoenix does by running a real Lightning node on the handset, or a custodian does it on a server you do not control, the secret marks them as one payment.
Payment secret vs payment hash
The payment hash and the payment secret are both 256 bit fields in one BOLT 11 invoice, and the difference is who gets to see them. Every hop learns the hash, because each locks its forwarded HTLC to it, while nobody but the final node learns the secret, which rides in the innermost onion layer. The hash answers whether the payment settled, and the preimage that opens it is the receipt. The secret answers whether the payer is working from the invoice you wrote, which a hash cannot, being visible to everyone on the route. In the encoding they look like twins: tag p and tag s, both 52 characters, both rejected at any other length.