REST API Reference v1.16
ZeroPay API Reference
HTTP API endpoints for creating checkout sessions, querying transactions, configuring Telegram FatherBot alerts, and receiving cryptographic webhooks.
Select Code Language:
1. Authentication
ZeroPay authenticates API requests using Bearer tokens. Pass your Secret API Key (sec_live_... or sec_test_...) in the standard Authorization header:
Authorization: Bearer sec_live_YOUR_SECRET_KEYPOST/api/v1/payments
Creates a new payment intent and generates a unified hosted checkout URL.
curl -X POST https://www.zero-pay.tech/api/v1/payments \
-H "Authorization: Bearer sec_live_YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": 1500,
"currency": "BDT",
"merchantOrderId": "ORD-98214",
"customerPhone": "01712345678",
"customerName": "Rahim Ahmed",
"customerEmail": "rahim@example.com",
"successUrl": "https://yourstore.com/checkout/success",
"cancelUrl": "https://yourstore.com/checkout/cancel"
}'GET/api/v1/payments/:id
Retrieves real-time verification and settlement status of an existing payment intent.
curl -X GET https://www.zero-pay.tech/api/v1/payments/pi_live_8f921ba09c4d \ -H "Authorization: Bearer sec_live_YOUR_SECRET_KEY"
POST/api/notifications/telegram/test
Tests and validates your Telegram Bot Father credentials by dispatching a real test message to your configured Chat ID.
curl -X POST https://www.zero-pay.tech/api/notifications/telegram/test \
-H "Content-Type: application/json" \
-d '{
"token": "7123456789:AAHk_your_bot_token_from_botfather",
"chatId": "-100123456789"
}'5. Webhook Signature Verification Header (x-zeropay-signature)
When a payment is settled, ZeroPay delivers a signed JSON payload with the header x-zeropay-signature: t=<timestamp>,v1=<hex_hmac>.
// Verify x-zeropay-signature header (Node.js)
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!;
// Split "t=1727289600,v1=5d41402abc..."
const parts = Object.fromEntries(sigHeader.split(",").map(p => p.split("=")));
const { t, v1 } = parts;
// Replay Attack Tolerance (5 minutes)
if (Math.abs(Math.floor(Date.now() / 1000) - parseInt(t, 10)) > 300) {
return new Response("Expired timestamp", { status: 400 });
}
// Timing-safe comparison
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") {
// Process order fulfillment
}
return Response.json({ received: true });
}