BitBNPL - Bitcoin Payment Infrastructure & BNPL Platform

Digital payments with Bitcoin, without selling it.

BitBNPL is a payment infrastructure that enables seamless digital payments using Bitcoin through MUSD stablecoin. More than just a Buy Now Pay Later platform, BitBNPL solves the fundamental problem of using Bitcoin for everyday purchases: Bitcoin holders can shop anywhere without selling their BTC.

How it works: Customers lock Bitcoin as collateral, borrow MUSD stablecoin against it, and make instant digital payments. Merchants receive immediate settlements in MUSD. Customers maintain full exposure to Bitcoin price appreciation while enjoying flexible payment options.

Built on Mezo blockchain with integrated MoonPay fiat onramp, Mezo Passport wallet infrastructure, and a comprehensive collateral lending protocol - BitBNPL provides the complete payment infrastructure: from fiat to Bitcoin, Bitcoin to MUSD, and MUSD to merchants. All while your Bitcoin remains securely locked as collateral, not sold.

Overview

The Problem We Solve

Bitcoin as a payment method is broken. Bitcoin holders face a dilemma:

Using Bitcoin for payments today means:

Selling BTC and missing potential price appreciation
Triggering taxable events on every purchase
Reducing your long-term Bitcoin position
Volatility makes pricing difficult for merchants
Slow settlement times (blockchain confirmations)

Existing solutions fall short:

Traditional payment processors don't support Bitcoin
Crypto payment gateways force users to spend appreciating assets
BNPL platforms don't work with cryptocurrency
Bitcoin Lightning has liquidity and adoption challenges

The BitBNPL Solution: A Complete Payment Infrastructure

BitBNPL is a Bitcoin payment infrastructure that bridges Bitcoin holders to digital commerce through MUSD stablecoin. We provide the complete payment rails:

Payment Infrastructure Layer:

Bitcoin → MUSD Conversion: Lock BTC as collateral, borrow stable MUSD for payments
Instant Settlements: Merchants receive MUSD immediately via liquidity pool
Stable Pricing: MUSD eliminates Bitcoin volatility for merchants
On-Chain Rails: All transactions on Mezo blockchain with BTC-secured finality
Fiat Onramp: MoonPay integration brings fiat users into Bitcoin ecosystem
Multi-Wallet Support: Mezo Passport connects Bitcoin wallets (Unisat, Xverse, OKX)

For Customers (Bitcoin Payment Users):

Pay with Bitcoin: Use your BTC for digital payments without selling it
MUSD Liquidity: Borrow MUSD stablecoin against BTC collateral (up to 90% LTV)
Flexible Options: Pay in full or split into installments (1, 4, 6, or 8 payments)
Keep BTC Upside: Your Bitcoin remains locked, not sold - capture price appreciation
Dashboard Control: Manage collateral, borrowing, repayments, and health in one place
Complete Onramp: Buy BTC with fiat → Lock → Borrow MUSD → Pay anywhere

For Merchants (Payment Acceptance):

Accept Bitcoin Payments: Tap into Bitcoin holder market via MUSD settlement
Instant Settlement: Receive full payment immediately in MUSD, not installments
Zero Volatility Risk: Get paid in stable MUSD, not volatile BTC
No Fraud Risk: Smart contract-guaranteed payments, no chargebacks
Easy Integration: Add payment widget in minutes - Simple Link, JS Widget, or React SDK
Verified Network: Admin-verified merchant registry on Mezo blockchain

Technical Infrastructure:

Mezo Blockchain: Bitcoin-native L2 with BTC gas fees and EVM compatibility
MUSD Stablecoin: Stable payment token borrowed against BTC collateral
Mezo Passport: Unified wallet infrastructure for Bitcoin and EVM wallets
MoonPay: Fiat-to-BTC onramp for payment system entry point
Smart Contracts: Trustless collateral management, lending, and payment processing
Liquidity Pool: Enables instant merchant settlements while customers pay over time

