Developer Documentation & API Reference

0

Base URL & Authentication

All server API requests use HTTPS. Send your live key in X-Api-Key: YOUR_API_KEY or Authorization: Bearer YOUR_API_KEY. The hosted checkout calls the status endpoint without exposing that key.

BASE URL

https://payment.burstaxis.online

Authentication: Keep the API key on your server. Header authentication is recommended; JSON api_key is accepted by order creation for backwards compatibility.
Plan limits: Order creation is governed by the merchant's current plan and active-link allowance. HTTP 429 includes an upgrade_url when a plan limit is reached.
Status polling: Poll /api/verify-order.php every 2–3 seconds per active order. The checkout performs a targeted Gmail receipt scan with overlap protection.
Non-Custodial Settlement & Refunds: 100% of customer funds transfer directly into your personal FamPay UPI wallet with zero platform custody. Because Eclipse Gateway never holds, escrows, or debits your money, programmatic debit/refund endpoints are intentionally not supported; merchants issue refunds manually directly from their FamApp or UPI banking app.

1

Prerequisites — Connect FamPay Account

Before making any API calls, connect your FamPay Gmail account on the Integrations Page. This allows Eclipse Gateway to automatically monitor your inbox for payment confirmation emails and verify transactions in real-time.

Step	What to Do
1	Go to Integrations → Connect FamPay Gmail
2	Enter your FamPay-linked Gmail address
3	Create a Google App Password (16 characters, no spaces) and enter it
4	Enter your FamPay UPI ID (e.g., `yourname@fam`)
5	Click Save — your `api_key` will now be active

Credential handling: Use a dedicated, revocable 16-character Google App Password—never your primary Google password. This build stores the App Password server-side so the worker can connect to Gmail; protect database and configuration access. The UI does not return the saved password. Merchant passkeys are available separately in Profile Settings.

2

Create Order & Generate UPI QR

Creates a unique dynamic payment session. Eclipse Gateway generates an atomic order session with Bank UTR Idempotency locking, allowing customers to pay exact clean amounts without double-spend conflicts.

Parameter	Type	Status	Description
X-Api-Key	header	Required	Your active server-side API key.
amount	float	Required	Payment amount in INR (e.g., `499.00`).
redirect_url	string	Optional	Where to redirect user after hosted checkout payment.
webhook_url	string	Optional	Override the dashboard Webhook URL for this order only.
customer_name	string	Optional	Customer's full name or internal user ID.
customer_email	string	Optional	Customer's email address.
customer_phone	string	Optional	Customer's 10-digit mobile number.
note	string	Optional	Your internal order note, up to 1000 characters.
validity_hours	integer	Optional	Payment window from 1 to 720 hours; defaults to 24.

curl -X POST "https://payment.burstaxis.online/api/create-order.php" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{"amount":"499.00","customer_name":"Rahul Sharma","validity_hours":24}'

from burstfamgateway import FamGateway

fg = FamGateway(api_key="YOUR_API_KEY")
order = fg.create_order(amount=499.00)

// Bundled Eclipse Gateway PHP SDK
require_once 'FamGateway.php';

$fg = new FamGateway('YOUR_API_KEY');

// Method 1: Instant 1-line checkout redirect (easiest for e-commerce stores)
$fg->createPayment(499.00, 'https://yoursite.com/success');

// Method 2: Custom API integration (returns order data without redirecting)
$order = $fg->createOrder(499.00, [
    'customer_name' => 'Rahul Sharma',
    'redirect_url'  => 'https://yoursite.com/success'
]);

echo "Checkout URL: " . $order['checkout_url'];
echo "QR Image URL: " . $order['qr_url'];

// The SDK sends JSON to POST /api/create-order.php over verified HTTPS.

RESPONSE — SUCCESS (200 OK)

{
  "status": "success",
  "data": {
    "order_id": "fg_0123456789abcdefabcd",
    "expires_at": "2026-09-06T10:30:00+00:00",
    "validity_hours": 24,
    "amount": 499,
    "checkout_url": "https://payment.burstaxis.online/checkout.php?order_id=fg_0123456789abcdefabcd",
    "qr_url": "https://api.qrserver.com/v1/create-qr-code/?size=320x320&data=...",
    "upi_intent": "upi://pay?pa=merchant%40fam&pn=Merchant&am=499.00&tr=fg_0123456789abcdefabcd&tn=fg0123456789abcdefabcd&cu=INR",
    "redirect_url": "",
    "webhook_url": ""
  }
}

