The URL

Every button is this URL with your details filled in. The maker on the front page writes it for you, and anything that can write a URL can write one too: a person, a spreadsheet formula, a shop plugin or an AI agent that has been asked to get someone paid.

https://theorangebutton.com
  ?address={lightning_address}
  &product={name}
  &amount={number}
  &currency={USD|EUR|GBP|AUD|CAD|sats}   // optional, USD when left out
  &collect=email                           // optional
  &ref={string}                            // optional
  &notify={https url}                      // optional

Encode the values the way any URL wants them: a space as + or %20, an ampersand inside a product name as %26.

Examples

// A plain price
https://theorangebutton.com?address=satoshi@coinos.io&product=Ebook&amount=20

// Ask the buyer who they are
https://theorangebutton.com?address=satoshi@coinos.io&product=Cake+recipe&amount=10&collect=email

// Priced in sats
https://theorangebutton.com?address=satoshi@coinos.io&product=Sticker+pack&amount=5000&currency=sats

// Tell your own server when it is paid
https://theorangebutton.com?address=satoshi@coinos.io&product=Order+4821&amount=35&ref=4821&notify=https://your-site.com/paid

The button as HTML

This is what the maker hands out under "Button for your site": an ordinary link, styled orange, that opens the pay page. It works anywhere HTML does.

<a href="https://theorangebutton.com?address=satoshi@coinos.io&product=Ebook&amount=20" style="display:inline-block;padding:12px 24px;background:#f7931a;color:#fff;border-radius:10px;font-family:sans-serif;font-weight:bold;text-decoration:none;box-shadow:0 4px 0 #c9700d">⚡ Pay with Bitcoin</a>

For AI agents

Construct the URL from the seller's lightning address, the product and the price, and return it as a link. That is the whole integration. Nothing has to be authenticated and nothing has to be registered first; the pay page comes into being the moment somebody opens the URL.

Short links

A short link is theorangebutton.com/yourname. You claim one from the maker after making a button. It is free, and it asks for your email, because that is where your edit link is sent. The short link carries the address, the product, the price and every setting with it, so the URL you share stays clean, and it is what makes the rest of the site work:

• Payment emails. An email lands in your inbox when a payment settles, with the product, the amount, and the buyer's name and email when they gave them. It can be switched off on the edit page.
• Automatic delivery. Attach a message, a link or a file on the edit page. When a payment settles, the buyer sees it on the pay page under Paid ✓ and gets it by email if they gave one. You do nothing.
• A record of who bought. Every confirmed payment is listed on the edit page with the buyer's details, and the whole list downloads as a CSV.
• A wallet you can change. Every button, link and QR code you have shared points at the short link, and the short link points at the wallet. Change the address on the edit page and nothing you have printed or pasted breaks.
• A webhook without a long URL. Set "Also POST to this URL" once on the edit page instead of carrying notify= in every link.

A URL-built button has none of these, because there is nowhere to keep an email address or a file. It still shows Paid ✓ when the wallet can confirm the payment, and it still fires notify=; it simply cannot email or deliver anything.

The edit link looks like theorangebutton.com/edit?secret=… and it is the whole account. We email it to you when you claim, and we cannot recover it for you later, so keep it somewhere safe.

The button on your own site

There are three ways to put the button on a page you control. The first is the HTML link above, which opens the pay page in the same tab. The other two keep the buyer on your page.

The pay page inside your page

An iframe that shows the pay card alone, without the rest of this site around it. The snippet for a claimed link is on your edit page under "More"; this is its shape:

<iframe src="https://theorangebutton.com/embed/?link=yourname" style="border:0;width:100%;max-width:420px;height:560px" title="Pay yourname with Bitcoin" allow="clipboard-write"></iframe>

For a URL-built button, put the same parameters after /embed/? in place of link=: https://theorangebutton.com/embed/?address=you@coinos.io&product=Ebook&amount=20. Add bg=f4f4f4 (a hex colour, no #) to paint the frame's background the colour of the panel it sits in; without it the frame is transparent.

The frame talks to your page with postMessage. It reports its height whenever the card changes, so the iframe can grow with the card instead of scrolling, and it says when the payment has settled:

// frame is your <iframe> element
addEventListener('message', function (e) {
  if (e.source !== frame.contentWindow || !e.data) return;   // only our frame
  if (e.data.type === 'ob:height') {
    frame.style.height = Math.min(Math.max(e.data.px | 0, 180), 1200) + 'px';
  }
  if (e.data.type === 'ob:settled') {
    // { link, ref, amount_sats, product, pr, verify_url }
    console.log('paid', e.data.amount_sats, 'sats');
  }
});

Treat ob:settled as something to update your page with, not as proof. Proof is the webhook, which our server sends only after it has checked the payment with the wallet itself.

A button that opens the pay page in a small window

One script tag. It draws the orange button exactly where it sits, so it can go in a paragraph, a sidebar or a product card:

<script src="https://theorangebutton.com/embed.js" data-link="yourname"></script>

On a desktop the pay page opens in a small window over your page. On a phone, or when the browser blocks the window, it opens in a new tab instead, so the button always works. When the payment settles in the small window, the button's text changes to Paid ✓ and it fires an orangebutton:paid event, which bubbles, with the same detail as ob:settled. A payment made in a new tab pays the seller just the same, but your page is not told about it, so treat the event as a bonus rather than the record of a sale. The webhook below is the record.