How It Works: Payment Infrastructure Flow

BitBNPL provides complete payment rails from BTC to merchants:

Payment Flow 1: Direct MUSD Payment

Customer has MUSD → Select Items → Choose Payment Plan → Pay with MUSD
→ Merchant receives instant settlement → Done

Payment Flow 2: Bitcoin Collateral Payment

Customer has BTC → Checkout detects low MUSD → Navigate to Dashboard
→ Lock BTC as Collateral → Borrow MUSD (90% LTV, 1% APR)
→ Return to Checkout → Pay with MUSD → Merchant receives settlement
→ Customer repays MUSD loan anytime → BTC unlocked

Payment Flow 3: Fiat Onramp to Bitcoin Payment

Customer has Fiat → Dashboard "Buy BTC" → MoonPay Widget Opens
→ Buy BTC with Credit Card/Bank → BTC arrives in Mezo wallet
→ Lock BTC as Collateral → Borrow MUSD → Pay merchant with MUSD
→ Merchant receives instant settlement → Customer repays flexibly

The Infrastructure Result:

Customers: Pay with Bitcoin without selling it - maintain BTC exposure while transacting
Merchants: Receive stable, instant MUSD settlements - no BTC volatility risk
Bitcoin Ecosystem: Bridge BTC holders to e-commerce without forcing them to sell
Payment Network: Complete rails from fiat → BTC → MUSD → merchants → repayment

Why BitBNPL? The Payment Infrastructure Bitcoin Needs

As a Payment Infrastructure:

Bitcoin Payment Network: First infrastructure enabling Bitcoin-backed digital payments at scale
Complete Payment Rails: Fiat → BTC → MUSD → Merchants → Settlement in one system
Instant Finality: Sub-second MUSD settlements vs Bitcoin's 10-minute confirmations
Stability Layer: MUSD eliminates Bitcoin volatility for predictable merchant pricing
Interoperable: Built on Mezo, compatible with EVM ecosystem and Bitcoin wallets
Bitcoin-First: Preserves Bitcoin's value proposition while enabling payments

For Bitcoin Holders (Payment Users):

Keep Your BTC Upside: Pay digitally while Bitcoin continues appreciating
No Tax Events: Borrowing MUSD isn't a taxable event - only loan repayment matters
Full Control: Your BTC is locked as collateral, not sold or exchanged
Repay Anytime: No fixed schedule for loan repayment - pay when convenient
Use Anywhere: Pay any merchant that accepts BitBNPL infrastructure

For New Bitcoin Users:

Easy Onboarding: Buy BTC with credit card in seconds via MoonPay
Guided Experience: Smart checkout guides you through payment flow
Risk Management: Health factor monitoring prevents surprise liquidations
Global Access: Available in 100+ countries through MoonPay integration

For Merchants (Payment Acceptance):

Instant Settlement: Receive full MUSD payment immediately, not over installments
Zero Fraud Risk: Smart contract-guaranteed payments, no chargebacks
No Volatility: Get stable MUSD, not volatile BTC - predictable revenue
Easy Integration: Add payment widget in minutes - Simple Link, JS, or React
New Market: Tap into $1T+ Bitcoin holder market without BTC exposure
Global Reach: Accept payments from Bitcoin users worldwide

Key Features

Payment Infrastructure:

Bitcoin Payment Rails: Complete infrastructure from BTC → MUSD → Merchants
MUSD Stablecoin: Borrow against Bitcoin collateral (up to 90% LTV at 1% APR)
Instant Settlements: Merchants receive MUSD immediately via liquidity pool
Fiat Onramp: MoonPay integration - buy BTC with credit card, bank transfer, Apple Pay
Multi-Wallet Support: Mezo Passport connects Bitcoin wallets (Unisat, Xverse, OKX)
On-Chain Transparency: All payments, settlements, and loans tracked on Mezo blockchain

For Customers (Payment Experience):