Hosted Checkout: Redirect customer to checkout_url for an instant mobile-optimized payment screen with live auto-verification.
Telegram & Custom Apps: Deliver qr_url directly as an image in chat, or open checkout_url in button links.
Offline & Screenshot Payments (Autonomous Sync): If a customer takes a screenshot of the QR code and closes their browser tab, the configured Eclipse Gateway background worker monitors all active sessions. When the customer scans the screenshot from their gallery and pays, the daemon detects the bank receipt, locks the Bank UTR, and fires your webhook automatically.
Verified binding: The trusted receipt must contain the exact order reference, exact amount, and one 12-digit UTR. Amount-only matching is never used.

3

Verify Payment Status (Poll)

After displaying the QR code, poll this endpoint every 2–3 seconds. A pending request triggers a targeted receipt scan; confirmation time still depends on FamPay email delivery and Gmail IMAP availability.

Parameter	Type	Status	Description
X-Api-Key	header	Server use	Recommended for merchant backend calls; omitted only by the hosted checkout.
order_id	string	Required	The `order_id` returned from the create order call.

curl "https://payment.burstaxis.online/api/verify-order.php?order_id=fg_0123456789abcdefabcd" \
  -H "X-Api-Key: YOUR_API_KEY"

// Bundled Eclipse Gateway PHP SDK
$status = $fg->getOrderStatus('fg_0123456789abcdefabcd');

if (($status['order_status'] ?? '') === 'success') {
    $utr = $status['data']['utr'];
    echo "Payment verified! UTR: " . $utr;
}

# Use the order ID and expected amount saved by your server
status = fg.get_status(order.order_id)

if status.is_paid and status.amount == order.amount:
    print("Payment Verified! UTR:", status.utr)
# Fulfill only once, for the customer associated with this stored order.

RESPONSE — SUCCESS (200 OK)

{
  "status": "success",
  "order_status": "success",
  "expires_at": "2026-09-06T10:30:00+00:00",
  "payment_verification_status": "verified",
  "verification_message": "Payment verified.",
  "order_id": "fg_0123456789abcdefabcd",
  "data": {
    "order_id": "fg_0123456789abcdefabcd",
    "status": "success",
    "amount": 499,
    "customer_name": "Rahul Sharma",
    "utr": "420987654321",
    "checkout_url": "https://payment.burstaxis.online/checkout.php?order_id=fg_0123456789abcdefabcd",
    "qr_url": "",
    "upi_intent": "",
    "created_at": "2026-09-05 10:30:00",
    "paid_at": "2026-09-05 10:31:12",
    "redirect_url": ""
  }
}

FRONTEND JAVASCRIPT POLLING (PUBLIC NO-AUTH ENDPOINT)

// Safe for frontend browser JavaScript (does not require or expose your secret api_key)
GET /api/verify-order.php?order_id=fg_0123456789abcdefabcd

// Response:
// Read order_status: pending, success, expired, failed, or disabled.
// The hosted checkout uses this form and never exposes the API key.

Server-to-Server verification: Send X-Api-Key and the order ID. Save the expected amount and customer mapping in your own database before redirecting.
Hosted checkout polling: The same endpoint supports the unguessable checkout order reference without exposing the secret key.
Anti-replay protection: Merchant-scoped UTR claims and atomic pending-to-success updates prevent one verified receipt from crediting multiple orders.
Bot polling: Query in a non-blocking loop every 2–3 seconds and fulfill exactly once only when order_status is success and the amount matches your saved order.

4

Bundled Python SDK & Telegram Bot Integration

Included with this project: install the local python-sdk directory with python -m pip install ./python-sdk (Python 3.10+). PyPI publication is not claimed. This is an Eclipse Gateway client by Priyam Manna, not an official FamApp SDK.

PYTHON QUICKSTART (LOCAL SDK)

# 1. From the extracted project: python -m pip install ./python-sdk
import os
from burstfamgateway import FamGateway

# 2. Initialize with your API Key
fg = FamGateway(api_key=os.environ["BURSTFAM_API_KEY"])

# 3. Create Dynamic UPI Order (No customer details required)
order = fg.create_order(amount=499.00)

print("Order ID:", order.order_id)
print("QR Code Image URL:", order.qr_url)
print("Deep UPI Intent:", order.upi_intent)
print("Hosted Checkout URL:", order.checkout_url)

# 4. Check server-verified status; validate your stored order/customer mapping
status = fg.get_status(order.order_id)
if status.is_paid and status.amount == order.amount:
    print(f"Payment Confirmed! Bank UTR: {status.utr}")

