Developer Documentation
Complete guides, architectural specifications, code examples, and 1-click AI integration prompts for bKash, Nagad, Rocket, Upay, and TallyPay with ৳0 platform fees.
Documentation Guide
Copy pre-engineered prompts tailored for Google Antigravity, Claude, or Cursor to build this integration in seconds.
1. Architecture Overview
ZeroPay is Bangladesh's modern non-custodial financial rail. Unlike legacy aggregators that hold merchant funds in third-party escrow pools for 3 to 7 days and deduct 2.5% to 3.5% transaction fees, ZeroPay routes customer payments directly to your personal or merchant SIM/bank accounts with ৳0 platform fees.
Direct P2P Settlement
Funds land instantly in your bKash, Nagad, Rocket, or Bank account without intermediate custody.
Sub-second Matching
Deterministic regex matching engine parses inbound carrier SMS alerts and verifies TrxIDs in <1 second.
Anti-Replay Fraud Lock
Consumed TrxIDs are cryptographically locked across the cluster to completely prevent double-spending.
2. Quickstart & API Keys
Every project has isolated environment keys. Use Sandbox Keys (sec_test_...) during development and Live Production Keys (sec_live_...) when accepting real customer payments.
.env.local / .env).ZEROPAY_SECRET_KEY=sec_live_your_secret_key_here
ZEROPAY_WEBHOOK_SECRET=whsec_your_webhook_secret_here
NEXT_PUBLIC_APP_URL=https://yourstore.com
3. Payment Intent & Checkout API
Call POST /api/v1/payments from your backend to create a payment intent. ZeroPay allocates a receiving MFS wallet and returns a hosted checkout URL (checkoutUrl) to redirect the customer.
// Node.js (TypeScript / Fetch)
const response = await fetch("https://www.zero-pay.tech/api/v1/payments", {
method: "POST",
headers: {
"Authorization": "Bearer sec_live_YOUR_SECRET_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
amount: 1500,
currency: "BDT",
merchantOrderId: "ORD-2026-9901",
customerName: "Sadman Sakib",
customerPhone: "01712345678",
customerEmail: "customer@example.com",
successUrl: "https://yourstore.com/checkout/success",
cancelUrl: "https://yourstore.com/checkout/cancel",
}),
});
const { checkoutUrl, payment_id } = await response.json();
// Redirect customer:
window.location.href = checkoutUrl;4. Webhooks & HMAC-SHA256 Signature Security
When a payment is matched and verified, ZeroPay dispatches an encrypted HTTP POST webhook to your server with the header x-zeropay-signature.
x-zeropay-signature: t=1727289600,v1=5d41402abc4b2a76b9719d911017c592b23a9b...- t: Timestamp of dispatch in seconds. Protects against replay attacks.
- v1: Hex-encoded HMAC-SHA256 signature calculated over
${t}.${rawBody}using your Webhook Secret. - Always use timing-safe comparison to prevent timing side-channel attacks.
// Node.js (Next.js App Router / Express)
import crypto from "crypto";
export async function POST(req: Request) {
const rawBody = await req.text();
const sigHeader = req.headers.get("x-zeropay-signature") || "";
const secret = process.env.ZEROPAY_WEBHOOK_SECRET!; // whsec_...
// Format: t=<timestamp>,v1=<hmac_hex>
const parts = Object.fromEntries(sigHeader.split(",").map(p => p.split("=")));
const { t, v1 } = parts;
// Replay Attack Protection (5 minutes tolerance)
if (Math.abs(Math.floor(Date.now() / 1000) - parseInt(t, 10)) > 300) {
return new Response("Expired timestamp", { status: 400 });
}
// Timing-safe HMAC-SHA256 Verification
const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
const isValid = crypto.timingSafeEqual(Buffer.from(v1, "hex"), Buffer.from(expected, "hex"));
if (!isValid) return new Response("Signature mismatch", { status: 400 });
const event = JSON.parse(rawBody);
if (event.event === "payment.succeeded") {
const { merchantOrderId, transactionId, amount } = event.data;
// Fulfill customer order in database
}
return Response.json({ received: true });
}5. Telegram FatherBot Alerts Setup
Receive instant, real-time push alerts to your phone or company Telegram group whenever an operational event occurs.
Step 1: Get Bot Token from @BotFather
- Open Telegram and message
@BotFather. - Send
/newbotand follow instructions to name your bot. - Copy the generated HTTP API Token (e.g.,
7123456789:AAHk...).
Step 2: Get Your Chat ID & Bind
- Add your bot to your alert group or message it directly.
- Extract your Chat ID using
@userinfobotor getUpdates. - In ZeroPay Dashboard → System Settings → Notification Settings, save Token & Chat ID.
- Payment Successfully Matched: Customer paid, TrxID verified, amount settled.
- Unmatched Inbound Carrier SMS: Alert when SMS received without matching checkout session.
- Android Gateway Node Offline: Immediate alert if phone battery or connection drops.
- Wallet Reaching 85% Daily Cap: Prevent account limits before they happen.
6. Android Gateway SMS Node (Phone Pairing)
Turn any Android phone with your personal or merchant bKash/Nagad/Rocket SIM cards into an automated SMS webhook gateway.
- Install the ZeroPay Gateway APK on your Android 8.0+ smartphone.
- In your Dashboard under Gateways → Android Nodes, click "Pair Device" and scan the QR code.
- Grant SMS read permissions.
- Important: Set App Battery Usage to "Unrestricted" in Android Settings so the background service runs uninterrupted 24/7.
- Whenever carrier SMS arrives from
bKash,16167(Nagad), or16216(Rocket), the node instantly pushes the raw text to ZeroPay for sub-second reconciliation.
7. Invoices & Receipts
ZeroPay automatically generates Gmail-compliant, light-mode payment receipts that fit perfectly on 1 single printed page with official ZeroPay branding, merchant name, and verification details.
Phone: +880 9611 522 455
Email: support@zero-pay.tech
Slogan: Payments Without Limits
Customers can click "Download PDF" on the checkout success screen (/checkout/[id]) to download a clean, vector-rendered A4 invoice.
8. 1-Click AI Integration Prompts
Building with Google Antigravity, Claude Code, Cursor, or Windsurf? Skip manual boilerplate! Click below to copy a prompt that tells your AI assistant exactly how to build the entire checkout and webhook flow in your repository.
Launch AI Prompt Studio
Pre-engineered prompts for Next.js, PHP/Laravel, Python/FastAPI, Express, and .NET.
9. Testing & Sandbox Simulation Rail
Test your integration before taking real money:
- Use your Sandbox Secret Key (
sec_test_...) to initialize test checkouts. - In the Sandbox checkout screen, enter any test TrxID starting with
TEST_(e.g.TEST_BKASH_991) to trigger immediate simulated settlement. - In Dashboard → SMS Data → Simulate SMS, test your regex rules with mock SMS payloads without sending real money.
