PayBoy

Payboy — Stripe-simple onboarding for PYUSD

Payboy makes it dead-simple for Web2-native teams to accept PayPal USD (PYUSD) across three use cases:

Solo sellers (one merchant, one balance),

Shops (single brand with multiple staff/users), and

Multi-merchant marketplaces (many sellers under one platform).

Think “Stripe-like developer experience,” but for PYUSD and on-chain escrow—so startups can ship payments fast without becoming blockchain experts.

What it is (plain English)

Payboy is an integration layer + smart-contract escrow that lets you add PYUSD checkout in minutes. You get a lightweight SDK, REST APIs, and webhooks that feel familiar to any Web2 developer, while Payboy handles the crypto plumbing: wallets, chain selection, on-chain escrow, fee routing, and payouts to sellers.

Who it’s for

Solo creators & sellers who want a simple “Pay with PYUSD” button and auto-settlement.

Online stores (Next.js, Shopify custom app, etc.) that want drop-in checkout and staff roles.

Marketplaces & platforms that need multi-merchant onboarding, per-merchant balances, split fees, and escrow-style buyer protection.

Why it matters

Web2-simple DX: Add a button, call 2–3 endpoints, receive webhooks—done.

Buyer trust: Funds sit in on-chain escrow until delivery/confirmation.

Platform ready: Multi-merchant accounts, fee splits, and payout policies from day one.

Scales later: Start with PYUSD; keep the same integration as you add more chains/tokens.

Core features

Drop-in Checkout: Prebuilt UI component (<PayboyCheckout />) or a minimal REST flow (/payments/create, /payments/confirm, /webhooks).

Smart-contract escrow: Per-order escrows hold PYUSD until release conditions are met (delivery confirmation, dispute window, or admin override).

Multi-merchant architecture: A Marketplace Factory deploys a marketplace’s contract once; merchant vaults are created lazily on onboarding; each order opens its own escrow instance.

Fee routing: Configurable platform fee + merchant payout handled on-chain.

Wallets: Use embedded (custodial) seller wallets for zero-friction onboarding, or connect external wallets when ready.

Webhooks: Real-time events (payment.created, payment.confirmed, escrow.released, payout.sent, payout.failed) to sync your database and UI.

Environment presets: Test on Arbitrum Sepolia with a single toggle; mainnet configuration is a variable swap away.

Compliance-friendly surface: PYUSD (a regulated stablecoin) + clear audit trail via on-chain events and signed webhooks.

How it works (flows)

1. Solo Seller

Seller signs in → Payboy creates an embedded wallet and a merchant vault.

Your app calls POST /payments/create (amount, currency=PYUSD, metadata).

Buyer pays → funds land in order escrow.

You confirm delivery (POST /orders/:id/deliver) → escrow releases to the seller vault.

Seller taps Payout → on-chain transfer to their wallet (or off-ramp later).

1. Shop (single brand, multiple users)

Same as Solo, plus roles (owner/admin/staff), store-level reports, and restricted API keys for staff apps. All orders still settle to the shop’s merchant vault.

1. Marketplace (multi-merchant)

Platform registers → Marketplace contract deployed by Factory.

Each seller onboards → merchant vault created under the marketplace.

Checkout can do split fees: escrow later releases platform_fee to platform + net_amount to merchant.

Disputes & delivery windows are enforced via marketplace policy (time-locks + admin resolution hooks).

Developer experience

SDK: @payboy/sdk for Next.js/React (hook + component) or vanilla JS.

REST + Webhooks: Familiar Web2 patterns; sign all webhooks, verify with shared secret.

Helpers: chain.ts and token.ts simplify chain IDs, token addresses, decimals, and formatting.

Minimal setup: PAYBOY_API_KEY, WEBHOOK_SECRET, CHAIN_ID. Optional: EMBEDDED_WALLET_PROVIDER.

Types: Strong TypeScript types for Payment, Order, Merchant, and webhook payloads.

Smart-contract design (clear & opinionated)

Factory pattern: Deploys a Marketplace contract for each platform.

Merchant vaults: Lightweight per-merchant proxies under a marketplace.

Order escrows: One escrow per order; holds PYUSD; immutable references to buyer, seller, amounts, and policy.

Release conditions:

Buyer confirms delivery, or

Delivery window expires without dispute, or

Admin resolves a dispute (marketplace authority).

Events: EscrowOpened, EscrowReleased, EscrowRefunded, PayoutSent, PayoutFailed for full transparency.

Security & reliability (MVP stance)