document.addEventListener('orangebutton:paid', function (e) {
  console.log(e.detail.link, e.detail.amount_sats, e.detail.ref);
});

For a URL-built button, give the script data-address, data-product, data-amount and, if you want them, data-currency and data-collect="email" instead of data-link. Either kind also takes data-ref and data-label (the words on the button; "⚡ Pay with Bitcoin" when left out). The script adds nothing else to your page: no styles, no fonts, no tracking.

How a payment is confirmed

The pay page asks your wallet for an invoice (LNURL-pay) and, when the wallet supports it, is handed a verify URL alongside it (LUD-21). It asks that URL every three seconds, for up to ten minutes, whether the invoice has settled. When the wallet says yes, the page shows Paid ✓ and tells our server.

The server does not take the page's word for it. Before anything is recorded, emailed or delivered it does four things:

1. It checks that the verify URL belongs to the wallet behind your lightning address, and it follows no redirect off that host.
2. It asks that URL itself and accepts only settled: true for that exact invoice.
3. It reads the amount out of the invoice, never out of the request.
4. It keeps one record per invoice, so the same payment reported twice is answered as a duplicate and nothing happens twice.

Nobody can make a payment appear by pressing something on the page or by posting to our server. If the wallet does not say the invoice settled, nothing happened.

A wallet that offers no verify URL (Wallet of Satoshi is the common one) still receives the payment, but there is no way for anyone to confirm it, so the page never says Paid ✓ and our server never hears of it. The section on wallets says which ones confirm.

The webhook

Give the button an https URL, as notify= on a URL-built button or under "Also POST to this URL" on your edit page, and our server POSTs one JSON message to it for every settled payment, after it has confirmed the payment itself as described above:

POST https://your-site.com/paid
Content-Type: application/json
Idempotency-Key: {sha256 of the invoice}

{
  "event": "paid",
  "link": "yourname",                 // null for a URL-built button
  "product": "Ebook",
  "amount_sats": 28571,               // read from the invoice
  "amount": 20,                       // the listed price, or null
  "currency": "USD",
  "buyer_name": "Sarah Jones",        // null when not given
  "buyer_email": "sarah@example.com", // null when not given
  "ref": null,
  "pr": "lnbc…",
  "verify_url": "https://…",
  "settled_at": "2026-09-06T01:02:03Z"
}

Answer with any 2xx. Delivery is at least once: a reply that is not 2xx is tried once more, and a payment reported to us twice can reach you twice, so dedupe on the Idempotency-Key header or on pr.

Re-check verify_url yourself before trusting the event. Fetch it, and act only when it answers settled: true for the same pr. Our server has already done this, but your server should not have to take our word for it any more than we take the browser's.

buyer_name and buyer_email are what the buyer typed. They are self-reported and never verified, so escape them before they touch a page, an email or a spreadsheet. The verification covers the payment, not the name.

The buyer's name and email

With collect=email on, the buyer is asked for a name (optional) and an email (required) before the invoice is made. They travel two ways:

• To your wallet, as the invoice comment (LUD-12), written Name <email>. If the two together do not fit the wallet's comment limit, the email goes alone; if the wallet takes no comment, nothing goes. Most wallets show the comment next to the payment.
• To the sale, on a claimed link, where they are recorded with the payment, put in your payment email and used to send the buyer what they bought. This happens whatever the wallet did with the comment.

Both are whatever the buyer typed. Nothing checks that the name is theirs or that the email is real, so treat them as display text: escape them, and do not act on them alone.

Wallets

Any Lightning wallet can pay a button, and any wallet that gives you a lightning address can receive from one. Two things depend on which wallet is receiving:

• Confirming payments (LUD-21 verify). Coinos, Alby, Blink and Speed do. Wallet of Satoshi does not. Without it there is no Paid ✓, no payment email, no delivery and no sales record. The sats still arrive.
• Taking a comment (LUD-12). Most wallets do, with a limit somewhere between a hundred and a few hundred characters. Without it the buyer's details do not appear in your wallet, though a claimed link still records them.

The maker and the edit page check the wallet behind the address you type and say which of these it does. The check reads a table our server keeps of the wallet services it has met; a service it has never met is probed once and the answer is kept for everyone. The answer is kept against the wallet service, not against you: what is stored is what that service can do.

Downloads

A file attached to a short link is handed out as theorangebutton.com/d/{token}, a private link made for that one sale. It appears on the pay page under Paid ✓ and in the buyer's email. It works for 30 days from the sale and is sent as a plain attachment, whatever the file type. The file itself sits at no address anyone can guess; there is nothing to find without a sale. Uploading a new file replaces the old one, and the link serves whatever file is attached at the time.

Non-custodial, and what follows from it

We never hold, route or touch any bitcoin. The pay page resolves your lightning address, asks your wallet for an invoice and shows it to the buyer; the sats go from their wallet to yours. Our server's only part comes afterwards, when it asks your wallet whether an invoice it never issued has settled. There is no balance here, nothing to withdraw and nothing that can be frozen.

It follows that there are no refunds, disputes or buyer accounts on this site. A refund is a payment you make back to the buyer from your own wallet, and a buyer with a question reaches you wherever they found your button.

bitcoinpaylinks.com links keep working

The Orange Button is the new name for BitcoinPayLinks. Every bitcoinpaylinks.com pay link, short link and QR code redirects to the same address here with its parameters intact, so nothing already printed or pasted needs to change.