Good morning
Activity
Get started
0 of 5Order status
Payments by method
How paid orders were verified
Live slots
100 freeEach dot is one paise slot (0 to 99) that can be added to an amount. Busy slots free up on payment, cancel or timeout.
Recent transactions
| Order | Amount | Payer | UTR | Status |
|---|
Transactions
| Order | Amount | Payer | UTR | Txn ID | Status | Time |
|---|
Unmatched payments
| Amount | Payer | UTR | Received |
|---|
Test payment
Create a test order
Same order inside a Telegram bot
No redirectThe QR comes from the API, so your bot or site shows it itself. Customers never leave your platform.
Scan with any UPI app. Expires in 5 minutes.
Add instant payments to any project with AI
Pick website or bot, download the prompt and paste it into ChatGPT, Claude or Gemini together with your project code. The AI adds instant payments and a full admin panel, so you set the gateway URL, API key, expiry, texts and design from your own admin panel, with nothing to edit in code.
What the AI will be told
API key
Webhooks
Endpoint
Payload
{ "event": "payment.verified", "order_id": "ORD123", "status": "paid", "amount": 100.37, "utr": "412345678901", "txn_id": "FAM8K2X91Q", "payer_name": "RAHUL KUMAR", "received_in": null, "reason_code": null, "reason": null }
Events: payment.verified, payment.unmatched, order.expired. Failed deliveries are retried after 1 min, 5 min, 30 min, 2 hours and 6 hours.
Recent deliveries
| Event | Order | Result | Attempts | Time |
|---|
Gmail connection
Credentials
How to get an App Password
- Turn on 2-step verification in your Google account.
- Open Google Account, search for App passwords.
- Create one named after this gateway and copy the 16 letters.
- In Gmail settings, make sure IMAP is enabled.
Connection health
Profile
Account
Change password
Credits
Documentation
Quick start
You can take your first payment in about five minutes. No redirects: your site or bot shows the QR itself.
Authentication
Send your API key in the Authorization header of every request. Calls must come from your server or bot, never from browser code, because the key is secret.
Authorization: Bearer fam_7c91e0b4a2d85f3169ab04c7e2d1f58b3a96c0de Content-Type: application/json
Base URL: https://api.yourdomain.com/v1. Your API key works on any platform, with no domain restriction.
Create an order
Creates an order and returns a QR code to show to your customer.
Body
| Field | Type | Description |
|---|---|---|
amountrequired | number | Amount in rupees, for example 100. A few paise (0 to 99) are added so each open order has its own unique amount. |
order_idrequired | string | Your own order reference, up to 64 characters. Reusing it with the same amount returns the same live order, so retries are safe. Once an order is paid, expired or cancelled the id is free again. |
expires_inoptional | number | Seconds until the order expires. Default 300 (5 minutes), range 120 to 3600. Set it to match your site or bot, for example 900 for 15 minutes. |
webhook_urloptional | string | Overrides your default webhook URL for this order. |
metadataoptional | object | Anything you want back in the webhook, such as a user ID or chat ID. |
curl https://api.yourdomain.com/v1/orders \
-H "Authorization: Bearer fam_..." \
-H "Content-Type: application/json" \
-d '{ "amount": 100, "order_id": "ORD123" }'const res = await fetch("https://api.yourdomain.com/v1/orders", {
method: "POST",
headers: { Authorization: "Bearer fam_...", "Content-Type": "application/json" },
body: JSON.stringify({ amount: 100, order_id: "ORD123" })
});
const order = await res.json(); // order.qr_image is ready for an <img>import requests
order = requests.post("https://api.yourdomain.com/v1/orders",
headers={"Authorization": "Bearer fam_..."},
json={"amount": 100, "order_id": "ORD123" }).json()
print(order["qr_png_url"])$ch = curl_init("https://api.yourdomain.com/v1/orders");
curl_setopt_array($ch, [
CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["Authorization: Bearer fam_...", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode(["amount" => 100, "order_id" => "ORD123"])
]);
$order = json_decode(curl_exec($ch), true);Response
{
"id": "ord_8fK2xQ",
"order_id": "ORD123",
"status": "pending",
"base_amount": 100,
"amount": 100.37,
"expires_at": "2026-11-06T09:40:00+05:30",
"qr_image": "data:image/png;base64,iVBOR...",
"qr_base64": "iVBOR...",
"qr_png_url": "https://api.yourdomain.com/v1/orders/ord_8fK2xQ/qr.png",
"upi_link": "upi://pay?pa=rockystore@fam&am=100.37&tn=ORD123"
}amount to your customer. The paise are what identify the order. The QR is returned right in the response: use qr_image in an <img> on a website, qr_base64 to upload the picture yourself, or qr_png_url to send it to a bot as a photo. The customer scans it where it is shown and the payment is verified automatically. A QR is only available while the order is waiting for payment.Get an order
Check an order any time. Webhooks are faster, but this is handy for polling.
{
"id": "ord_8fK2xQ", "order_id": "ORD123", "status": "paid", "amount": 100.37,
"payment": {
"utr": "412345678901", "txn_id": "FAM8K2X91Q",
"payer_name": "RAHUL KUMAR", "paid_at": "2026-11-06T09:34:12+05:30",
"received_in": "rockystore@fam"
}
}Order status
| Status | Meaning |
|---|---|
| pending | Waiting for the customer to pay. |
| paid | Payment found in your Gmail and matched. |
| expired | Time ran out. The slot is released. |
| cancelled | You cancelled the order. |
Cancel, list and account
{id} can be the gateway id or your own order_id, here and on GET.status, order_id (your own id), created_from, created_to, limit, starting_after.Webhooks
We call your server when something happens to an order. Set the URL on the Webhooks page, or pass webhook_url per order.
| Event | Sent when |
|---|---|
payment.verified | A payment is matched to an order. |
order.expired | An order times out unpaid. |
payment.unmatched | A payment arrives that no order claimed (wrong amount, or after expiry). Attach it on the Unmatched payments page. |
{
"event": "payment.verified",
"order_id": "ORD123",
"id": "ord_8fK2xQ",
"status": "paid",
"amount": 100.37,
"paid_at": "2026-11-06T09:34:12+05:30",
"utr": "412345678901",
"txn_id": "FAM8K2X91Q",
"payer_name": "RAHUL KUMAR",
"received_in": "rockystore@fam",
"metadata": { "chat_id": 99887766 }
}Every webhook also has reason_code and reason (the exact reason when a payment is not accepted). A field that the FamPay email does not contain is sent as null, for example utr on a FamPay to FamPay transfer.
Verify the signature
Every request carries X-Fam-Signature (HMAC SHA256 of the raw body). For replay protection also use X-Fam-Timestamp and X-Fam-Signature-V2, the HMAC SHA256 of timestamp + "." + body. Reject requests whose timestamp is more than 5 minutes old.
import crypto from "crypto";
const sig = req.headers["x-fam-signature"];
const expected = crypto.createHmac("sha256", process.env.FAM_WEBHOOK_SECRET)
.update(req.rawBody).digest("hex");
if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) return res.sendStatus(401);
res.sendStatus(200);import hmac, hashlib
expected = hmac.new(SECRET.encode(), request.body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(request.headers["X-Fam-Signature"], expected):
return HttpResponse(status=401)
return HttpResponse(status=200)Delivery and retries
- Reply with any
2xxwithin 10 seconds. - If we get anything else, we retry after 1 min, 5 min, 30 min, 2 hours and 6 hours.
- The same event can arrive twice. Use
order_idto ignore repeats.
Use it in a Telegram bot
The bot shows the QR inside the chat. The customer never leaves Telegram.
order = requests.post(API + "/orders",
headers={"Authorization": "Bearer " + KEY},
json={"amount": 100, "order_id": oid, "expires_in": 300, # 5 minutes, change as you like (120 to 3600)
"metadata": {"chat_id": chat_id}}).json()
# the QR goes straight into the chat, no link to open
bot.send_photo(chat_id, order["qr_png_url"],
caption=f"Scan and pay exactly ₹{order['amount']}. Expires in 5 minutes.")
# or upload the picture yourself: bot.send_photo(chat_id, base64.b64decode(order["qr_base64"]))
# the customer pays; you get a payment.verified webhook, nothing more to doComplete example
A working flow in four files: create the order, show the exact amount and QR, wait for the webhook, deliver. Copy it, set three environment variables (FAM_BASE_URL, FAM_API_KEY, FAM_WEBHOOK_SECRET) and run it.
// npm i express then node server.js
const express = require("express"), crypto = require("crypto");
const API = process.env.FAM_BASE_URL, KEY = process.env.FAM_API_KEY, SECRET = process.env.FAM_WEBHOOK_SECRET;
const app = express(), orders = new Map(); // use a database in a real project
const fam = (path, body) => fetch(API + path, {
method: body ? "POST" : "GET",
headers: { Authorization: "Bearer " + KEY, "Content-Type": "application/json" },
body: body && JSON.stringify(body) }).then(r => r.json());
// 1) the page asks us to start a payment
app.post("/pay", express.json(), async (req, res) => {
const id = "ORD" + Date.now();
const o = await fam("/orders", { amount: Number(req.body.amount), order_id: id, expires_in: 300 });
if (o.error) return res.status(400).json(o.error);
orders.set(id, { status: "pending", amount: o.amount });
res.json({ order_id: id, amount: o.amount, qr: o.qr_image, expires_at: o.expires_at });
});
// 2) the page polls this every 3 seconds
app.get("/status/:id", (req, res) => res.json({ status: (orders.get(req.params.id) || {}).status || "unknown" }));
// 3) the gateway tells us the payment is done
app.post("/webhook", express.raw({ type: "*/*" }), (req, res) => {
const ts = req.headers["x-fam-timestamp"], sig = req.headers["x-fam-signature-v2"] || "";
const exp = crypto.createHmac("sha256", SECRET).update(ts + "." + req.body).digest("hex");
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300 || sig.length !== exp.length ||
!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(exp))) return res.sendStatus(401);
const ev = JSON.parse(req.body);
const o = orders.get(ev.order_id);
if (ev.event === "payment.verified" && o && o.status !== "paid") {
o.status = "paid"; // deliver the product / add balance here
} else if (ev.event === "order.expired" && o && o.status === "pending") o.status = "expired";
res.sendStatus(200);
});
app.use(express.static("public")); app.listen(3000);# pip install flask requests
import os, hmac, hashlib, time, json, requests
from flask import Flask, request, jsonify
API, KEY, SECRET = os.environ["FAM_BASE_URL"], os.environ["FAM_API_KEY"], os.environ["FAM_WEBHOOK_SECRET"]
H = {"Authorization": "Bearer " + KEY}
app, orders = Flask(__name__), {} # use a database in a real project
@app.post("/pay")
def pay():
oid = "ORD%d" % (time.time() * 1000)
o = requests.post(API + "/orders", headers=H, json={
"amount": float(request.json["amount"]), "order_id": oid, "expires_in": 300}).json()
if "error" in o: return jsonify(o["error"]), 400
orders[oid] = {"status": "pending", "amount": o["amount"]}
return jsonify(order_id=oid, amount=o["amount"], qr=o["qr_image"], expires_at=o["expires_at"])
@app.get("/status/<oid>")
def status(oid): return jsonify(status=orders.get(oid, {}).get("status", "unknown"))
@app.post("/webhook")
def webhook():
ts, sig = request.headers.get("X-Fam-Timestamp", "0"), request.headers.get("X-Fam-Signature-V2", "")
exp = hmac.new(SECRET.encode(), ts.encode() + b"." + request.get_data(), hashlib.sha256).hexdigest()
if abs(time.time() - int(ts)) > 300 or not hmac.compare_digest(sig, exp): return "", 401
ev = json.loads(request.get_data()); o = orders.get(ev["order_id"])
if ev["event"] == "payment.verified" and o and o["status"] != "paid":
o["status"] = "paid" # deliver the product / add balance here
elif ev["event"] == "order.expired" and o and o["status"] == "pending":
o["status"] = "expired"
return "", 200<?php
// pay.php : creates the order and returns the QR to your page
$API = getenv("FAM_BASE_URL"); $KEY = getenv("FAM_API_KEY");
function fam($path, $body = null) { global $API, $KEY;
$ch = curl_init($API . $path);
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["Authorization: Bearer $KEY", "Content-Type: application/json"]]);
if ($body) { curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body)); }
return json_decode(curl_exec($ch), true); }
$oid = "ORD" . round(microtime(true) * 1000);
$o = fam("/orders", ["amount" => (float)$_POST["amount"], "order_id" => $oid, "expires_in" => 300]);
if (isset($o["error"])) { http_response_code(400); exit(json_encode($o["error"])); }
// save $oid, $o["amount"], status "pending" in your database here
echo json_encode(["order_id" => $oid, "amount" => $o["amount"], "qr" => $o["qr_image"], "expires_at" => $o["expires_at"]]);
// ---- webhook.php ----
$raw = file_get_contents("php://input");
$ts = $_SERVER["HTTP_X_FAM_TIMESTAMP"] ?? "0"; $sig = $_SERVER["HTTP_X_FAM_SIGNATURE_V2"] ?? "";
$exp = hash_hmac("sha256", $ts . "." . $raw, getenv("FAM_WEBHOOK_SECRET"));
if (abs(time() - (int)$ts) > 300 || !hash_equals($exp, $sig)) { http_response_code(401); exit; }
$ev = json_decode($raw, true);
if ($ev["event"] === "payment.verified") {
// if the order is not marked paid yet: mark it paid and deliver here
}
http_response_code(200);<!-- public/index.html : the customer page. It only talks to YOUR server, never to the gateway. -->
<input id="amt" type="number" value="100"> <button onclick="pay()">Pay</button>
<div id="box" style="display:none">
<h3>Pay exactly ₹<span id="exact"></span></h3>
<img id="qr" width="260" alt="UPI QR"><p id="msg">Waiting for payment...</p>
</div>
<script>
async function pay() {
const r = await fetch("/pay", { method: "POST", headers: { "Content-Type": "application/json" },
body: JSON.stringify({ amount: document.getElementById("amt").value }) });
const o = await r.json();
if (o.message) return alert(o.message);
exact.textContent = o.amount.toFixed(2); qr.src = o.qr; box.style.display = "block";
const t = setInterval(async () => {
const s = (await (await fetch("/status/" + o.order_id)).json()).status;
if (s === "paid") { clearInterval(t); msg.textContent = "Payment received. Thank you!"; }
if (new Date() > new Date(o.expires_at) || s === "expired") { clearInterval(t); msg.textContent = "Expired. Please try again."; }
}, 3000);
}
</script>- The customer page calls your server. Your server calls the gateway with the secret key.
- Show
amountexactly as returned (the paise identify the order) and theqr_image. - Deliver only when the signed
payment.verifiedwebhook arrives, never because the browser says so.
Errors and limits
Errors use standard HTTP codes and a JSON body: { "error": { "code": "...", "message": "..." } }.
| HTTP | Code | Meaning |
|---|---|---|
| 401 | invalid_api_key | Missing, wrong or regenerated key. |
| 400 | invalid_amount | Amount is missing, zero or too large. |
| 404 | order_not_found | No order with this ID in your account. |
| 409 | gmail_not_connected | Connect Gmail before creating orders. |
| 429 | rate_limited | More than 120 requests a minute on one key. |
| 503 | slots_full | All 100 unique-amount slots for this amount are busy. Try again shortly or use a shorter expires_in. |
| 400 | invalid_order_id | order_id is missing or longer than 64 characters. |
| 409 | order_id_conflict | This order_id is live with a different amount. Use a new id. |
| 402 | insufficient_credits | Credits are on and your wallet is too low. Ask the admin to add credits. |
| 403 | account_suspended | Your account was suspended by the administrator. |