TELEGRAM BOT IN-CHAT CHECKOUT (telebot)

# pip install ./python-sdk pyTelegramBotAPI
import telebot
import os
from telebot.types import InlineKeyboardMarkup, InlineKeyboardButton
from burstfamgateway import FamGateway

bot = telebot.TeleBot(os.environ["TELEGRAM_BOT_TOKEN"])
fg = FamGateway(api_key=os.environ["BURSTFAM_API_KEY"])
# Demo only: replace with persistent database storage in production.
saved_orders = {}

@bot.message_handler(commands=['buy'])
def handle_buy(message):
    # 1. Create UPI payment order for Rs 50
    order = fg.create_order(amount=50.0)
    saved_orders[order.order_id] = (message.from_user.id, order.amount)

    # 2. Create interactive Pay Button
    markup = InlineKeyboardMarkup()
    markup.row(
        InlineKeyboardButton("Pay via UPI App / Web", url=order.checkout_url),
        InlineKeyboardButton("Verify Status", callback_data=f"chk:{order.order_id}")
    )

    # 3. Send QR directly in Telegram chat (Zero external web redirect)
    caption = (
        f"Payment Details:\n\n"
        f"Amount to Pay: Rs {order.payable_amount}\n"
        f"Order ID: `{order.order_id}`\n\n"
        f"Scan the QR code with PhonePe, Google Pay, or Paytm.\n"
        f"After completing the transfer, tap 'Verify Status' below."
    )

    bot.send_photo(
        chat_id=message.chat.id,
        photo=order.qr_url,
        caption=caption,
        parse_mode="Markdown",
        reply_markup=markup
    )

@bot.callback_query_handler(func=lambda call: call.data.startswith("chk:"))
def handle_check(call):
    order_id = call.data.split(":")[1]
    saved = saved_orders.get(order_id)
    if not saved or saved[0] != call.from_user.id:
        bot.answer_callback_query(call.id, "Unknown order for this user.", show_alert=True)
        return
    status = fg.get_status(order_id)

    if status.is_paid and status.amount == saved[1]:
        bot.answer_callback_query(call.id, "Payment Verified!", show_alert=True)
        bot.send_message(call.message.chat.id, f"Payment Received! Bank UTR: `{status.utr}`\nDemo only: no access granted. Fulfill once in your database.")
    else:
        bot.answer_callback_query(call.id, "Payment pending. Please complete the UPI transfer.", show_alert=True)

bot.infinity_polling()

5

Payment Links (Shareable URLs)

Each generated payment link is a single order with its own exact amount, expiry, and fg_ reference. Share the hosted checkout URL and verify it through verify-order.php.

Parameter	Type	Status	Description
order_id	string	Required	The generated identifier in the form `fg_` followed by 20 lowercase hexadecimal characters.

CHECK IF PAYMENT LINK IS PAID

GET /api/verify-order.php?order_id=fg_0123456789abcdefabcd
X-Api-Key: YOUR_API_KEY

6

Webhooks & HMAC-SHA256 Signature Verification

After a receipt is verified, Eclipse Gateway queues an HTTPS POST notification. Delivery time depends on receipt detection, DNS, and the receiving server. The X-FamGateway-Signature value is HMAC-SHA256 of the exact raw JSON body using the merchant secret key.

Global Webhook URL: Configure your default webhook listener in your Merchant Dashboard under Webhooks Settings.
Per-order routing: Send "webhook_url":"https://yourserver.com/hook" in the JSON body of POST /api/create-order.php. It overrides the dashboard URL for that order.
Endpoint rules: The webhook URL must use public HTTPS on port 443. Private, reserved, credential-bearing, and redirecting targets are rejected.

const express = require('express');
const crypto = require('crypto');
const app = express();

const API_KEY = 'YOUR_FAMGATEWAY_API_KEY';

// IMPORTANT: Preserve raw request body buffer for HMAC verification
app.use(express.json({
  verify: (req, res, buf) => { req.rawBody = buf; }
}));

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-famgateway-signature'];
  const expected = crypto.createHmac('sha256', API_KEY)
    .update(req.rawBody)
    .digest('hex');

  // Cryptographically compare signatures (prevents timing attacks)
  if (!signature || !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send('Invalid webhook signature');
  }

  const event = req.body;
  if (event.event === 'payment.success' || event.status === 'success') {
    const { order_id, amount, utr } = event;
    console.log(`Payment confirmed: Order ${order_id} for Rs.${amount} (UTR: ${utr})`);
    
    // TODO: Fulfill order in your database / deliver product
  }

  // Always respond with 200 OK within 10 seconds
  res.status(200).send('OK');
});