Pay with Bitcoin: Use BTC for digital payments without selling it
Complete Journey: Fiat → BTC → Collateral → MUSD → Payments (all in-app)
Dashboard Control: Manage collateral, borrowing, repayment, health in /dashboard
Intelligent Checkout: Auto-detects balance and guides to MUSD acquisition
Flexible Options: Pay in full or split into 1, 4, 6, or 8 installments
Health Monitoring: Real-time collateralization ratio, liquidation warnings

For Merchants (Payment Acceptance):

Easy Integration: Three methods - Simple Link, JavaScript Widget, React SDK
Instant Settlement: Receive full MUSD payment immediately, not over installments
Zero Volatility Risk: Get stable MUSD, not volatile BTC
Transparent Pricing: 0% (1 payment), 5% (4), 8% (6), 10% (8 payments) + 1% platform fee
Verified Network: Admin-verified merchant registry on Mezo blockchain
Real-Time Tracking: Monitor all payments and settlements on-chain

Project Structure

bitbnpl/
├── contracts/          # Foundry smart contracts (Mezo integration core)
├── frontend/           # Next.js web application
├── packages/
│   └── react-sdk/     # React SDK for merchant integration
└── backend/           # Backend services (planned for email services)

Mezo Integration Points

This section documents all locations where Mezo blockchain integration is implemented.

1. Smart Contracts (`/contracts`)

Location: /contracts/src/

The core Mezo integration lives in Solidity smart contracts deployed on Mezo Matsnet.

Contract Files

File	Purpose	Mezo Integration
`MerchantRegistry.sol`	Merchant management	Stores merchant addresses, verification status, transaction stats on Mezo
`InstallmentProcessor.sol`	BNPL payment logic	Handles installment payments, liquidity pool, MUSD token transfers on Mezo
`interfaces/`	Contract interfaces	ERC20 interface for MUSD token

Contract Addresses (Mezo Matsnet)

MerchantRegistry:      0xC80a70e2C2a8d3534043F200C83D772943AF0D91
InstallmentProcessor:  0x78a473F3D3DEC35220E47A45B796CcaB70726439
MUSD Token:            0x118917a40FAF1CD7a13dB0Ef56C86De7973Ac503

Mezo Network Details:

Chain ID: 31611
RPC URL: https://rpc.test.mezo.org
Currency: BTC (for gas fees)

Files:

/contracts/.env - Mezo RPC URL and deployed contract addresses
/contracts/foundry.toml - Foundry config with Mezo RPC settings
/contracts/deploy.sh - Deployment script for Mezo network

2. Frontend Application (`/frontend`)

Location: /frontend/

The Next.js application integrates with Mezo through Mezo Passport, Wagmi/Viem, and wallet connectors.

Environment Configuration

File: /frontend/.env.local

# Mezo Network Configuration
NEXT_PUBLIC_MEZO_RPC_URL=https://rpc.test.mezo.org

# Smart Contract Addresses on Mezo
NEXT_PUBLIC_MERCHANT_REGISTRY_ADDRESS=0xC80a70e2C2a8d3534043F200C83D772943AF0D91
NEXT_PUBLIC_INSTALLMENT_PROCESSOR_ADDRESS=0x78a473F3D3DEC35220E47A45B796CcaB70726439
NEXT_PUBLIC_MUSD_TOKEN_ADDRESS=0x118917a40FAF1CD7a13dB0Ef56C86De7973Ac503

Mezo Passport Integration

File: /frontend/app/providers.tsx

Mezo Passport is the core wallet connection system that provides seamless Bitcoin and Mezo wallet support.

Integration Code:

import { getConfig } from '@mezo-org/passport'

const config = getConfig({
  appName: 'BitBNPL',
  walletConnectProjectId: process.env.NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID,
  mezoNetwork: 'testnet',
})

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <RainbowKitProvider theme={customTheme}>
          <CartProvider>{children}</CartProvider>
        </RainbowKitProvider>
      </QueryClientProvider>
    </WagmiProvider>
  )
}