Signed webhooks + idempotency keys on all write endpoints.

Replay & race protection in escrow release and payouts.

Typed validation on server (amounts, addresses, chain IDs).

Audit-friendly logs (link off-chain order IDs ↔ on-chain tx hashes).

Roadmap

Additional currencies (USDC/USDT) with the same integration surface.

Off-ramp partners for sellers that want fiat.

Hosted onboarding for marketplaces (no-code merchant invite flow).

Dispute center UI with time-boxed actions and evidence uploads.

Accounting exports (CSV/QuickBooks/Xero).

Optional KYC modules for marketplaces with higher regulatory needs.

🛠️ How It’s Made

Payboy was built to feel Stripe-simple on the surface, but it’s powered by a deeply modular and crypto-native backend. Here's how it all works under the hood:

🔗 Core Tech Stack

Smart Contracts: Written in Solidity using the Factory pattern, deployed via HardHat. Each marketplace gets its own on-chain instance, which spawns per-merchant vaults and order-level escrows on demand.

Blockchain: Currently deployed on Arbitrum Sepolia for testing, with planned support for Arbitrum mainnet and future expansion to other chains (Polygon, Base, Optimism). All chain logic is abstracted behind config helpers so we can scale to multi-chain and multi-token environments with minimal changes.

Token Support: PYUSD is our primary asset, but we're building in compatibility with KYUSD and USDC/USDT to enable flexible settlement options.

Wallets: We use Privy to provide embedded wallets for sellers and buyers. This enables frictionless onboarding—no MetaMask or seed phrase needed.

ENS: We assign readable ENS subdomains (e.g. tx-abc123.payboy.eth) to every receipt and escrow instance for human-friendly transaction tracing.

Off-chain SDK & APIs: Our backend is built using Next.js and TypeScript with RESTful routes and signed webhook support. The frontend SDK is lightweight and designed for Web2 devs who just want to createPayment() and get moving.

🧪 Testing & Deployment

HardHat scripts deploy contracts and verify them automatically on chain.

Our test suite includes mock marketplace, multi-seller, and dispute flows, simulating the full order lifecycle from createPayment to escrowRelease.

💳 Web2 Payment Flow, Crypto Backing

Our core value prop is Venmo/PayPal-native UX, backed by on-chain escrow. Buyers can fund payments via PayPal → PYUSD (or KYUSD), which are then routed into our smart contract escrow layer.

Because we're using regulated stablecoins like PYUSD and KYUSD, our flows stay compliance-friendly while still offering on-chain transparency and trust.

🧠 Hacky (but clever) bits

ENS receipts: We use the eth-registrar system with a payboy.eth subdomain manager to auto-register human-readable receipts (e.g. tx-93af13.payboy.eth) using hashed order IDs.

Embedded vaults: We lazy-initialize seller vaults only when they first receive funds—saves gas and simplifies dev UX.

Auto-escrow logic: Funds are auto-held in escrow unless delivery is confirmed, a dispute is opened, or a timeout expires. This means platforms can offer "Pay on Delivery"-style trust by default.

Onchain fees + offchain logs: Our smart contracts emit granular events like EscrowCreated, EscrowReleased, PayoutSent, and DisputeOpened—these are mirrored via webhook logs for off-chain traceability.

Chain abstraction: We use chain.ts and token.ts to map chain IDs, RPCs, native tokens, and decimals into a single config-driven interface—so the frontend and backend don't care whether you're on Arbitrum, Polygon, or Base.

🧩 Partner Tech Benefits

Privy: Enabled us to ship fast with embedded wallets for both buyers and sellers. This cut onboarding time by 90%—no wallet setup friction.

ENS: Gave us readable and trustable URLs for receipts and escrows. It’s not just cool—it’s helpful when debugging and builds trust with non-crypto users.

PYUSD and USDC: Our choice of stablecoins makes it easy for real-world buyers to fund purchases using Venmo, PayPal, or onramps like MoonPay—no volatile tokens needed.

Arbitrum: Gave us fast finality and low fees. Their dev tooling, explorer, and contract deployment UX is excellent—perfect for hackathon speed and beyond.

🧪 Summary

Payboy was designed to be Web2-simple but crypto-powerful. Every technical decision—from contract factories to webhooks, Privy wallets, ENS receipts, and escrow state machines—was chosen to make stablecoin checkout as easy to add as Stripe. But under the hood, it’s decentralized, programmable, and built to scale.

We believe payments should be programmable, trust-minimized, and easy to integrate—and Payboy is our take on that future.