20 · Crypto & card payments
How money other than cash enters GPE today — non-custodial crypto (strength), card/terminal providers (partial), and what storefront needs to feel like real e-commerce.
Non-negotiable: invoicing spine
Sales should end as Invoices via Core Invoicing (usually POS finalize).
Do not revive parallel ledgers. Legacy /api/payments Stripe/Coinbase router is
off when ENABLE_LEGACY_3P ≠ 1.
flowchart LR
TENDER[Tender on cart]
FIN[finalize]
INV[Core Invoicing]
TENDER --> FIN --> INV
CRYPTO[Crypto address + watcher]
CRYPTO --> TENDER
CARD[Card / terminal]
CARD --> TENDER
Cryptocurrency (platform differentiator)
Non-custodial model
Businesses hold keys/wallets; platform watches chain / price and links payment to invoice.
DOGE · LTC · BTC paths appear in UI/services (config dependent).
| Area | What exists |
|---|---|
| Config UI | /admin/crypto · CryptoConfig · crypto-config API |
| Wallets UI | /crypto-wallet · /api/crypto-wallet/* |
| Addresses | POST /api/doge/address · LTC routes · HD helpers in services |
| Watchers | dogeWatcher · ltcWatcher · price watchers (in backend process) |
| Webhooks | /api/webhooks/doge · /ltc walletnotify; also Coinbase/Coinremitter mounts |
| Prices | /api/crypto-prices/* public-ish spot/quote |
| POS | tender/crypto on cart · QR / amount · Modern + Mobile + Storefront crypto path |
Bridge can expose cryptoRpc for local node ops when configured.
Card & payment providers
| Layer | Status |
|---|---|
| POS tender card | Generic card tender on cart; often “record card payment” style depending on provider wiring |
| Terminals | Routes for stripe-terminal, square-terminal, ingenico, verifone, adyen, paypal on pos.routes — UI partial |
| payment-providers API | /api/payment-providers — configure provider + terminal-config + bin rules |
| admin payments | /api/admin/payments/providers metadata CRUD/test |
| /api/v1 payments | Broader payments-engine style surface (merchants, ledger, keys, recon) — parallel sophistication |
| Legacy /api/payments | Stripe Terminal + Coinbase Commerce writing outside invoicing — disabled by default |
Not “PayPal Checkout for storefront” out of the box
There is no polished public hosted checkout (PayPal/Stripe Checkout redirect) on storefront today.
Card/crypto tenders assume the POS/storefront cart session model.
What storefront needs for real e-commerce
Your read is correct — storefront is a start, not Square Online / PayPal Commerce yet.
| # | Capability | Why |
|---|---|---|
| 1 | Guest (or shopper) session for /api/pos | Today POS requires platform session; public shoppers hit a wall |
| 2 | Server-side allowGuestCheckout / requireAccount | Flags exist in config only |
| 3 | Card processor on finalize path | Stripe/PayPal/etc. that create PaymentIntent, confirm, then finalize invoice — not legacy parallel table |
| 4 | Webhooks → invoice paid | Async card capture like crypto watchers |
| 5 | Receipts / email / order history | Customer portal + CRM link |
| 6 | Optional shipping / tax UX | Flags only today |
| 7 | PCI-safe UX | Hosted fields / redirect; never raw PAN on GPE if possible |
Recommended direction
Keep cart + Core Invoicing as the spine. Add a
tender/stripe (or PayPal) that is storefront-safe + guest cart auth,
rather than resurrecting ENABLE_LEGACY_3P.
File anchors
| Concern | Path |
|---|---|
| POS tenders | pos.routes.js tender/* · finalize |
| Crypto config/wallet | crypto-config.routes.js · crypto-wallet.routes.js |
| DOGE/LTC | doge.routes.js · ltc.routes.js · watchers · webhooks |
| Providers | paymentProviders.routes.js · admin.payments.routes.js |
| v1 engine | backend/payments/api/v1/* |
| Legacy | payments.routes.js gated ENABLE_LEGACY_3P |
| UI | Crypto.jsx · CryptoWallet · CryptoConfig · payment methods admin |
| OAO | 07 Cryptocurrency · 04 payments engine HTML |