What Mezo Passport Provides:

Automatic Mezo Configuration:
- Sets up Mezo Matsnet (Chain ID 31611) automatically
- Configures RPC URL: https://rpc.test.mezo.org
- Configures BTC as native currency for gas fees
Bitcoin Wallet Support:
- Unisat Wallet - Native Bitcoin wallet
- Xverse Wallet - Bitcoin & Stacks wallet
- OKX Wallet - Multi-chain including Bitcoin
Mezo-Native Wallets:
- OrangeKit - Mezo's official wallet connector
- Leather Wallet - Bitcoin-focused wallet with Mezo support
Standard Web3 Wallets:
- MetaMask - Via WalletConnect
- WalletConnect - Any WalletConnect-compatible wallet
- Coinbase Wallet - Standard EVM wallet support
Developer Benefits:
- No manual chain configuration needed
- BTC-based gas fee estimation handled automatically
- Unified connection experience across all wallet types
- Production-ready (switch to mainnet with mezoNetwork: 'mainnet')
- Type-safe with TypeScript
- Handles Mezo-specific signing quirks (BTC signatures, PSBT)

Dependencies:

{
  "@mezo-org/passport": "^1.x.x",
  "@mezo-org/orangekit": "^1.x.x",
  "@rainbow-me/rainbowkit": "^2.x.x",
  "wagmi": "^2.x.x",
  "viem": "^2.x.x"
}

Why Mezo Passport?

Abstracts away Mezo-specific complexities
Single config for multiple wallet types
Maintained by Mezo team for compatibility
Handles network upgrades automatically

Contract Interaction Hooks

All hooks include fallback addresses for Mezo contracts:

Hook File	Contract	Purpose
`/frontend/hooks/useMerchantRegistry.ts`	MerchantRegistry	Merchant registration, verification checks on Mezo
`/frontend/hooks/useInstallmentProcessor.ts`	InstallmentProcessor	Payment initiation, installment tracking on Mezo
`/frontend/hooks/useAdminData.ts`	Both contracts	Admin dashboard data from Mezo chain

Example (useMerchantRegistry.ts):

const MERCHANT_REGISTRY_ADDRESS =
  process.env.NEXT_PUBLIC_MERCHANT_REGISTRY_ADDRESS ||
  '0xC80a70e2C2a8d3534043F200C83D772943AF0D91'

// Uses Wagmi to read from Mezo blockchain
const { data: isMerchant } = useReadContract({
  address: MERCHANT_REGISTRY_ADDRESS,
  abi: merchantRegistryAbi,
  functionName: 'isMerchant',
  args: [address],
})

Pages with Mezo Integration

Page	File	Mezo Integration
Dashboard	`/frontend/app/dashboard/page.tsx`	Core customer flow: BTC collateral management, MUSD borrowing against BTC, loan repayment, health factor monitoring
Admin Dashboard	`/frontend/app/admin/page.tsx`	Reads merchant/payment data from Mezo contracts, manages liquidity pool
Merchant Registration	`/frontend/app/merchant/register/page.tsx`	Registers merchant address on Mezo blockchain
Merchant Dashboard	`/frontend/app/merchant/dashboard/page.tsx`	Displays transaction history from Mezo, integration code
Checkout	`/frontend/app/checkout/page.tsx`	Checks MUSD balance, initiates payments, redirects to dashboard if insufficient funds
Marketplace	`/frontend/app/marketplace/page.tsx`	Lists verified merchants from Mezo MerchantRegistry

Customer Dashboard (/dashboard) - The MUSD Acquisition Hub:

This is where the magic happens. When customers don't have MUSD to shop:

