Web3 + Stripe Demo

A turnkey Web3 + Stripe integration demo showcasing NFT minting, auctions, and hybrid payment systems using the latest stable tooling (May 2025).

Tech Stack

• Smart Contracts: Solidity 0.8.25, ERC721AUpgradeable, OpenZeppelin Contracts 5.3.x
• Web3 Integration: thirdweb SDK 5, viem 2.30.x, wagmi 2.15.x
• Wallet Connection: WalletConnect v2 with Web3Modal v3
• Frontend: Next.js 15.2 (React 19) with App Router and Server Actions
• Payments: Stripe API (2025-04-30)
• Development: Hardhat 3 (TypeScript), Bun package manager
• Network: Sepolia testnet with deterministic deployments

Features

• ERC721A NFT contract with royalties and payment splitter
• Lazy minting functionality
• Fixed price sales with direct ETH payments
• English auction system (reserve price, bidding, settlement)
• Stripe integration for credit card payments
• Gasless transactions via Biconomy paymaster (optional)
• On-chain/off-chain payment reconciliation

Quick Start

Prerequisites

• Node.js 22+
• Bun package manager
• Sepolia testnet ETH (for testing)
• Sepolia RPC endpoint (Infura, Alchemy, etc.)
• Metamask or any WalletConnect compatible wallet

Setup

1. Clone the repository

git clone https://github.com/yourusername/web3-stripe-demo.git
cd web3-stripe-demo

2. Install dependencies

bun install
cd web && bun install
cd ..

3. Configure environment variables

cp .env.local.example .env.local
# Edit .env.local with your credentials

4. Compile smart contracts

bun run compile

5. Deploy contracts to Sepolia

bun run deploy:sepolia

6. Start the development server

bun run dev

7. Access the application

Open your browser and navigate to http://localhost:3000

Environment Variables

This project requires several environment variables to be set. Copy .env.local.example to .env.local and configure the following:

Blockchain Configuration

• PRIVATE_KEY: Your Ethereum private key for contract deployment
• SEPOLIA_RPC_URL: RPC URL for Sepolia testnet
• ETHERSCAN_API_KEY: API key for contract verification

Contract Configuration

• CONTRACT_ADDRESS: Deployed NFT contract address
• DEPLOYMENT_SALT: Salt for deterministic deployments

Payment Splitter Configuration

• ROYALTY_RECEIVER: Address to receive royalties
• PRIMARY_PAYEE: First payment split recipient
• SECONDARY_PAYEE: Second payment split recipient

Stripe Configuration

• STRIPE_SECRET_KEY: Your Stripe secret key
• STRIPE_WEBHOOK_SECRET: Secret for Stripe webhook verification

Frontend Configuration

• NEXT_PUBLIC_APP_URL: URL of your frontend app
• NEXT_PUBLIC_CONTRACT_ADDRESS: Public exposure of contract address
• NEXT_PUBLIC_SEPOLIA_RPC_URL: Public RPC URL for frontend
• NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID: WalletConnect project ID

Biconomy Paymaster (Optional)

• NEXT_PUBLIC_ENABLE_PAYMASTER: Set to "true" to enable gasless transactions
• NEXT_PUBLIC_BICONOMY_API_KEY: Biconomy API key
• NEXT_PUBLIC_PAYMASTER_PRIVATE_KEY: Private key for paymaster operations

Data Flow Architecture

┌───────────┐     ┌───────────────┐     ┌────────────┐
│           │     │               │     │            │
│  Frontend │────▶│ Stripe / Web3 │────▶│  Contract  │
│           │     │               │     │            │
└───────────┘     └───────────────┘     └────────────┘
       │                   ▲                   ▲
       │                   │                   │
       ▼                   │                   │
┌───────────┐     ┌───────────────┐     ┌────────────┐
│           │     │               │     │            │
│  Backend  │────▶│    Webhook    │────▶│ SaleRecord │
│           │     │               │     │   Events   │
└───────────┘     └───────────────┘     └────────────┘

Payment Flow

1. Web3 Native Path:

   • User connects wallet and pays with ETH
   • Contract mints NFT directly to user's wallet
   • Transaction is recorded on-chain

2. Stripe Payment Path:

   • User initiates purchase and is redirected to Stripe Checkout
   • User completes payment with credit card
   • Stripe sends webhook notification to backend
   • Backend server calls contract to mint NFT with user's address
   • Contract emits SaleRecorded event with paymentIntentId
   • Reconciliation script matches on-chain events with Stripe payments

Testnet Resources

• Sepolia Faucet: https://sepoliafaucet.com/
• Sepolia Block Explorer: https://sepolia.etherscan.io
• Sepolia RPC Endpoints:
  • Infura: https://sepolia.infura.io/v3/YOUR_API_KEY
  • Alchemy: https://eth-sepolia.g.alchemy.com/v2/YOUR_API_KEY

Development

Contract Development

# Run tests
bun run test

# Generate gas reports
REPORT_GAS=true bun run test

# Deploy contracts
bun run deploy:sepolia

Frontend Development

# Start Next.js development server
bun run dev

# Build for production
bun run build

# Run linting
bun run lint

Reconciliation

# Run reconciliation between on-chain events and Stripe payments
bun run reconcile

License

MIT