| … | … | @@ -0,0 +1,68 @@ |
| 1 | # hyper-pay | |
| 2 | ||
| 3 | Generic payment module and embeddable checkout widget. | |
| 4 | ||
| 5 | ## What is this? | |
| 6 | ||
| 7 | A payment rail abstraction layer that unifies multiple payment methods behind one interface, plus an embeddable checkout widget for any website. | |
| 8 | ||
| 9 | ### Library | |
| 10 | ||
| 11 | Consumed by other projects (hyper-wallet, hyper-booking, etc.) to handle payments without coupling to a specific provider. | |
| 12 | ||
| 13 | ### Widget | |
| 14 | ||
| 15 | Drop-in checkout component for any website: | |
| 16 | ||
| 17 | ```html | |
| 18 | <script src="https://hyper-pay.example/embed.js"></script> | |
| 19 | <hyper-pay merchant="..." amount="100" /> | |
| 20 | ``` | |
| 21 | ||
| 22 | ## Payment Rails | |
| 23 | ||
| 24 | | Rail | Provider | Fee | Best for | | |
| 25 | |------|----------|-----|----------| | |
| 26 | | Credit/debit cards | Stripe Connect | 2.9% + 30¢ | Default checkout, universal | | |
| 27 | | ACH bank transfer | Stripe Connect | 0.8%, max $5 | Memberships, packages, B2B | | |
| 28 | | USDC stablecoin | Stripe | 1.5% | Crypto-native customers | | |
| 29 | | x402 protocol | Coinbase facilitator | $0.001/tx | API/agent payments, programmatic | | |
| 30 | | USDT / direct P2P | Tether WDK | Near-zero (gas only) | Self-custodial, no intermediary | | |
| 31 | | hyper-wallet | P2P | Zero platform fee | Direct peer-to-peer settlement | | |
| 32 | ||
| 33 | ## Architecture | |
| 34 | ||
| 35 | ``` | |
| 36 | hyper-pay/ | |
| 37 | ├── lib/ # Payment rail abstraction | |
| 38 | │ ├── stripe.js # Stripe Connect — cards, ACH, USDC | |
| 39 | │ ├── stablecoin.js # Direct stablecoin payments | |
| 40 | │ ├── x402.js # x402 protocol (agent/API payments) | |
| 41 | │ ├── wdk.js # Tether WDK integration | |
| 42 | │ └── wallet.js # hyper-wallet P2P payments | |
| 43 | ├── widget/ # Embeddable checkout UI | |
| 44 | │ ├── embed.js # <script> tag drop-in | |
| 45 | │ └── components/ # Payment form, method selector | |
| 46 | └── docs/ | |
| 47 | └── research/ # Payment ecosystem research | |
| 48 | ``` | |
| 49 | ||
| 50 | ## Integration Points | |
| 51 | ||
| 52 | ``` | |
| 53 | hyper-wallet (app) | |
| 54 | ├── hyper-wallet-lib (identity, storage, validation) | |
| 55 | └── hyper-pay (this module — payment rails) | |
| 56 | ||
| 57 | hyper-booking (future app) | |
| 58 | ├── hyper-pay (this module — payment rails) | |
| 59 | ├── scheduling engine | |
| 60 | └── marketplace UI | |
| 61 | ||
| 62 | any-website | |
| 63 | └── hyper-pay widget (embeddable checkout) | |
| 64 | ``` | |
| 65 | ||
| 66 | ## Status | |
| 67 | ||
| 68 | Research phase. See `docs/research/` for payment ecosystem analysis. |
| … | … | @@ -0,0 +1,175 @@ |
| 1 | # hyper-pay Architecture | |
| 2 | ||
| 3 | ## Overview | |
| 4 | ||
| 5 | hyper-pay is two things: | |
| 6 | ||
| 7 | 1. **Library** — payment rail abstraction consumed by hyper-wallet, hyper-booking, and other projects | |
| 8 | 2. **Widget** — embeddable checkout component for any website | |
| 9 | ||
| 10 | ## Design Principles | |
| 11 | ||
| 12 | - **Rail-agnostic** — application code calls `hyper-pay.charge()`, doesn't care if it's Stripe, USDC, or P2P | |
| 13 | - **Multi-tenant** — each merchant has their own payment configuration and payout preferences | |
| 14 | - **Embeddable** — drop a script tag on any page, get a full checkout | |
| 15 | - **Extensible** — new payment rails are plugins, not rewrites | |
| 16 | - **Dogfooded** — used by our own booking platform first | |
| 17 | ||
| 18 | ## Payment Rail Interface | |
| 19 | ||
| 20 | Every rail implements the same interface: | |
| 21 | ||
| 22 | ``` | |
| 23 | PaymentRail { | |
| 24 | authorize(amount, currency, customer, merchant) → PaymentIntent | |
| 25 | capture(paymentIntent) → Settlement | |
| 26 | refund(settlement, amount?) → Refund | |
| 27 | webhook(event) → void | |
| 28 | supports(currency, country) → boolean | |
| 29 | } | |
| 30 | ``` | |
| 31 | ||
| 32 | ## Rail Implementations | |
| 33 | ||
| 34 | ### stripe-card | |
| 35 | - Stripe Payment Intents API | |
| 36 | - Stripe Connect for merchant payouts | |
| 37 | - Supports auth/capture (deposits, delayed payment) | |
| 38 | ||
| 39 | ### stripe-ach | |
| 40 | - ACH Direct Debit via Stripe | |
| 41 | - Bank account verification | |
| 42 | - 3-5 day settlement | |
| 43 | ||
| 44 | ### stripe-stablecoin | |
| 45 | - USDC via Stripe (1.5% fee) | |
| 46 | - Settles to USD or keeps as USDC | |
| 47 | - Merchant choice | |
| 48 | ||
| 49 | ### x402 | |
| 50 | - Coinbase x402 protocol | |
| 51 | - For API/agent payments | |
| 52 | - Near-zero cost ($0.001/tx) | |
| 53 | - Session support (V2) for high-frequency | |
| 54 | ||
| 55 | ### wdk | |
| 56 | - Tether WDK integration | |
| 57 | - Gasless via Paymaster | |
| 58 | - Direct USDT payments | |
| 59 | ||
| 60 | ### hyper-wallet | |
| 61 | - P2P via hyper-wallet | |
| 62 | - Zero intermediary fees | |
| 63 | - Instant settlement | |
| 64 | - Self-custodial | |
| 65 | ||
| 66 | ## Smart Routing | |
| 67 | ||
| 68 | Given amount, currency, country, and merchant preferences, auto-select cheapest viable rail: | |
| 69 | ||
| 70 | ``` | |
| 71 | if amount > $625 && domestic → ACH ($5 cap) | |
| 72 | if customer has crypto wallet → stablecoin (1.5% or less) | |
| 73 | if agent/API request → x402 ($0.001) | |
| 74 | if both parties have hyper-wallet → P2P (free) | |
| 75 | default → card (2.9% + 30¢) | |
| 76 | ``` | |
| 77 | ||
| 78 | ## Multi-Tenant Model | |
| 79 | ||
| 80 | ``` | |
| 81 | Platform (us) | |
| 82 | ├── Merchant A (wellness coach) | |
| 83 | │ ├── Stripe Connected Account | |
| 84 | │ ├── hyper-wallet address | |
| 85 | │ ├── Enabled rails: [card, ACH, USDC] | |
| 86 | │ └── Platform fee: 5% | |
| 87 | ├── Merchant B (yoga studio) | |
| 88 | │ ├── Stripe Connected Account | |
| 89 | │ ├── Enabled rails: [card, hyper-wallet] | |
| 90 | │ └── Platform fee: 3% | |
| 91 | └── ... | |
| 92 | ``` | |
| 93 | ||
| 94 | ## Widget Architecture | |
| 95 | ||
| 96 | The embeddable widget renders a payment form that adapts to the merchant's enabled rails: | |
| 97 | ||
| 98 | ``` | |
| 99 | <hyper-pay | |
| 100 | merchant="merchant_id" | |
| 101 | amount="100" | |
| 102 | currency="USD" | |
| 103 | description="60min Massage" | |
| 104 | on-success="handleSuccess" | |
| 105 | on-error="handleError" | |
| 106 | /> | |
| 107 | ``` | |
| 108 | ||
| 109 | Implementation options: | |
| 110 | - **Web Component** — framework-agnostic, Shadow DOM isolation | |
| 111 | - **iframe** — maximum isolation, PCI compliance simplicity | |
| 112 | - **React/Preact component** — for React-based sites | |
| 113 | ||
| 114 | Likely: iframe for payment form (PCI), web component for the container. | |
| 115 | ||
| 116 | ## Integration Map | |
| 117 | ||
| 118 | ``` | |
| 119 | ┌─────────────────┐ ┌─────────────────┐ | |
| 120 | │ hyper-wallet │ │ hyper-booking │ | |
| 121 | │ (crypto app) │ │ (booking SaaS) │ | |
| 122 | └────────┬────────┘ └────────┬────────┘ | |
| 123 | │ │ | |
| 124 | └───────┐ ┌──────────┘ | |
| 125 | │ │ | |
| 126 | ┌──────▼───▼──────┐ | |
| 127 | │ hyper-pay │ | |
| 128 | │ (this module) │ | |
| 129 | ├──────────────────┤ | |
| 130 | │ lib/ │ | |
| 131 | │ stripe, ach, │ | |
| 132 | │ stablecoin, │ | |
| 133 | │ x402, wdk, │ | |
| 134 | │ hyper-wallet │ | |
| 135 | ├──────────────────┤ | |
| 136 | │ widget/ │ | |
| 137 | │ embeddable │ | |
| 138 | │ checkout UI │ | |
| 139 | └──────────────────┘ | |
| 140 | │ | |
| 141 | ┌────────────┼────────────┐ | |
| 142 | │ │ │ | |
| 143 | ┌───▼───┐ ┌────▼────┐ ┌───▼────┐ | |
| 144 | │Stripe │ │Coinbase │ │ P2P │ | |
| 145 | │Connect│ │ x402 │ │Network │ | |
| 146 | └───────┘ └─────────┘ └────────┘ | |
| 147 | ``` | |
| 148 | ||
| 149 | ## Phased Build Plan | |
| 150 | ||
| 151 | ### Phase 1: Foundation | |
| 152 | - Stripe card payments via Connect | |
| 153 | - Single merchant (dogfood) | |
| 154 | - Basic widget (iframe) | |
| 155 | ||
| 156 | ### Phase 2: Multi-rail | |
| 157 | - ACH support | |
| 158 | - Stablecoin via Stripe (USDC) | |
| 159 | - Payment method selection in widget | |
| 160 | ||
| 161 | ### Phase 3: Crypto-native | |
| 162 | - x402 protocol support | |
| 163 | - hyper-wallet integration | |
| 164 | - Smart routing | |
| 165 | ||
| 166 | ### Phase 4: Platform | |
| 167 | - Multi-tenant merchant onboarding | |
| 168 | - Merchant dashboard | |
| 169 | - Discovery marketplace integration | |
| 170 | ||
| 171 | ### Phase 5: Advanced | |
| 172 | - Tether WDK integration | |
| 173 | - Custom stablecoin issuance (via Bridge) | |
| 174 | - AI agent payments | |
| 175 | - International expansion |
| … | … | @@ -0,0 +1,179 @@ |
| 1 | # Payment Landscape Research | |
| 2 | ||
| 3 | Research conducted 2026-03-21. | |
| 4 | ||
| 5 | ## Decision: Stripe Connect as Primary Rail | |
| 6 | ||
| 7 | For a multi-tenant booking platform built from the ground up, Stripe Connect is the clear choice: | |
| 8 | ||
| 9 | - Onboard merchants as Connected Accounts | |
| 10 | - Set platform fees on every transaction | |
| 11 | - Stripe handles payouts, KYC, tax reporting, disputes | |
| 12 | - Same API for online and in-person (Stripe Terminal) | |
| 13 | - Stablecoin support built in (USDC at 1.5%) | |
| 14 | - Best docs and developer experience in the space | |
| 15 | ||
| 16 | ### Revenue Model | |
| 17 | ||
| 18 | ``` | |
| 19 | Customer pays $100 for a booking | |
| 20 | → $5 platform fee (we keep) | |
| 21 | → $95 to the merchant/coach | |
| 22 | → Stripe takes ~$3.20 from the $100 | |
| 23 | ``` | |
| 24 | ||
| 25 | ## Payment Rails Comparison | |
| 26 | ||
| 27 | ### Stripe (Primary) | |
| 28 | ||
| 29 | | Fee type | Cost | | |
| 30 | |----------|------| | |
| 31 | | Online card payments | 2.9% + 30¢ (US) | | |
| 32 | | In-person (Terminal) | 2.6% + 10¢ | | |
| 33 | | International cards | +1% | | |
| 34 | | Currency conversion | +1% | | |
| 35 | | Stablecoin (USDC) | 1.5% | | |
| 36 | | ACH Direct Debit | 0.8%, max $5.00 | | |
| 37 | | ACH Credit | $1.00 flat | | |
| 38 | | Failed ACH | $4.00 | | |
| 39 | | Disputes/chargebacks | $15 | | |
| 40 | | Monthly fee | $0 | | |
| 41 | ||
| 42 | ACH sweet spot: bookings over $200 (memberships, packages, B2B). | |
| 43 | ||
| 44 | ### x402 Protocol (Coinbase) | |
| 45 | ||
| 46 | - Open standard using HTTP 402 status code for stablecoin payments | |
| 47 | - Created by Coinbase (May 2025), backed by Stripe, Cloudflare, Visa, Circle, AWS, Google | |
| 48 | - Free tier: 1,000 settled payments/month, then $0.001 per payment | |
| 49 | - Protocol itself charges zero fees | |
| 50 | - Facilitator sponsors gas fees | |
| 51 | - SDKs: TypeScript, Go, Python | |
| 52 | - Multi-chain: Base, Polygon, Solana | |
| 53 | - 100M+ payments processed in first 6 months | |
| 54 | - V2 (Jan 2026) adds session support for high-frequency use cases | |
| 55 | ||
| 56 | Best for: API monetization, AI agent bookings, programmatic payments. | |
| 57 | ||
| 58 | ### Tether WDK | |
| 59 | ||
| 60 | - Free, open source wallet development kit | |
| 61 | - Gasless transactions via Candide Paymaster (currently waiving surcharges) | |
| 62 | - Supports Bitcoin, Lightning, USDT, XAUT | |
| 63 | - Includes fiat on/off-ramp modules | |
| 64 | - ERC-4337 account abstraction on EVM chains | |
| 65 | - Fee-free on TON (paymaster) and Tron (gas-free service) | |
| 66 | ||
| 67 | Best for: Self-custodial merchant payouts, P2P settlement. | |
| 68 | ||
| 69 | ### hyper-wallet (Our Own) | |
| 70 | ||
| 71 | - Direct peer-to-peer settlement | |
| 72 | - No intermediary, no platform fee on the payment itself | |
| 73 | - Customer wallet → Coach wallet | |
| 74 | - Bitcoin (Lightning), USDT, direct transfer | |
| 75 | - Unique differentiator vs every other booking platform | |
| 76 | ||
| 77 | ## Cost Comparison: $100 Booking | |
| 78 | ||
| 79 | | Method | Platform cost | Merchant receives | Settlement | | |
| 80 | |--------|--------------|-------------------|------------| | |
| 81 | | Stripe (card) | ~$3.20 | ~$96.80 | 2-3 days | | |
| 82 | | Stripe (USDC) | ~$1.50 | ~$98.50 | Same day | | |
| 83 | | Stripe (ACH) | ~$0.80 | ~$99.20 | 3-5 days | | |
| 84 | | x402 (USDC on Base) | ~$0.001 | ~$99.99 | ~2 seconds | | |
| 85 | | Direct USDT (Base) | <$0.01 | ~$99.99 | ~1 second | | |
| 86 | | hyper-wallet P2P | $0 | $100.00 | Instant | | |
| 87 | ||
| 88 | + fiat off-ramp adds 0.5-1.5% if merchant wants USD in their bank. | |
| 89 | ||
| 90 | ## Stablecoin Checkout Reality Check | |
| 91 | ||
| 92 | Current state (2026): stablecoin checkout requires customers to already hold crypto in a wallet. No seamless fiat-to-crypto onramp at checkout yet. | |
| 93 | ||
| 94 | ### Wallet Connection Methods | |
| 95 | ||
| 96 | 1. **EIP-6963** — browser extension discovery (MetaMask, Coinbase Wallet, etc.) | |
| 97 | 2. **WalletConnect** — QR code / deep link for mobile wallets | |
| 98 | 3. **Coinbase Smart Wallet** — ERC-4337 account abstraction, gasless | |
| 99 | ||
| 100 | ### Practical Split | |
| 101 | ||
| 102 | - ~90% of customers will use cards (Stripe) | |
| 103 | - ~5-10% crypto-native users will use stablecoin | |
| 104 | - API/agent payments via x402 growing rapidly | |
| 105 | ||
| 106 | ### Shopify/Coinbase Integration (Reference) | |
| 107 | ||
| 108 | Shopify + Coinbase Commerce Protocol: | |
| 109 | - USDC on Base, gasless for customers | |
| 110 | - Escrow smart contract (auth/capture like cards) | |
| 111 | - 480 supported wallets | |
| 112 | - Merchants settle in local currency or keep USDC | |
| 113 | - No fiat onramp at checkout — customer must already hold USDC | |
| 114 | ||
| 115 | ## Stripe vs Square Decision | |
| 116 | ||
| 117 | Chose Stripe over Square because: | |
| 118 | ||
| 119 | - **Developer control** — full API, not locked into Square's ecosystem | |
| 120 | - **Multi-tenant / ISV** — Stripe Connect purpose-built for platforms | |
| 121 | - **Stablecoin native** — Square has no stablecoin support | |
| 122 | - **Extensibility** — essentially unlimited growth path | |
| 123 | - **International** — 135+ currencies vs Square's limited reach | |
| 124 | ||
| 125 | Square advantages we're giving up: | |
| 126 | - Built-in appointment scheduling (we'll build our own) | |
| 127 | - Turnkey POS hardware (Stripe Terminal is viable alternative) | |
| 128 | - Faster time to market (we're building from scratch anyway) | |
| 129 | ||
| 130 | ## Non-Viable Options | |
| 131 | ||
| 132 | ### Zelle | |
| 133 | ||
| 134 | No public API. Bank-to-bank only. Cannot programmatically accept or verify payments. Not suitable for any automated checkout. | |
| 135 | ||
| 136 | ### Coinbase Commerce (as fiat gateway) | |
| 137 | ||
| 138 | Crypto-only. Does NOT accept credit cards or bank transfers. Useful for USDC acceptance but not a Stripe replacement. | |
| 139 | ||
| 140 | ## Other Platforms Evaluated | |
| 141 | ||
| 142 | ### All-in-One Wellness (Buy, Don't Build) | |
| 143 | ||
| 144 | Mindbody, Vagaro, Zenoti, Boulevard, Mangomint, Fresha, GlossGenius, Pabau — all bundle booking + payments. Rejected because we need full control and the payment module must be generic/reusable. | |
| 145 | ||
| 146 | ### Booking + Payment Integration (Mix and Match) | |
| 147 | ||
| 148 | Acuity Scheduling, SimplyBook.me, Workee — booking platforms that integrate with Stripe/PayPal. Could be competitors to hyper-booking but don't offer the P2P/stablecoin rails. | |
| 149 | ||
| 150 | ### ISV Payment Platforms | |
| 151 | ||
| 152 | | Platform | Assessment | | |
| 153 | |----------|-----------| | |
| 154 | | Stripe Connect | **Selected** — best docs, fastest integration, stablecoin support | | |
| 155 | | Adyen | Enterprise only, won't engage at our scale | | |
| 156 | | Braintree | Viable but PayPal sunsetting in favor of own platform | | |
| 157 | | Worldpay | Enterprise sales cycle, needs existing payments expertise | | |
| 158 | | Clover Connect | ISV-focused but tied to Clover hardware ecosystem | | |
| 159 | ||
| 160 | ## Stripe Bridge Acquisition ($1.1B) | |
| 161 | ||
| 162 | Stripe acquired Bridge (stablecoin infrastructure) in Feb 2025. This gives Stripe: | |
| 163 | - Orchestration — move/store/accept stablecoins via API | |
| 164 | - Issuance — businesses can launch their own stablecoin | |
| 165 | - Money Transfer — global fund movement in minutes | |
| 166 | - Visa card issuing — stablecoin-linked Visa cards (Latin America, expanding) | |
| 167 | ||
| 168 | Signals that Stripe is going all-in on stablecoin rails. Good bet for long-term alignment. | |
| 169 | ||
| 170 | ## Reference: Theater Toolkit / Majestic 10 | |
| 171 | ||
| 172 | Initial research started by analyzing Majestic 10 cinema checkout: | |
| 173 | - Platform: Theater Toolkit (cinema-specific website + ticketing) | |
| 174 | - Payment processor: Clover Connect (Fiserv) | |
| 175 | - POS integrations: NCR, RTS, Vista, Veezi | |
| 176 | - Server-side payment processing (no client-side SDK visible) | |
| 177 | - Example of how an ISV (Theater Toolkit) embeds payments for end businesses (theaters) | |
| 178 | ||
| 179 | This ISV model is what hyper-pay follows: we are the ISV, wellness businesses are our merchants. |