Add BTC Collateral (AddCollateralModal):
- Locks Bitcoin in Mezo contract as collateral
- Enables borrowing capacity calculation based on BTC price oracle
Borrow MUSD (BorrowMUSDModal):
- Borrows MUSD against locked BTC (up to ~90% LTV)
- 1% APR interest rate
- No need to sell Bitcoin
- Maintains BTC price exposure
Repay MUSD (RepayMUSDModal):
- Repay borrowed MUSD at any time
- Improves health factor
- Can withdraw BTC after full repayment
Buy BTC (BuyBTCButton - MoonPay integration):
- If user has no BTC, opens MoonPay widget
- Purchase BTC with fiat (credit card, bank transfer)
- BTC sent directly to Mezo wallet
Monitor Health:
- Real-time collateralization ratio
- Liquidation price warnings
- Health factor tracking

Components with Mezo Integration

Component	File	Mezo Integration
Navbar	`/frontend/components/Navbar.tsx`	OrangeKit wallet connection for Mezo
MerchantTransactions	`/frontend/components/merchant/MerchantTransactions.tsx`	Fetches transaction events from Mezo blockchain
BuyBTCButton	`/frontend/components/onramp/BuyBTCButton.tsx`	MoonPay widget integration for BTC purchases
AddCollateralModal	`/frontend/components/modals/AddCollateralModal.tsx`	Locks BTC as collateral on Mezo
BorrowMUSDModal	`/frontend/components/modals/BorrowMUSDModal.tsx`	Borrows MUSD from Mezo lending protocol
RepayMUSDModal	`/frontend/components/modals/RepayMUSDModal.tsx`	Repays MUSD debt on Mezo
CollateralHealthMeter	`/frontend/components/dashboard/CollateralHealthMeter.tsx`	Displays health factor from Mezo contracts
ActiveInstallments	`/frontend/components/dashboard/ActiveInstallments.tsx`	Shows active BNPL payments from Mezo
TransactionHistory	`/frontend/components/dashboard/TransactionHistory.tsx`	Historical transactions from Mezo blockchain

3. JavaScript Widget (`/frontend/public/widget.js`)

Location: /frontend/public/widget.js

Standalone JavaScript widget for merchant websites to integrate Mezo payments.

Mezo Configuration:

const BITBNPL_BASE_URL = 'https://bitbnpl.vercel.app';
const MERCHANT_REGISTRY_ADDRESS = '0xC80a70e2C2a8d3534043F200C83D772943AF0D91';
const RPC_URL = 'https://rpc.test.mezo.org';

Usage:

<script src="https://bitbnpl.vercel.app/widget.js"></script>
<button
  data-bitbnpl-merchant="0x742d35Cc..."
  data-bitbnpl-amount="1000"
  data-bitbnpl-order-id="ORDER123">
  Pay with BitBNPL
</button>

Clicking the button navigates to the checkout page that connects to Mezo and initiates payment.

4. React SDK (`/packages/react-sdk`)

Location: /packages/react-sdk/src/

NPM package for React applications to integrate Mezo BNPL payments.

Published: @bitbnpl/react-sdk on NPM

Mezo Integration:

// src/BitBNPLButton.tsx
// Configures Wagmi with Mezo Matsnet
const config = createConfig({
  chains: [mezoMatsnet],  // Chain ID 31611
  transports: {
    [mezoMatsnet.id]: http('https://rpc.test.mezo.org'),
  },
})

Usage:

import { BitBNPLButton } from '@bitbnpl/react-sdk';

<BitBNPLButton
  merchantAddress="0x742d35Cc..."
  amount="1000"
  orderId="ORDER123"
/>

The button handles Mezo wallet connection and payment initiation.

5. MoonPay Integration (`/frontend/components/onramp`)

Location: /frontend/components/onramp/BuyBTCButton.tsx

MoonPay enables users to purchase Bitcoin with fiat currency, solving the cold start problem for users without BTC.

Integration Code:

import { useMoonPay } from '@/hooks/useMoonPay'

