diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index ebffac9..d824e56 100644 --- a/docs/.vitepress/config.mjs +++ b/docs/.vitepress/config.mjs @@ -101,6 +101,7 @@ export default withMermaid(defineConfig({ }, ], }, + { text: 'Merchant Stack', link: '/merchant-stack/' }, { text: 'API', items: [ @@ -280,6 +281,24 @@ export default withMermaid(defineConfig({ ], }, ], + '/merchant-stack/': [ + { + text: 'Merchant Stack', + items: [ + { text: 'Overview', link: '/merchant-stack/' }, + { text: 'Quick Start with SaaS', link: '/merchant-stack/quick-start' }, + { text: 'Set up TPoS', link: '/merchant-stack/tpos' }, + { text: 'Set up Inventory', link: '/merchant-stack/inventory' }, + { text: 'Capture Orders', link: '/merchant-stack/orders' }, + { text: 'Sell Online with WebShop', link: '/merchant-stack/webshop' }, + { text: 'Use Tabs', link: '/merchant-stack/tabs' }, + { text: 'Hardware and Printing', link: '/merchant-stack/hardware' }, + { text: 'Bookkeeping', link: '/merchant-stack/bookkeeping' }, + { text: 'Merchant Advisors', link: '/merchant-stack/advisors' }, + { text: 'Troubleshooting', link: '/merchant-stack/troubleshooting' }, + ], + }, + ], '/api/': [ { text: 'API Reference', diff --git a/docs/.vitepress/theme/components/HomePage.vue b/docs/.vitepress/theme/components/HomePage.vue index a622519..e42dd09 100644 --- a/docs/.vitepress/theme/components/HomePage.vue +++ b/docs/.vitepress/theme/components/HomePage.vue @@ -11,9 +11,17 @@ const mounted = ref(false) const toast = ref('') const ghStars = ref('') const contribVideoActive = ref(false) +const merchantVideoOpen = ref(false) + +function closeMerchantVideo() { + merchantVideoOpen.value = false +} onMounted(() => { mounted.value = true + window.addEventListener('keydown', e => { + if (e.key === 'Escape') closeMerchantVideo() + }) fetch('https://api.github.com/repos/lnbits/lnbits', { headers: { Accept: 'application/vnd.github.v3+json' } }) .then(r => r.ok ? r.json() : null) .then(d => { if (d?.stargazers_count) ghStars.value = (d.stargazers_count / 1000).toFixed(1) + 'k' }) @@ -123,6 +131,9 @@ const quickLinks = [ { title: 'Installation', desc: 'uv, Poetry, Docker, Nix, Fly.io', link: '/guide/installation/', icon: 'download' }, { title: 'Wallet Backends', desc: '20+ funding sources', link: '/guide/wallets/', icon: 'wallet' }, { title: 'Extensions', desc: '60+ plugins ready to use', link: '/guide/using-extensions', icon: 'puzzle' }, + { title: 'Merchant Stack', desc: 'POS, inventory, orders, WebShop', link: '/merchant-stack/', icon: 'store' }, + { title: 'Plugins', desc: 'WooCommerce, Shopify and more', link: '/plugins/', icon: 'cart' }, + { title: 'Apps', desc: 'Standalone apps for LNbits', link: '/apps/', icon: 'apps' }, { title: 'Admin Dashboard', desc: 'Server config & user management', link: '/guide/admin-dashboard', icon: 'shield' }, { title: 'Super User', desc: 'Full control & first-run setup', link: '/guide/core/super-user', icon: 'star' }, { title: 'FAQ', desc: 'Common questions answered', link: '/guide/faq/', icon: 'help' }, @@ -249,6 +260,48 @@ const quickLinks = [ + +
+
+
+ For Merchants & Entrepreneurs +

The LNbits Merchant Stack

+

+ Everything you need to accept Lightning payments in the real world: + point of sale, inventory, orders, and a full web shop. Built for + merchants, ambassadors, and everyone bringing Bitcoin to their community. +

+
    +
  • Point of sale & card terminals
    • +
  • Inventory & order management
    • +
  • Hosted WebShop
    • +
  • Tap-to-pay with Boltcards
    • +
  • Fiat payments: tap to pay with credit card
    • +
  • Hardware receipt printing
    • +
+
+ + + Explore the Merchant Stack + + +
+
+
+
+ LNbits Merchant Stack hardware: mobile wallet, point of sale tablet, card terminal, and the LNbits box +
+
+
+

Explore

@@ -267,6 +320,12 @@ const quickLinks = [ + + + + + +
{{ q.title }} @@ -459,6 +518,26 @@ const quickLinks = [
+ + +
+
+ +
+ +
+
+
+ +
{{ toast }}
@@ -813,6 +892,219 @@ const quickLinks = [ transform: translateX(0); } +/* ═══════════════════════════════════ + Merchant Stack + ═══════════════════════════════════ */ +.mstack { + margin-bottom: 56px; +} + +.mstack-inner { + display: grid; + grid-template-columns: 1.1fr 0.9fr; + gap: 36px; + align-items: center; + border: 1px solid var(--vp-c-divider); + border-radius: 16px; + background: var(--vp-c-bg-elv); + padding: 36px 40px; + overflow: hidden; +} + +.mstack-copy { + display: flex; + flex-direction: column; + gap: 10px; +} + +.mstack-eyebrow { + font-size: 12px; + font-weight: 700; + text-transform: uppercase; + letter-spacing: 1px; + color: var(--vp-c-brand-1); +} + +.mstack-title { + font-size: 24px; + font-weight: 800; + letter-spacing: -0.02em; + color: var(--vp-c-text-1); + margin: 0; + line-height: 1.2; +} + +.mstack-desc { + font-size: 14px; + color: var(--vp-c-text-2); + line-height: 1.6; + margin: 2px 0 4px; +} + +.mstack-features { + list-style: none; + padding: 0; + margin: 0 0 6px; + display: grid; + grid-template-columns: 1fr 1fr; + gap: 6px 18px; +} + +.mstack-features li { + font-size: 13px; + color: var(--vp-c-text-2); + padding-left: 20px; + position: relative; +} + +.mstack-features li::before { + content: '✓'; + position: absolute; + left: 0; + color: var(--vp-c-brand-1); + font-weight: 700; + font-size: 13px; +} + +.mstack-actions { + display: flex; + gap: 10px; + margin-top: 6px; +} + +.mstack-btn { + display: inline-flex; + align-items: center; + gap: 6px; + padding: 10px 20px; + border-radius: 10px; + font-size: 14px; + font-weight: 600; + text-decoration: none; + border: 1px solid var(--vp-c-divider); + color: var(--vp-c-text-1); + background: var(--vp-c-bg); + transition: border-color 0.2s, background 0.2s, transform 0.2s; +} + +.mstack-btn:hover { + border-color: var(--vp-c-brand-1); + transform: translateY(-1px); +} + +.mstack-btn--primary { + background: var(--vp-c-brand-1); + border-color: var(--vp-c-brand-1); + color: #fff; +} + +.mstack-btn--primary:hover { + opacity: 0.9; + border-color: var(--vp-c-brand-1); +} + +.mstack-visual { + position: relative; + display: flex; + align-items: center; + justify-content: center; +} + +.mstack-glow { + position: absolute; + inset: 0; + margin: auto; + width: 72%; + height: 72%; + background: radial-gradient(circle, rgba(149, 117, 205, 0.22), transparent 70%); + filter: blur(44px); + z-index: 0; +} + +.mstack-img { + position: relative; + z-index: 1; + width: 100%; + max-width: 460px; + height: auto; + display: block; +} + +/* ═══════════════════════════════════ + Video Modal (lightbox) + ═══════════════════════════════════ */ +.video-modal { + position: fixed; + inset: 0; + z-index: 100; + display: flex; + align-items: center; + justify-content: center; + padding: 24px; + background: rgba(0, 0, 0, 0.75); + backdrop-filter: blur(4px); +} + +.video-modal-inner { + position: relative; + width: 100%; + max-width: 880px; +} + +.video-modal-frame { + position: relative; + width: 100%; + aspect-ratio: 16 / 9; + border-radius: 14px; + overflow: hidden; + background: #000; + box-shadow: 0 24px 64px rgba(0, 0, 0, 0.5); +} + +.video-modal-frame iframe { + position: absolute; + inset: 0; + width: 100%; + height: 100%; + border: 0; +} + +.video-modal-close { + position: absolute; + top: -44px; + right: 0; + display: inline-flex; + align-items: center; + justify-content: center; + width: 36px; + height: 36px; + border: 0; + border-radius: 50%; + background: rgba(255, 255, 255, 0.12); + color: #fff; + cursor: pointer; + transition: background 0.2s; +} + +.video-modal-close:hover { + background: rgba(255, 255, 255, 0.24); +} + +.video-modal-close svg { + width: 20px; + height: 20px; +} + +.vmodal-enter-active, +.vmodal-leave-active { + transition: opacity 0.2s ease; +} + +.vmodal-enter-from, +.vmodal-leave-to { + opacity: 0; +} + /* ═══════════════════════════════════ Quick Links (2x3 grid) ═══════════════════════════════════ */ @@ -1238,6 +1530,12 @@ const quickLinks = [ .contrib-roles { grid-template-columns: 1fr; } + + .video-modal-close { + top: 8px; + right: 8px; + background: rgba(0, 0, 0, 0.5); + } } /* ═══════════════════════════════════ @@ -1351,6 +1649,20 @@ const quickLinks = [ gap: 10px; } + .mstack-inner { + grid-template-columns: 1fr; + gap: 24px; + padding: 24px; + } + + .mstack-visual { + order: -1; + } + + .mstack-img { + max-width: 360px; + } + .mcard { flex-direction: row; align-items: center; diff --git a/docs/.vitepress/theme/components/MegaMenu.vue b/docs/.vitepress/theme/components/MegaMenu.vue index 06c8f9a..4c61ba1 100644 --- a/docs/.vitepress/theme/components/MegaMenu.vue +++ b/docs/.vitepress/theme/components/MegaMenu.vue @@ -41,6 +41,7 @@ const columns = [ { name: 'Wallet Backends', desc: '20+ funding sources', link: '/guide/wallets/', icon: 'wallet' }, { name: 'Core Features', desc: 'Payments, LNURL, labels', link: '/guide/core/', icon: 'zap' }, { name: 'Extensions', desc: '60+ extensions', link: '/guide/using-extensions', icon: 'puzzle' }, + { name: 'Merchant Stack', desc: 'POS, inventory, orders, WebShop', link: '/merchant-stack/', icon: 'shopping-cart' }, { name: 'Admin Dashboard', desc: 'Server management', link: '/guide/admin-dashboard', icon: 'settings' }, { name: 'User Management', desc: 'Roles & permissions', link: '/guide/core/user-management/', icon: 'users' }, { name: 'FAQ', desc: '80+ common questions', link: '/guide/faq/', icon: 'help' }, @@ -124,10 +125,16 @@ const columns = [ { name: 'Browse Extensions', desc: '60+ extensions ready to use', link: '/extensions/', icon: 'puzzle' }, ], }, + { + heading: 'Merchant Stack', + items: [ + { name: 'Merchant Stack', desc: 'POS, inventory, orders, WebShop', link: '/merchant-stack/', icon: 'store' }, + ], + }, { heading: 'Companion Apps', items: [ - { name: 'Browse Apps', desc: 'Standalone apps for LNbits', link: '/apps/', icon: 'zap' }, + { name: 'Browse Apps', desc: 'Standalone apps for LNbits', link: '/apps/', icon: 'apps' }, ], }, { @@ -204,6 +211,8 @@ const columns = [ + + diff --git a/docs/.vitepress/theme/components/NavSwitch.vue b/docs/.vitepress/theme/components/NavSwitch.vue index 796c72e..13fbc48 100644 --- a/docs/.vitepress/theme/components/NavSwitch.vue +++ b/docs/.vitepress/theme/components/NavSwitch.vue @@ -11,6 +11,7 @@ const sections = [ { text: 'Guide', link: '/guide/', match: '/guide' }, { text: 'API', link: '/api/', match: '/api' }, { text: 'Extensions', link: '/extensions/', match: '/extensions' }, + { text: 'Merchant Stack', link: '/merchant-stack/', match: '/merchant-stack' }, { text: 'Apps', link: '/apps/', match: '/apps' }, { text: 'Plugins', link: '/plugins/', match: '/plugins' }, { text: 'Developers', link: '/dev/architecture', match: '/dev' }, diff --git a/docs/guide/index.md b/docs/guide/index.md index 0cbe005..fc934d5 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -14,6 +14,8 @@ New to LNbits? Start here: 2. **[Installation](/guide/installation/)** - choose your setup method 3. **[Core features](/guide/core/)** - wallets, payments, API keys +Running a shop, popup, event, or merchant onboarding workflow? Start with the **[Merchant Stack](/merchant-stack/)** guide. + ## Installation Pick the method that fits your environment: diff --git a/docs/merchant-stack/advisors.md b/docs/merchant-stack/advisors.md new file mode 100644 index 0000000..8fd3b08 --- /dev/null +++ b/docs/merchant-stack/advisors.md @@ -0,0 +1,89 @@ +# Merchant Advisor Guide + +> Use Merchant Stack to help shops in your area accept Bitcoin with a practical operating workflow. + +A merchant advisor is someone who helps a shop get from interest to a working setup. This may be a local Bitcoiner, educator, meetup organizer, consultant, developer, or LNbits power user. + +## Why advisors matter + +Many merchants do not want to learn Lightning infrastructure before accepting their first payment. They need someone who can: + +- explain the setup +- choose the right deployment path +- configure the first wallet and extensions +- test the first payment +- recommend hardware +- support staff during early use + +LNbits SaaS makes this easier because the advisor can start with a hosted instance instead of managing a server. + +## Demo script + +A simple merchant demo: + +1. Open TPoS. +2. Add one or two products to the cart. +3. Show a Lightning QR payment. +4. Show card payment if configured. +5. Print a customer receipt. +6. Open Orders and show the order record. +7. Open Inventory and show stock change. +8. Open WebShop and show the same product online. + +Keep the demo focused on shop operations, not technical details. + +## Merchant pitch + +Use this framing: + +> LNbits lets you accept Bitcoin without losing the practical tools you need to run a shop: POS, products, stock, orders, receipts, online sales, and hosted setup. + +Avoid leading with: + +- developer platform details +- every extension LNbits supports +- Bitcoin-only messaging +- deep backend configuration + +## First merchant checklist + +- [ ] Create or choose the LNbits instance. +- [ ] Create the merchant wallet. +- [ ] Install TPoS, Inventory, and Orders. +- [ ] Add a small product catalog. +- [ ] Complete a test Lightning payment. +- [ ] Configure card payments if needed. +- [ ] Test receipt printing. +- [ ] Configure notifications. +- [ ] Document who has admin access. +- [ ] Schedule a follow-up after first real sales. + +## Referral programs + +If a referral or onboarder program is available, use your referral link when helping a merchant start with LNbits SaaS. + +Track: + +- merchant name +- SaaS account or instance +- setup date +- first successful payment +- follow-up issues + +## Boundaries + +Be clear with merchants about: + +- who provides support +- who controls admin access +- who controls wallet seed phrases and backups +- which payment methods are enabled +- local rules for selling Bitcoin, if using OTC/ATM features + +## Related pages + +- [Quick Start with SaaS](/merchant-stack/quick-start) +- [TPoS](/merchant-stack/tpos) +- [Hardware and printing](/merchant-stack/hardware) +- [Troubleshooting](/merchant-stack/troubleshooting) + diff --git a/docs/merchant-stack/bookkeeping.md b/docs/merchant-stack/bookkeeping.md new file mode 100644 index 0000000..8db6f3f --- /dev/null +++ b/docs/merchant-stack/bookkeeping.md @@ -0,0 +1,53 @@ +# Bookkeeping + +> Merchants need records they can reconcile, not only payment confirmations. + +Merchant Stack helps keep sales activity connected to wallet records, orders, receipts, and exports. + +## What to record + +For each merchant workflow, make sure the merchant can answer: + +- what was sold +- when it was sold +- how the customer paid +- which wallet received the payment +- whether tax was included or added +- whether the order was fulfilled +- whether the sale was refunded, written off, or manually settled + +## LNbits records + +LNbits can help with: + +- wallet transaction history +- payment hashes and invoice records +- Orders records +- TPoS source tracking +- exchange-rate data +- CSV exports where available +- accounting integrations where configured + +## Fiat and Bitcoin together + +If a merchant accepts both card and Bitcoin payments, decide how records should flow into accounting tools. + +For example: + +- Stripe may already sync fiat/card payments to the merchant's accounting system. +- LNbits records can help track Bitcoin payments and LNbits-side operational data. +- Orders can preserve line items and receipt context. + +## Manual settlement caution + +Cash settlement, card settlement, write-offs, and on-chain settlement records can affect the merchant's accounting view. + +Keep these workflows restricted to trusted staff and document when each method should be used. + +## Related pages + +- [Orders](/merchant-stack/orders) +- [TPoS](/merchant-stack/tpos) +- [Tabs](/merchant-stack/tabs) +- [Core payments](/guide/core/payments) + diff --git a/docs/merchant-stack/hardware.md b/docs/merchant-stack/hardware.md new file mode 100644 index 0000000..cd786c9 --- /dev/null +++ b/docs/merchant-stack/hardware.md @@ -0,0 +1,90 @@ +# Hardware And Printing + +> Hardware is often the difference between a demo and a usable merchant setup. + +Merchant Stack can run on ordinary devices, but card payments and printing introduce hardware-specific requirements. Test the merchant's exact setup before relying on it in production. + +## Common setup + +A practical small-shop setup can include: + +- a computer or tablet for staff checkout +- an Android phone or POS device for customer-facing payment +- a receipt printer +- a hosted LNbits SaaS instance +- optional LNbitsBox or self-hosted instance for local control + +## Android device for tap-to-pay + +For Stripe tap-to-pay, the Android device must be compatible with Stripe requirements. + +Check for: + +- NFC support +- Google Mobile Services certification when required +- current Android version +- working camera for QR pairing +- reliable internet connection + +::: warning +Do not assume any generic Android POS device will work with Stripe tap-to-pay. Test the exact device model first. +::: + +## TPoS Wrapper app + +The [TPoS Wrapper](/apps/tpos-wrapper) app connects the LNbits TPoS workflow to Android tap-to-pay and device printing. + +Use it when the merchant needs: + +- card tap-to-pay on Android +- customer-facing device payments +- silent printing from the device + +## Pairing tips + +If QR pairing is unreliable: + +- increase screen brightness +- open the QR code on a light background +- clean the device camera +- avoid glare +- verify the Android device has internet access +- retry pairing after saving the TPoS settings + +## Receipt printing + +Merchants may need two receipt types: + +- **Customer receipt**: the buyer's payment receipt +- **Order receipt**: a larger internal ticket for kitchen, barista, staff, or fulfillment workflows + +Printer setup can vary by hardware. Test: + +- printer discovery +- silent printing +- print width +- paper size +- character encoding +- logo and store details +- reprint from recent receipts + +## Recommended production check + +Before a merchant goes live: + +1. Complete a Lightning payment. +2. Complete a card payment if configured. +3. Validate a cash sale if used. +4. Print a customer receipt. +5. Print an internal order receipt. +6. Confirm the order appears in Orders. +7. Confirm stock changes in Inventory. +8. Confirm owner/staff notifications arrive. + +## Related pages + +- [TPoS](/merchant-stack/tpos) +- [TPoS Wrapper](/apps/tpos-wrapper) +- [Orders](/merchant-stack/orders) +- [Troubleshooting](/merchant-stack/troubleshooting) + diff --git a/docs/merchant-stack/index.md b/docs/merchant-stack/index.md new file mode 100644 index 0000000..ed3664a --- /dev/null +++ b/docs/merchant-stack/index.md @@ -0,0 +1,87 @@ +# Merchant Stack + +> Run a real shop with LNbits: point of sale, inventory, orders, online sales, open balances, and hosted deployment. + +LNbits Merchant Stack is a set of LNbits tools that work together for merchants and the people who help merchants accept Bitcoin. + +It is not a single extension. It is a practical workflow built from LNbits SaaS and merchant-focused extensions: + +- **[TPoS](/merchant-stack/tpos)** for in-person checkout +- **[Inventory](/merchant-stack/inventory)** for shared products and stock +- **[Orders](/merchant-stack/orders)** for receipts, order history, and notifications +- **[WebShop](/merchant-stack/webshop)** for online sales +- **[Tabs](/merchant-stack/tabs)** for open balances and deferred settlement +- **[LNbits SaaS](/merchant-stack/quick-start)** for the fastest hosted setup + +## Who it is for + +Merchant Stack is useful for: + +- independent shops accepting Lightning payments +- cafes, bars, and restaurants that need receipts, order tickets, tips, or tabs +- popups, events, festivals, and meetups +- online sellers that also sell in person +- Bitcoin educators and local merchant onboarders +- operators managing several merchant LNbits instances + +## What it helps you do + +With the stack, a merchant can: + +- accept Lightning payments in person +- accept card payments through configured fiat providers +- validate cash sales +- receive on-chain payments where configured +- keep a shared product catalog +- track stock across POS and WebShop workflows +- capture paid orders +- send owner or staff notifications +- print customer receipts and internal order tickets +- sell online through a hosted or embedded WebShop +- settle open balances later with Tabs +- run everything from a hosted LNbits SaaS instance + +## How the pieces fit together + +```mermaid +flowchart LR + SaaS[LNbits SaaS] --> LNbits[LNbits instance] + LNbits --> TPoS[TPoS] + LNbits --> WebShop[WebShop] + LNbits --> Tabs[Tabs] + Inventory[Inventory] --> TPoS + Inventory --> WebShop + TPoS --> Orders[Orders] + WebShop --> Orders + TPoS --> Tabs +``` + +**Inventory** is the product source. +**TPoS** and **WebShop** are sales channels. +**Orders** records what was sold. +**Tabs** handles balances that should be settled later. +**SaaS** gives merchants a hosted LNbits instance without running a server. + +## Recommended first setup + +Start with the simplest merchant flow: + +1. [Create a hosted LNbits instance with SaaS](/merchant-stack/quick-start). +2. [Set up TPoS](/merchant-stack/tpos) for checkout. +3. [Add Inventory](/merchant-stack/inventory) for products and stock. +4. [Enable Orders](/merchant-stack/orders) to keep receipts and notifications. +5. Add [WebShop](/merchant-stack/webshop) or [Tabs](/merchant-stack/tabs) when the merchant needs those workflows. + +## Hosted or self-hosted + +For most new merchants, start with [LNbits SaaS](https://my.lnbits.com). It avoids server setup and gives the merchant a full LNbits instance with extensions, HTTPS, and a management dashboard. + +Self-hosting remains available when the merchant wants deeper infrastructure control. See [Installation](/guide/installation/) for self-hosted options. + +## Next steps + +- [Quick Start with SaaS](/merchant-stack/quick-start) +- [Set up TPoS](/merchant-stack/tpos) +- [Hardware and printing](/merchant-stack/hardware) +- [Merchant advisor guide](/merchant-stack/advisors) + diff --git a/docs/merchant-stack/inventory.md b/docs/merchant-stack/inventory.md new file mode 100644 index 0000000..5d573d3 --- /dev/null +++ b/docs/merchant-stack/inventory.md @@ -0,0 +1,79 @@ +# Set Up Inventory + +> Inventory is the shared product and stock source for Merchant Stack. + +Use Inventory so the merchant does not maintain separate product lists in TPoS, WebShop, and other sales channels. + +## Why use Inventory + +Inventory helps merchants: + +- create products once +- reuse products across extensions +- track stock quantities +- store product names, descriptions, tags, and prices +- separate in-store and online products with tags +- keep checkout and WebShop data consistent + +## Basic setup + +1. Enable the [Inventory extension](/extensions/inventory/). +2. Create an item. +3. Add a name, price, description, and any useful metadata. +4. Set stock quantity. +5. Add tags or categories. +6. Save the item. + +## Suggested product fields + +For each product, collect: + +- product name +- short description +- price +- image +- stock quantity +- category or tag +- weight if the item may be shipped +- channel tag such as `pos`, `webshop`, or `event` + +## Channel tags + +Tags are useful when the merchant sells different products in different places. + +Examples: + +| Tag | Use | +| --- | --- | +| `pos` | show in the in-person TPoS catalog | +| `webshop` | show in the online shop | +| `event` | show only for a temporary event setup | +| `hidden` | keep in Inventory but omit from active channels | + +## Connect Inventory to TPoS + +After products exist: + +1. Open the TPoS settings. +2. Choose the Inventory-backed product source if available. +3. Select the tags or categories that should appear. +4. Open TPoS and confirm the products appear. +5. Make a test sale and confirm stock changes as expected. + +## Connect Inventory to WebShop + +For online sales: + +1. Enable WebShop. +2. Create a shop. +3. Select the inventory source. +4. Choose the products or tags to expose. +5. Open the public shop page and confirm unavailable products do not appear. + +## Related pages + +- [Inventory extension](/extensions/inventory/) +- [TPoS](/merchant-stack/tpos) +- [WebShop](/merchant-stack/webshop) +- [Orders](/merchant-stack/orders) + diff --git a/docs/merchant-stack/orders.md b/docs/merchant-stack/orders.md new file mode 100644 index 0000000..5016f5d --- /dev/null +++ b/docs/merchant-stack/orders.md @@ -0,0 +1,62 @@ +# Capture Orders + +> Orders keeps the record of what was sold after payment. + +Payments are only part of the merchant workflow. Merchants also need receipt history, line items, tax data, notifications, shipping status, and a way to review sales later. + +## What Orders stores + +Orders can store normalized paid order data such as: + +- line items +- totals +- tax information +- exchange-rate data +- source TPoS or WebShop details +- payment hash or payment reference +- metadata needed for receipt and fulfillment flows + +## Basic setup + +1. Enable the [Orders extension](/extensions/orders/). +2. Enable TPoS or WebShop. +3. Complete a test payment. +4. Open Orders. +5. Confirm the paid order appears. + +## Notifications + +Orders can notify the merchant or staff when a sale happens. + +Supported notification targets include: + +- Telegram chat ID +- Nostr npub +- email address + +Use notifications when: + +- the owner is not always in the shop +- WebShop orders need fulfillment +- kitchen or staff workflows depend on new order alerts +- an advisor wants to confirm that a merchant setup is working + +## Receipt and fulfillment workflows + +Orders can support: + +- customer digital receipts +- internal order tickets +- shipping labels +- shipped/unshipped status +- follow-up messages when an order ships + +Use these workflows to connect payment acceptance to real operations. + +## Related pages + +- [Orders extension](/extensions/orders/) +- [TPoS](/merchant-stack/tpos) +- [WebShop](/merchant-stack/webshop) +- [Bookkeeping](/merchant-stack/bookkeeping) + diff --git a/docs/merchant-stack/quick-start.md b/docs/merchant-stack/quick-start.md new file mode 100644 index 0000000..db08e47 --- /dev/null +++ b/docs/merchant-stack/quick-start.md @@ -0,0 +1,93 @@ +# Quick Start With LNbits SaaS + +> The fastest way to try Merchant Stack is to create a hosted LNbits instance and install the merchant extensions. + +LNbits SaaS gives you a full LNbits instance without running a server. Use it for real shops, demos, popups, workshops, or merchant onboarding. + +## Before you start + +You need: + +- access to [my.lnbits.com](https://my.lnbits.com) +- a payment method supported by the selected plan +- a name or subdomain for the instance +- a decision about funding source + +For a first merchant test, use the default hosted path unless you already know which Lightning backend you want to connect. + +## Create an instance + +1. Go to [my.lnbits.com](https://my.lnbits.com). +2. Create or sign in to your account. +3. Choose a plan and billing period. +4. Choose a subdomain. +5. Pay for the instance. +6. Wait for provisioning to finish. +7. Open the instance and complete first setup. + +::: tip +Hourly or weekly billing is useful for demos, popups, events, and workshops. Monthly or yearly billing is better for ongoing merchant use. +::: + +## Complete first setup + +When the instance is ready: + +1. Use the first install token if prompted. +2. Create the super user. +3. Choose a strong password. +4. Confirm the funding source. +5. Create or select the wallet the merchant will use for sales. + +::: warning +Keep super-user access limited. Some merchant features, such as manual settlement entries or Bitcoin selling, can affect accounting records and should be controlled carefully. +::: + +## Install merchant extensions + +Install these first: + +- [TPoS](/extensions/tpos/) for checkout +- [Inventory](/extensions/inventory/) for products +- [Orders](/extensions/orders/) for order history and notifications + +Then add the extensions the merchant needs: + +- [WebShop](/extensions/webshop/) for online sales +- Tabs for open balances and deferred settlement +- [WebPages](/extensions/webpages/) for same-origin shop embeds +- [Chat](/extensions/chat/) for website support flows + +## First test workflow + +Use a simple test before adding more complexity: + +1. Create one inventory item. +2. Create one TPoS terminal. +3. Connect TPoS to the inventory item. +4. Enable Orders. +5. Open the TPoS public page. +6. Add the item to the cart. +7. Complete a small test payment. +8. Confirm the payment appears in Orders. +9. Confirm stock changed as expected. + +## What to configure next + +After the first test payment: + +- add the real product catalog +- configure staff or owner notifications +- configure receipt details +- add card payments if needed +- set up printing and hardware +- add WebShop for online sales +- add Tabs for hospitality or account workflows + +## Related pages + +- [LNbits SaaS](/guide/installation/saas) +- [TPoS setup](/merchant-stack/tpos) +- [Inventory setup](/merchant-stack/inventory) +- [Orders setup](/merchant-stack/orders) + diff --git a/docs/merchant-stack/tabs.md b/docs/merchant-stack/tabs.md new file mode 100644 index 0000000..df60a5f --- /dev/null +++ b/docs/merchant-stack/tabs.md @@ -0,0 +1,71 @@ +# Use Tabs For Open Balances + +> Tabs lets merchants charge now and settle later. + +Use Tabs when the merchant needs open balances for customers, tables, teams, events, hospitality, house accounts, or internal staff accounts. + +Tabs can be used on its own as a merchant ledger, or connected to [TPoS](/merchant-stack/tpos) when point-of-sale carts should be booked to a tab. + +## Common use cases + +- cafe or bar tabs +- restaurant tables +- event organizer tabs +- office kitchen accounts +- corporate house accounts +- coworking or hospitality billing +- service-session billing + +## What a tab records + +A tab can include: + +- charges +- credits +- adjustments +- settlements +- notes +- running balance +- public payment page +- audit history + +## Basic flow + +1. Create a tab for a customer, table, event, team, or account. +2. Add charges as activity happens. +3. Add notes when context matters. +4. Settle part or all of the balance. +5. Close the tab when the balance reaches zero. +6. Archive tabs that should remain available for history. + +## Settlement methods + +Tabs can support: + +- Lightning invoice settlement +- cash settlement +- card settlement +- bank transfer +- other manual settlement +- write-off + +## Optional TPoS workflow + +For point-of-sale use, Tabs can connect to TPoS: + +1. Staff builds a cart in TPoS. +2. Staff chooses to book or add the cart to a tab. +3. TPoS sends a summarized charge to Tabs. +4. Tabs updates the balance. +5. The cart clears. +6. The customer settles later. + +## Public tab page + +A public tab page lets the payer inspect the open balance and pay without giving them access to the merchant management UI. + +## Related pages + +- [TPoS](/merchant-stack/tpos) +- [Orders](/merchant-stack/orders) +- [Hardware and printing](/merchant-stack/hardware) diff --git a/docs/merchant-stack/tpos.md b/docs/merchant-stack/tpos.md new file mode 100644 index 0000000..ea4280e --- /dev/null +++ b/docs/merchant-stack/tpos.md @@ -0,0 +1,92 @@ +# Set Up TPoS + +> TPoS is the in-person checkout surface for Merchant Stack. + +Use TPoS when a merchant needs a touch-friendly point of sale for Lightning payments, card payments, cash validation, receipts, tips, and product-based checkout. + +## What TPoS can do + +Depending on configuration, TPoS can support: + +- Lightning invoices +- product carts +- tips +- tax settings +- Stripe fiat payment integration +- cash validation +- on-chain payments with a watch-only wallet +- remote payment display on another device +- customer receipts +- internal order receipts +- OTC Bitcoin selling through LNURL withdraw + +## Basic setup + +1. Enable the [TPoS extension](/extensions/tpos/). +2. Create a new TPoS. +3. Choose the wallet that receives payments. +4. Choose the display currency. +5. Configure store details such as name, address, and VAT ID if needed. +6. Open the TPoS public page. +7. Make a test Lightning payment. + +## Use shared Inventory + +For a real merchant setup, use [Inventory](/merchant-stack/inventory) instead of keeping a separate product list only inside TPoS. + +Shared Inventory lets the merchant: + +- reuse the same products in TPoS and WebShop +- track stock in one place +- filter products with tags +- keep product names and prices consistent + +## Card payments + +TPoS can work with fiat providers such as Stripe when the LNbits instance and companion app are configured correctly. + +For Android tap-to-pay with Stripe, see [TPoS Wrapper](/apps/tpos-wrapper). + +::: warning +Stripe tap-to-pay depends on compatible Android hardware. Use a GMS-certified device with NFC support and test it before relying on it in production. +::: + +## Remote payment device + +Many small shops use a two-device checkout: + +1. Staff builds the cart on a computer. +2. Staff clicks pay. +3. The payment appears on a customer-facing phone or POS device. +4. Customer scans the Lightning QR or taps a card. +5. Completion syncs back to the staff screen. + +This is useful when the staff computer is not easy for the customer to scan or tap. + +## Receipts + +TPoS can be used with receipt printing workflows: + +- **Customer receipt** for the buyer +- **Order receipt** for internal preparation, such as a kitchen or barista ticket + +See [Hardware and printing](/merchant-stack/hardware) before choosing devices or printers. + +## Super-user features + +Some features should be limited to trusted operators: + +- cash settlement entries +- on-chain settlement entries +- OTC Bitcoin selling + +These can affect accounting records or move funds, so keep access controlled and document how the merchant should use them. + +## Related pages + +- [TPoS extension](/extensions/tpos/) +- [TPoS Wrapper app](/apps/tpos-wrapper) +- [Inventory](/merchant-stack/inventory) +- [Orders](/merchant-stack/orders) +- [Hardware and printing](/merchant-stack/hardware) + diff --git a/docs/merchant-stack/troubleshooting.md b/docs/merchant-stack/troubleshooting.md new file mode 100644 index 0000000..b533bab --- /dev/null +++ b/docs/merchant-stack/troubleshooting.md @@ -0,0 +1,87 @@ +# Troubleshooting Merchant Stack + +> Start with the workflow that failed: SaaS setup, payment, inventory, order capture, hardware, or notifications. + +## SaaS instance is not ready + +Try: + +- wait a few minutes for provisioning +- refresh the SaaS dashboard +- confirm the payment was completed +- check whether the instance has an admin URL +- use the first install token if prompted + +See [LNbits SaaS](/guide/installation/saas) for the hosted setup flow. + +## Products do not appear in TPoS + +Check: + +- Inventory extension is enabled +- products are active and in stock +- the TPoS is configured to use Inventory +- tags or categories match the TPoS filter +- the TPoS page was refreshed after changes + +## Orders are not captured + +Check: + +- Orders extension is enabled for the user +- the payment actually settled +- the order source is TPoS or WebShop +- notification settings are not being confused with order capture + +## Card tap-to-pay does not work + +Check: + +- Stripe is configured as the fiat provider +- the Android device supports NFC +- the device is compatible with Stripe tap-to-pay requirements +- the TPoS Wrapper app is installed +- the Stripe Terminal location ID is correct +- the LNbits ACL token includes the needed fiat permission +- the device is online + +## QR pairing does not scan + +Try: + +- increase screen brightness +- open the QR code on a white background +- move away from glare +- clean the device camera +- use a larger display +- retry after saving the TPoS settings + +## Printer does not print + +Check: + +- printer is powered on +- printer is paired or available to the device +- TPoS Wrapper app can see the printer +- test print works +- paper is loaded +- receipt width matches printer paper +- silent printing permission is available + +## Notifications do not arrive + +Check: + +- notification target is configured correctly +- Telegram chat ID, Nostr npub, or email address is valid +- global notification settings are configured if required +- the order was captured +- spam filters for email + +## Related pages + +- [Quick Start](/merchant-stack/quick-start) +- [TPoS](/merchant-stack/tpos) +- [Orders](/merchant-stack/orders) +- [Hardware and printing](/merchant-stack/hardware) + diff --git a/docs/merchant-stack/webshop.md b/docs/merchant-stack/webshop.md new file mode 100644 index 0000000..0cc86ee --- /dev/null +++ b/docs/merchant-stack/webshop.md @@ -0,0 +1,79 @@ +# Sell Online With WebShop + +> WebShop adds an online sales channel to the same merchant stack. + +Use WebShop when the merchant wants a direct shop page or an embeddable shop on an existing website. + +## How it works + +WebShop uses Inventory products and creates a public shop where customers can: + +- browse products +- add items to a cart +- check out +- pay with Lightning +- receive an order page or receipt + +Orders can capture the paid order for merchant review and fulfillment. + +## Basic setup + +1. Enable [Inventory](/extensions/inventory/) and create products. +2. Enable [WebShop](/extensions/webshop/). +3. Create a shop. +4. Choose the wallet for payments. +5. Select the inventory products or tags to expose. +6. Open the public shop page. +7. Complete a test checkout. +8. Confirm the order appears in Orders. + +## Embed options + +WebShop supports two common embed modes. + +### Iframe + +Use iframe mode when embedding the shop into an external website. + +```html + +``` + +### Same-origin component + +Use component mode for pages served from the same LNbits server, such as a page built with the WebPages extension. + +```html +
+ + +``` + +Component mode can avoid iframe limitations and allows more direct interaction with the shop page. + +## Fulfillment + +For shipping workflows: + +1. collect the contact or shipping details the merchant needs +2. capture the paid order in Orders +3. print a label or use the order details for fulfillment +4. mark the order shipped when complete +5. send a customer update if email notifications are configured + +## Related pages + +- [WebShop extension](/extensions/webshop/) +- [Inventory](/merchant-stack/inventory) +- [Orders](/merchant-stack/orders) +- [WebPages extension](/extensions/webpages/) + diff --git a/docs/public/merchant_stack/lnbitsbox_small.png b/docs/public/merchant_stack/lnbitsbox_small.png new file mode 100644 index 0000000..3b8d6dd Binary files /dev/null and b/docs/public/merchant_stack/lnbitsbox_small.png differ