app.listen(3000, () => console.log('Webhook server running on port 3000'));

import hmac, hashlib
from fastapi import FastAPI, Request, HTTPException, Header

app = FastAPI()
API_KEY = "YOUR_FAMGATEWAY_API_KEY"

@app.post("/webhook")
async def famgateway_webhook(request: Request, x_famgateway_signature: str = Header(None)):
    body = await request.body()
    computed = hmac.new(API_KEY.encode(), body, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(computed, x_famgateway_signature or ""):
        raise HTTPException(status_code=401, detail="Invalid signature")

    data = await request.json()
    if data.get("status") == "success":
        order_id = data.get("order_id")
        utr = data.get("utr")
        amount = data.get("amount")
        print(f"Payment Verified: Order {order_id}, UTR: {utr}, Amount: Rs.{amount}")

    return {"status": "ok"}

<?php
// Bundled Eclipse Gateway PHP SDK
require_once 'FamGateway.php';

$fg = new FamGateway('YOUR_API_KEY');

$rawBody   = file_get_contents('php://input');
$sigHeader = $_SERVER['HTTP_X_FAMGATEWAY_SIGNATURE'] ?? '';

// One-line cryptographic HMAC-SHA256 signature verification
$event = $fg->verifyWebhook($rawBody, $sigHeader);

if ($event !== false && (($event['event'] ?? '') === 'payment.success' || ($event['status'] ?? '') === 'success')) {
    $orderId    = $event['order_id'];
    $utr        = $event['utr'];
    $amount     = $event['amount'];
    // TODO: Fulfill order in your database (credit wallet, deliver digital good)
    
    http_response_code(200);
    echo 'OK';
} else {
    // Fake or invalid signature
    http_response_code(401);
    die('Invalid signature');
}

WEBHOOK EVENT PAYLOAD (JSON)

{
  "event":          "payment.success",
  "order_id":       "fg_0123456789abcdefabcd",
  "amount":         499,
  "status":         "success",
  "utr":            "420987654321",
  "timestamp":      1788352710
}

Header: X-FamGateway-Signature contains the HMAC-SHA256 signature calculated over the raw JSON payload.
Events dispatched: Only verified payment.success events are queued. Pending, expired, disabled, and failed orders do not generate success webhooks.
Background processing: Closed-browser payments are detected only when cron-payments.php is configured as a recurring CLI job on the server.
Automatic Retries: Eclipse Gateway retries failed webhook endpoints up to 5 times with exponential backoff if your server returns non-2xx status codes.

7

Verified Browser Receipt

A successful order opens a server-derived receipt page at success.php?order_id=.... The page reads amount, merchant, paid time, and UTR from the database and includes print styles.

Verified values: Query-string amount, status, UTR, and customer overrides are not trusted.
Printing: Use the browser's Print action to print or save the rendered receipt as PDF.
No PDF API claim: This build does not expose a binary PDF download endpoint and does not email PDF attachments.

VERIFIED RECEIPT PAGE

GET /success.php?order_id=fg_0123456789abcdefabcd

// Available only after the database order status is success.
// Use the browser Print dialog if a PDF copy is required.

8

HTTP Status & Error Codes

Errors use {"status":"error","message":"Description"}. Do not treat a network error as proof that a payment failed.

HTTP Code	Status Field	When it happens	Fix
401	`error`	Missing API key on order creation, or a supplied key does not own the requested order	Check your API key in API Keys
403	`error`	Integration is incomplete or the owner disabled API access	Confirm Integrations or contact support
404	`error`	`order_id` does not exist	Verify the order_id is correct
422	`error`	Invalid amount, validity, UPI ID, or request field	Correct the field described by `message`
429	`error`	Current plan payment or active-link limit reached	Use the returned `upgrade_url` or close an unused pending link
503	`error`	Database or required service is temporarily unavailable	Retry with backoff; do not create duplicate orders blindly

9

Production Requirements

PHP with PDO MySQL, cURL, OpenSSL, and IMAP extensions.
HTTPS on the application and every webhook endpoint.
A recurring CLI job for cron-payments.php so closed-browser payments can be detected.
A merchant Gmail App Password and verified FamPay UPI ID configured through Integrations.
Persist your own order/customer mapping and make fulfillment idempotent.

Developer Documentation & API Reference API v2.0 Live status