export function BuyBTCButton() {
  const { openBuyWidget, isConnected } = useMoonPay()

  const handleClick = () => {
    openBuyWidget({
      baseCurrencyCode: 'usd',
      onSuccess: (transactionId) => {
        // BTC sent to user's Mezo wallet
        window.location.reload()
      }
    })
  }

  return <button onClick={handleClick}>Buy BTC</button>
}

How It Works:

User clicks "Buy BTC" button in /dashboard
MoonPay widget opens (embedded in app or popup)
User selects payment method (credit card, bank transfer, Apple Pay, etc.)
MoonPay processes fiat payment and purchases BTC
BTC is sent directly to user's connected Mezo wallet address
User can immediately use BTC as collateral to borrow MUSD

Benefits:

No need to leave the app
Direct BTC delivery to Mezo wallet
Supports 100+ countries
Multiple payment methods
KYC handled by MoonPay

Configuration:

NEXT_PUBLIC_MOONPAY_API_KEY=your_api_key_here
NEXT_PUBLIC_MOONPAY_SECRET_KEY=your_secret_key_here

File: /frontend/hooks/useMoonPay.ts - Custom hook for MoonPay SDK integration

6. Contract ABIs

Location: /frontend/lib/abi/

Contains ABI definitions for interacting with Mezo smart contracts:

merchantRegistryAbi.ts - MerchantRegistry contract interface
installmentProcessorAbi.ts - InstallmentProcessor contract interface
erc20Abi.ts - MUSD token interface

These ABIs are used by Wagmi hooks to type-safely interact with Mezo contracts.

7. Documentation

Location: /frontend/app/docs/

Comprehensive merchant documentation about Mezo integration:

Page	Content
`/docs/page.tsx`	Overview, displays Mezo network details and contract addresses
`/docs/getting-started/page.tsx`	Step-by-step guide including Mezo wallet setup
`/docs/integration/page.tsx`	Integration methods with Mezo connection examples
`/docs/api/page.tsx`	Complete smart contract API reference for Mezo
`/docs/testing/page.tsx`	Mezo testnet testing guide (getting mats, testnet BTC)

Getting Started

Prerequisites

Node.js 18+ and npm
Foundry (for smart contracts)
Mezo-compatible wallet (OKX Wallet, OrangeKit)
Testnet BTC (for gas fees on Mezo)

Installation

Clone the repository:

git clone https://github.com/jerrymusaga/bitbnpl.git
cd bitbnpl

Install dependencies:

# Frontend
cd frontend
npm install

# Contracts
cd ../contracts
forge install

# React SDK
cd ../packages/react-sdk
npm install

Configure environment variables:

# Frontend (.env.local)
NEXT_PUBLIC_MEZO_RPC_URL=https://rpc.test.mezo.org
NEXT_PUBLIC_MERCHANT_REGISTRY_ADDRESS=0xC80a70e2C2a8d3534043F200C83D772943AF0D91
NEXT_PUBLIC_INSTALLMENT_PROCESSOR_ADDRESS=0x78a473F3D3DEC35220E47A45B796CcaB70726439
NEXT_PUBLIC_MUSD_TOKEN_ADDRESS=0x118917a40FAF1CD7a13dB0Ef56C86De7973Ac503

# Contracts (.env)
RPC_URL=https://rpc.test.mezo.org
PRIVATE_KEY=your_private_key_here
MERCHANT_REGISTRY_ADDRESS=0xC80a70e2C2a8d3534043F200C83D772943AF0D91
INSTALLMENT_PROCESSOR_ADDRESS=0x78a473F3D3DEC35220E47A45B796CcaB70726439

Running Locally

Frontend:

cd frontend
npm run dev
# Visit http://localhost:3000

Compile Contracts:

cd contracts
forge build

Deploy Contracts to Mezo:

cd contracts
./deploy.sh

Architecture

Payment Flow on Mezo

1. Merchant Registration

Merchant wallet address registers on Mezo via MerchantRegistry.registerMerchant()
Admin verifies merchant: MerchantRegistry.verifyMerchant(address)

