Merchant-Pull Micropayments for Zero-Connectivity Consumers on Stellar/Soroban
PeraPin enables consumers in informal micro-economies (sari-sari stores, school canteens, PUVs) to pay for goods using a static QR code sticker — even when their smartphone is dead, offline, or left at home.
| Item | Details / Link |
|---|---|
| Live Production MVP | https://perapin.vercel.app |
| GitHub Repository | https://github.com/lncekent/perapin |
| Soroban Contract ID | CBEASRMFLJOTK6PVM6276THY26GVNYUXKDWF3JVPKGYEC63MUSQV5P3D |
| Stellar Expert Explorer | View Contract on Explorer |
| Demo Video | Video Link |
| Consumer Dashboard | Merchant QR Scan | PIN Handoff Pad |
|---|---|---|
 |
 |
 |
| Mobile Navigation | Merchant Payment Confirmation |
|---|---|
 |
 |
| Vercel Analytics Dashboard | Inspector Console |
|---|---|
 |
 |
| Contract ID Page |
|---|
 |
Once users test PeraPin, their on-chain testnet settlements are logged on the Stellar Explorer:
| # | Role | Stellar Public Key | On-Chain Tx Hash |
|---|---|---|---|
| 1 | Consumer | GBSLOBZ5AOSCF75M76W7NUZREMSJN3INYVORMP3OMA7DFJLMH3C6JM4I |
885df6cf…8298c · account |
| 2 | Consumer | GC5LOROOR2E4NK6NUS2XZWXOIONBJHEXPISOYBE4DJZBAYKJZFIVTAZ5 |
32e68483…3198 · account |
| 3 | Consumer | GD3CWJXAG4A2BXJHWIKENQXST2BU3VBLLAFQMRM6QJEKRZY7Q2OFIHV7 |
3cff9448…5ade · account |
| 4 | Consumer | GC5DZMKDYN6PCRLN3EKOSUZCVAXNV4Q6BGO4W6MJ4JFTOAXUKMN57IJ2 |
9b78cfa4…5b51 · account |
| 5 | Consumer | GD2BEHIYC2DXQNFE73KZOVHX4F6TJ7FPAH6F7XOBXZXYQOJIKV7GCPAT |
28488972…94cd · account |
| 6 | Consumer | GAQXBIPCNZLTEI5Z4UF4FJPQ3LRPNEYHJ4A2JBOIJN35HLBPMTEMBCGN |
0f8bcb51…1ace · account |
| 7 | Consumer | GDO7DPZSNGCOXZLJCJCKLCVSVATADECRE4SU5SDFT2I7S7NXKU2OTEZD |
2edf15be…bb8e · account |
| 8 | Consumer | GALJDMTUAND72HT4AUXZ65ZUCUR4ADOBPICMQFM4DQHXDRAWRWKHNHR7 |
36af43ee…1338 · account |
| 9 | Consumer | GCZ6EIBXFR37624DJYRGTEGV6LS6BE6R3RXIYYP374EAUN5BNYCPQ4EO |
438b1f1c…c949 · account |
| 10 | Merchant | GCDNFZW6XJM2SCUZUAQ74F5OPB7RGPMQ7DN3EA3YR2QDNTMFHQYR66SQ |
1d4b0260…1933 · account |
Feedback collected securely via /feedback into Supabase:
| User | Role | Rating | Comment / Feedback |
|---|---|---|---|
| Student 1 | Consumer | ⭐⭐⭐⭐⭐ | "Nice, smooth sending money. The potential is great!" |
| Student 2 | Consumer | ⭐⭐⭐⭐⭐ | "the concept is really nice, the transactions were smooth with no delays. though the UI is minimal and lacks some minor contents, the core functions are met and working." |
| Merchant 1 | Merchant | ⭐⭐⭐☆☆ | "Must reload fast, but overall good" |
| Student 3 | Consumer | ⭐⭐⭐⭐⭐ | "Excellent!! Fast reload." |
Digital payment systems assume consumers have working smartphones, active data, and battery. PeraPin flips this paradigm:
┌─────────────────┐ Scans QR Sticker ┌──────────────────┐
│ Consumer QR │ ──────────────────────────> │ Merchant Phone │
│ (Zero Power/Data)│ │ (Active Device) │
└─────────────────┘ └─────────┬────────┘
│ │
│ Hands phone to consumer for 4-digit PIN │
└────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────┐
│ SHA-256 (PIN + Public Key) in Browser │
└──────────────────┬───────────────────┘
│
▼
┌──────────────────────────────────────┐
│ Soroban Contract `pay()` on Testnet │
└──────────────────────────────────────┘
- Merchant scans consumer sticker using their phone camera (or manual public key).
- Merchant inputs transaction amount in XLM.
- Merchant hands phone to consumer to enter a 4-digit PIN on a secure dark overlay.
- Browser computes SHA-256 hash client-side:
SHA-256(PIN + Public_Key). - API submits transaction to Soroban smart contract, moving XLM on Stellar Testnet upon verification.
- Client-Side Hashing: Raw 4-digit PINs never leave the browser. Hashing uses native
window.crypto.subtle.digest("SHA-256")with the user's public key as salt. - On-Chain Brute Force Lockout: 3 consecutive failed PIN entries trigger an automated 15-minute on-chain lockout enforced by the Soroban smart contract.
- Custodial Key Encryption: Merchant & Consumer private keys are encrypted using AES-256-GCM before database storage in Supabase. Keys are decrypted in-memory only during payload construction and scrubbed immediately in a
finallyblock.
| Layer | Technology |
|---|---|
| Frontend | Next.js 14 (App Router, React 19, TypeScript) |
| Styling | Tailwind CSS v4, Lucide Icons, Framer Motion |
| Smart Contract | Rust, Soroban SDK v27 |
| Blockchain SDK | @stellar/stellar-sdk |
| Authentication | Supabase Auth (Email OTP, Gmail SMTP, @supabase/ssr) |
| Database | Supabase PostgreSQL |
| QR Scanner / Generator | @zxing/browser, qrcode |
| Hosting & Analytics | Vercel, @vercel/analytics |
- Node.js: v20.x or later
- Rust & Stellar CLI: Rust 2021 toolchain (
stellar-cli/soroban-cli) - WASM Target:
rustup target add wasm32v1-none
Copy .env.example to .env.local and populate:
NEXT_PUBLIC_SUPABASE_URL="https://your-project.supabase.co"
NEXT_PUBLIC_SUPABASE_ANON_KEY="your-anon-key"
NEXT_PUBLIC_SOROBAN_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
NEXT_PUBLIC_SOROBAN_RPC_URL="https://soroban-testnet.stellar.org"
NEXT_PUBLIC_SOROBAN_CONTRACT_ID="CBEASRMFLJOTK6PVM6276THY26GVNYUXKDWF3JVPKGYEC63MUSQV5P3D"
SUPABASE_SERVICE_ROLE_KEY="your-service-role-key"
ENCRYPTION_SECRET="your-32byte-aes-encryption-secret"# Install dependencies
npm install
# Run Next.js local server
npm run dev
# Run Prettier code formatting
npm run format
# Run production build check
npm run buildDistributed under the MIT License. See LICENSE for details.