StackPay

StackPay is a Bitcoin-native payment gateway on Stacks for sBTC, STX, and USDCx. It combines on-chain invoices and payment routes with a merchant-facing Next.js console, Supabase-backed metadata, hosted checkout pages, receipts, and webhook-driven notifications.

The current working MVP supports:

• merchant profile setup tied to a Stacks wallet
• standard invoices created on-chain, then stored in Supabase after confirmation
• MultiPay payment links for reusable fixed-price or suggested-price checkout
• a universal QR route that accepts sBTC, STX, and USDCx
• hosted payment pages
• processor-based payment confirmation
• receipt PDF generation
• Hiro Chainhook ingestion for invoice-paid
• in-app notifications with toast + sound
• dashboard metrics from real merchant invoice/link data

StackPay currently uses:

• apps/web: Next.js 14 app router app, route handlers, merchant console, hosted checkout
• Supabase: off-chain source of truth for merchants, invoices, payment links, receipts, notifications, and activity
• packages/contracts/stackpay: Clarity contracts and tests
• Stacks wallets: merchant identity and contract signing

There is still an apps/api scaffold in the repo, but the active MVP backend now lives in Next.js route handlers under apps/web/app/api.

• apps/web: web app, API routes, hosted payment surfaces
• apps/api: legacy API scaffold, not the active MVP backend
• packages/contracts/stackpay: Clarity contracts and tests
• packages/domain: shared business metadata
• packages/integrations: integration/webhook manifests
• packages/sdk: SDK scaffolding
• packages/ui: navigation metadata and shared UI config
• packages/config: environment and network helpers
• supabase: Supabase config and migrations
• docs: MVP notes, Chainhook config, integration docs

1. Merchant completes profile setup.
2. Merchant creates a standard invoice from /create-invoice.
3. Wallet submits architecture.create-invoice.
4. Chain result returns the on-chain invoice id.
5. Only then does StackPay store the invoice in Supabase.
6. Customer pays from the hosted invoice page.
7. Payment confirmation creates a receipt and notification.

MultiPay is a reusable public payment route.

• it does not expire like a standard invoice
• it uses one currency
• it supports either:
  • one fixed amount
  • up to 3 suggested amounts
• each customer payment generates a fresh on-chain invoice under the hood

Merchant management:

• create from /create-invoice
• review all created MultiPay routes at /payment-links

The universal QR route is a permanent public route for flexible real-world payments.

• customers choose asset
• customers choose amount
• the route remains stable
• managed from /qr-link

The architecture + processor contracts handle:

• canonical invoice ids
• public link ids
• invoice/payment state
• receipt ids
• invoice-paid events for Chainhooks

Supabase stores:

• merchant profiles
• settlement wallet metadata
• invoices and public links for dashboard/querying
• receipts
• activity events
• notifications
• chainhook delivery state

Current payment notifications work like this:

1. Hiro Chainhook watches the deployed StackPay architecture contract.
2. On invoice-paid, Hiro posts to /api/webhooks/chainhooks.
3. StackPay confirms the invoice/receipt in Supabase.
4. A notification row is inserted.
5. The header bell and toast update from NotificationsButton.tsx.

The sample upload file is:

• docs/stackpay-chainhook-invoice-paid.json

Email notifications are not implemented yet. The current pipeline is in-app only.

Paid invoices can generate receipt PDFs through:

• /api/receipts/[receiptId]/pdf
• PDF generator lives in receipt-pdf.ts

Install dependencies:

npm install

Run the web app:

npm run dev

Build the app:

npm run build

Run contract tests:

npm run test:contracts

Copy envs:

cp apps/web/.env.example apps/web/.env.local

Start local Supabase:

npm run supabase:start

Apply migrations:

npm run supabase:db:reset

Stop local Supabase:

npm run supabase:stop

Authenticate and link:

npx supabase login
npx supabase link --project-ref YOUR_PROJECT_REF

Push migrations:

npm run supabase:db:push

If you switch from local to remote, make sure your remote DB actually has the current unique constraints used by upsert, especially on:

• merchant_profiles.wallet_address
• merchant_wallets.wallet_address
• invoices.onchain_invoice_id
• notifications.source_key
• chainhook_events.delivery_key

See apps/web/.env.example.

Important values:

• NEXT_PUBLIC_APP_URL
• NEXT_PUBLIC_STACKS_NETWORK
• NEXT_PUBLIC_SUPABASE_URL
• NEXT_PUBLIC_SUPABASE_ANON_KEY
• SUPABASE_SERVICE_ROLE_KEY
• NEXT_PUBLIC_STACKPAY_ARCHITECTURE_CONTRACT_ID
• NEXT_PUBLIC_STACKPAY_PROCESSOR_CONTRACT_ID
• STACKPAY_CHAINHOOK_SECRET
• STACKPAY_STACKS_API_URL (optional override)

Merchant pages:

• /dashboard
• /create-invoice
• /invoices
• /payment-links
• /qr-link
• /profile

Hosted/public pages:

• /pay/[invoiceId]
• /pay/link/[slug]

Core API routes:

• GET /api/merchant/profile
• POST /api/merchant/profile
• GET /api/invoices
• POST /api/invoices
• POST /api/invoices/confirm
• GET /api/payment-links
• POST /api/payment-links
• POST /api/payment-links/[paymentLinkId]/chain
• GET /api/payment-links/public/[slug]
• POST /api/payment-links/public/[slug]/invoices
• POST /api/payment-links/public/[slug]/invoices/confirm
• GET /api/qr-link
• POST /api/qr-link
• GET /api/notifications
• PATCH /api/notifications
• POST /api/webhooks/chainhooks

• The hosted merchant “open” actions now open in a new tab where appropriate.
• Recent dashboard activity is deduped server-side so a single invoice/link does not spam the feed.
• Notification sound is browser-dependent. Browsers may require prior user interaction before audio can play.

• docs/stackpay-mvp-blueprint.md
• docs/stackpay-supabase-mvp.md
• docs/stackpay-chainhook-invoice-paid.json

This SOP outlines the steps to create and manage invoices using the StackPay Bitcoin payment gateway.

1. Connect Your Wallet 0:42

• Log in to your StackPay dashboard.
• Navigate to the wallet connection section.
• Select your wallet and confirm the connection.

2. Set Up Your Profile 1:03

• Go to the profile settings.
• Enter your business name (e.g., Samuel Ventures).
• Set your display name (e.g., Sammy).
• Provide your invoice email address.
• Save your profile settings.

3. Create an Invoice 1:33

• Click on the 'Create Invoice' button.
• Choose the type of payment (Standard or Multi-Pay).
• For a Standard Invoice:
  • Enter the amount (e.g., 1 USDC).
  • Specify the customer’s email (e.g., Matt.searchme.com).
  • Set an expiration date for the invoice.
  • Describe the purpose of the payment (e.g., ebook).
• Click 'Generate Invoice' to create it.

4. Share the Invoice 2:37

• After generating the invoice, you can view it.
• Copy the invoice link to share with the customer.

5. Confirm Payment 3:07

• Once the customer pays, return to your dashboard.
• Check for payment notifications.
• Open the notification to confirm the payment has been received.

6. Download Receipt 3:33

• Navigate to the receipts section.
• Find the relevant receipt for the completed transaction.
• Download or print the receipt as needed.

7. Withdraw Funds 4:08

• Go to the funds withdrawal section.
• Specify the amount you wish to withdraw.
• Confirm the withdrawal request.

8. Access QR Code 4:37

• Locate the universal QR code in your dashboard.
• Click on it to view or share.

• Ensure that all wallet connections are secure to prevent unauthorized access.
• Double-check customer email addresses before sending invoices to avoid payment issues.

• Regularly update your profile information to ensure accurate invoicing.
• Use the Multi-Pay option for recurring customers to simplify payment processes.
• Keep track of invoice expiration dates to manage follow-ups effectively.

https://loom.com/share/b2135bb5820046e7a6fb9736c520580a