2. Customer Checkout & MUSD Acquisition Flow

When a customer clicks "Pay with BitBNPL", they are directed to /checkout which intelligently handles three scenarios:

Scenario A: Customer has sufficient MUSD balance

Customer selects installment plan (1, 4, 6, or 8 payments)
Initiates payment: InstallmentProcessor.initiatePayment(merchantAddress, totalAmount, installments)
Customer approves MUSD token spending on Mezo
First installment + interest paid immediately

Scenario B: Customer has BTC but no MUSD

Checkout detects insufficient MUSD balance
Customer is prompted: "Go to Dashboard to Add Funds"
User navigates to /dashboard where they can:
1. Add BTC as Collateral: Lock Bitcoin in Mezo smart contract
2. Borrow MUSD: Borrow MUSD against BTC collateral (up to ~90% LTV at 1% APR)
3. Shop with MUSD: Use borrowed MUSD for purchases while keeping BTC upside
After borrowing MUSD, customer returns to checkout to complete purchase

Scenario C: Customer has no BTC

Dashboard shows "Buy BTC" button (MoonPay integration)
Customer clicks "Buy BTC" → MoonPay widget opens
Customer purchases Bitcoin with fiat (credit card, bank transfer, etc.)
BTC is sent directly to customer's Mezo wallet
Customer then follows Scenario B flow (add collateral → borrow MUSD → shop)

Key Insight: Customers never need to sell their Bitcoin to shop. They borrow MUSD against BTC, make purchases, and can repay the MUSD loan anytime to unlock their Bitcoin.

3. Instant Merchant Settlement

Full payment amount transferred from liquidity pool to merchant on Mezo
Platform fee (1%) deducted and sent to admin
Merchant receives funds immediately, regardless of customer's installment plan

4. Installment Payments & Loan Management

Customer pays remaining installments on schedule
InstallmentProcessor.payInstallment(paymentId) called per payment
Late payments tracked on-chain
Customer can repay MUSD loan anytime via /dashboard
Upon full MUSD repayment, customer can withdraw BTC collateral

Technology Stack

Blockchain:

Mezo Matsnet (Chain ID: 31611)
Solidity smart contracts (Foundry)
MUSD stablecoin (ERC20)
BTC for gas fees

Frontend:

Next.js 14 (App Router)
TypeScript
Mezo Passport (@mezo-org/passport) - Core Mezo wallet integration
OrangeKit (@mezo-org/orangekit) - Mezo-native wallet connector
Wagmi/Viem - Ethereum-compatible RPC interaction on Mezo
RainbowKit - Wallet UI components
MoonPay SDK - Fiat onramp for BTC purchases
TailwindCSS - Styling

Integration Methods:

JavaScript Widget (vanilla JS)
React SDK (NPM package)
Simple Payment Link (URL-based)

Key Differentiator:

BTC Collateral Lending: Customers borrow MUSD against Bitcoin without selling
MoonPay Onramp: Seamless fiat-to-BTC conversion for new users
Mezo-Native: Built specifically for Mezo blockchain with Bitcoin-first approach

Smart Contract Reference

MerchantRegistry

Deployed: 0xC80a70e2C2a8d3534043F200C83D772943AF0D91 (Mezo Matsnet)

Key Functions:

registerMerchant(string email) - Register as merchant
verifyMerchant(address merchant) - Admin verifies merchant
isMerchant(address) - Check if address is registered
isVerified(address) - Check verification status
getMerchantStats(address) - Get transaction stats

InstallmentProcessor

Deployed: 0x78a473F3D3DEC35220E47A45B796CcaB70726439 (Mezo Matsnet)

Key Functions:

initiatePayment(address merchant, uint256 amount, uint8 installments) - Start payment
payInstallment(uint256 paymentId) - Pay installment
getPaymentDetails(uint256 paymentId) - Get payment info
addLiquidity(uint256 amount) - Admin adds liquidity
removeLiquidity(uint256 amount) - Admin removes liquidity

Interest Rates:

1 payment: 0%
4 payments: 5%
6 payments: 8%
8 payments: 10%

Testing on Mezo

Get Testnet Funds

Get Testnet BTC (for gas fees):
- Join Mezo Discord
- Earn "mats" tokens through activities
- Convert mats to testnet BTC via Mezo Portal
Get MUSD (for payments):
- Contact admin to mint test MUSD to your address

Test Scenarios

Register as merchant
Get merchant verified by admin
Create test payment (customer perspective)
Pay installments on schedule
Check transaction history

Deployment

Smart Contracts

Contracts are deployed on Mezo Matsnet:

cd contracts
./deploy.sh

Deployment broadcasts are saved in /contracts/broadcast/.

Frontend

Deployed on Vercel: https://bitbnpl.vercel.app

Environment Variables (set in Vercel):

NEXT_PUBLIC_MEZO_RPC_URL
NEXT_PUBLIC_MERCHANT_REGISTRY_ADDRESS
NEXT_PUBLIC_INSTALLMENT_PROCESSOR_ADDRESS
NEXT_PUBLIC_MUSD_TOKEN_ADDRESS

React SDK

Published on NPM as @bitbnpl/react-sdk:

cd packages/react-sdk
npm publish

Security

Smart contracts use OpenZeppelin libraries (Ownable, ReentrancyGuard)
Admin-only functions protected with onlyOwner modifier
Reentrancy protection on payment functions

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Resources

Live App: https://bitbnpl.vercel.app
Documentation: https://bitbnpl.vercel.app/docs
Mezo Docs: https://docs.mezo.org
React SDK: @bitbnpl/react-sdk

License

MIT License - see LICENSE file for details

Support

For questions or support:

Open an issue on GitHub
Check the documentation
Contact: support@bitbnpl.com

Built with Bitcoin. Powered by Mezo.

Name		Name	Last commit message	Last commit date
Latest commit History 30 Commits
contracts		contracts
frontend		frontend
node_modules		node_modules
packages/react-sdk		packages/react-sdk
.gitmodules		.gitmodules
MERCHANT_EMAIL_HANDLING.md		MERCHANT_EMAIL_HANDLING.md
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

BitBNPL - Bitcoin Payment Infrastructure & BNPL Platform

Overview

The Problem We Solve

The BitBNPL Solution: A Complete Payment Infrastructure

How It Works: Payment Infrastructure Flow

Why BitBNPL? The Payment Infrastructure Bitcoin Needs

Key Features

Project Structure

Mezo Integration Points

1. Smart Contracts (/contracts)

Contract Files

Contract Addresses (Mezo Matsnet)

2. Frontend Application (/frontend)

Environment Configuration

Mezo Passport Integration

Contract Interaction Hooks

Pages with Mezo Integration

Components with Mezo Integration

3. JavaScript Widget (/frontend/public/widget.js)

4. React SDK (/packages/react-sdk)

5. MoonPay Integration (/frontend/components/onramp)

6. Contract ABIs

7. Documentation

Getting Started

Prerequisites

Installation

Running Locally

Architecture

Payment Flow on Mezo

1. Merchant Registration

2. Customer Checkout & MUSD Acquisition Flow

3. Instant Merchant Settlement

4. Installment Payments & Loan Management

Technology Stack

Smart Contract Reference

MerchantRegistry

InstallmentProcessor

Testing on Mezo

Get Testnet Funds

Test Scenarios

Deployment

Smart Contracts

Frontend

React SDK

Security

Contributing

Resources

License

Support

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

1. Smart Contracts (`/contracts`)

2. Frontend Application (`/frontend`)

3. JavaScript Widget (`/frontend/public/widget.js`)

4. React SDK (`/packages/react-sdk`)

5. MoonPay Integration (`/frontend/components/onramp`)

Packages