Base URL & Authentication

All API requests are made over HTTPS. Authentication uses a simple api_key query parameter. You can find your API key in the API Keys section of your dashboard.

BASE URL

https://famgateway.in

🔑 Authentication: Include ?api_key=YOUR_API_KEY in every request. Never expose your API key in client-side JavaScript or public repositories.

⏱️ Rate Limit: 20 API requests per IP per 60 seconds. Exceeding this returns HTTP 429. Poll the verify endpoint every 3–5 seconds, not faster.

1

Prerequisites — Connect Your FamPay Account

Before making any API calls, you must connect your FamPay Gmail account in the Dashboard. This allows FamGateway to automatically monitor your inbox for payment confirmation emails and verify transactions in real-time.

Step	What to Do
1	Go to Dashboard → Gmail Settings
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

⚠️ Why Gmail App Password? FamGateway reads the FamPay payment notification emails from your Gmail inbox via IMAP to verify transactions. Your main Gmail password is never stored — only the App Password, which is encrypted in our database and can be revoked anytime.

2

Create Order & Generate UPI QR

Creates a unique payment session. The API automatically adds a small fractional offset (e.g., ₹100 → ₹100.04) to the amount to ensure each transaction is uniquely identifiable — preventing double-spend fraud even when multiple customers pay the same base amount simultaneously.

Parameter	Type	Status	Description
api_key	string	Required	Your active API Key.
amount	float	Required	Payment amount (e.g., `499.00`). Must be a positive number.
redirect_url	string	Optional	Where to redirect the user after a successful payment. Must start with `http://` or `https://`.

GET /api/qr.php

GET https://famgateway.in/api/qr.php?api_key=YOUR_KEY&amount=499

RESPONSE — 200 OK

{
  "status": "success",
  "data": {
    "order_id":       "aryanispe-EUF6VL",
    "qr_url":         "https://famgateway.in/api/qr-image.php?order_id=aryanispe-EUF6VL",
    "amount":         "499",
    "payable_amount": "499.04",
    "created_at_ist": "29-07-2026 14:30:00",
    "expires_at_ist": "29-07-2026 14:35:00"
  }
}

⚠️ Critical — Use payable_amount: Always display payable_amount (e.g., ₹499.04) to your user on screen, NOT the base amount. The customer must send this exact amount. The gateway matches this unique decimal to verify the payment.

🖼️ QR Code: Do NOT generate your own QR code. Simply render qr_url as an <img src="..."> tag. The image is auto-generated with your avatar and the correct UPI deep link embedded.

⏰ Expiry: Orders expire in 5 minutes. After expiry, verify-order.php returns status: expired.

3

Verify Payment Status (Poll)

After displaying the QR code, poll this endpoint every 3–5 seconds from your server. When the customer pays, FamGateway detects the FamPay Gmail notification in real-time, verifies the exact fractional amount, and returns a success response with the full transaction details.

Parameter	Type	Status	Description
api_key	string	Required	Your API key.
order_id	string	Required	The `order_id` returned from Step 2's Create Order call.

GET /api/verify-order.php

GET https://famgateway.in/api/verify-order.php?api_key=YOUR_KEY&order_id=aryanispe-EUF6VL

RESPONSE — SUCCESS (200 OK)

{
  "status": "success",
  "data": {
    "order_id":         "aryanispe-EUF6VL",
    "transaction_id":   "FMP987654321",
    "amount":           499.04,
    "utr":              "420987654321",
    "sender_name":      "Rahul Sharma",
    "payment_time_ist": "29-07-2026 14:31:12"
  }
}

🔄 Webhooks: You will receive a JSON webhook notification at your configured URL as soon as the payment is confirmed.

🔒 Anti-Replay Protection: The gateway has built-in double-spend detection. The same FamPay transaction email cannot confirm two different orders. Each utr can only be used once.

4

Full Integration Examples

Complete, copy-paste ready integration examples in PHP, Python, and Node.js showing the full payment flow.

PHP — Secure Checkout Flow

<?php
$API_KEY = 'YOUR_API_KEY';
$REDIRECT = urlencode('https://yourwebsite.com/success.php');
$BASE_URL = 'https://famgateway.in';

// Step 1: Create order
$res = file_get_contents("$BASE_URL/api/qr.php?api_key=$API_KEY&amount=499&redirect_url=$REDIRECT");
$data = json_decode($res, true)['data'];

// Step 2: Redirect user to Secure Hosted Checkout
header("Location: " . $data['checkout_url']);
exit;

/* 
 * WHAT HAPPENS NEXT?
 * 1. User sees the QR code on our secure page.
 * 2. They pay and our system verifies it automatically.
 * 3. They are redirected back to your redirect_url.
 * 4. We will send a Webhook to your server confirming the payment!
 */

Python — Secure Checkout Flow

import requests
from flask import redirect

API_KEY  = 'YOUR_API_KEY'
BASE_URL = 'https://famgateway.in'
REDIRECT = 'https://yourwebsite.com/success'

# Step 1: Create order
res = requests.get(f'{BASE_URL}/api/qr.php', params={
    'api_key': API_KEY, 'amount': 499, 'redirect_url': REDIRECT
}).json()

checkout_url = res['data']['checkout_url']

# Step 2: Redirect user to Hosted Checkout
# (Example using Flask redirect)
return redirect(checkout_url)

# Wait for our Webhook to hit your server to mark the order as paid!

Node.js — Secure Checkout Flow

const API_KEY  = 'YOUR_API_KEY';
const BASE_URL = 'https://famgateway.in';
const REDIRECT = 'https://yourwebsite.com/success';
const amount   = 499;

async function createCheckout() {
  // Step 1: Create order
  const res = await fetch(
    `${BASE_URL}/api/qr.php?api_key=${API_KEY}&amount=${amount}&redirect_url=${encodeURIComponent(REDIRECT)}`
  );
  const { data } = await res.json();
  
  // Step 2: Redirect user
  // (In Express.js, this would be: res.redirect(data.checkout_url))
  window.location.href = data.checkout_url;
}

// We will handle the QR code and payment verification.
// You just need to listen for the Webhook to fulfill the order!

5

Payment Links (Shareable URLs)

Payment Links are reusable, shareable URLs that let anyone pay you without needing any API integration. Create them from your dashboard or via API. You can verify if a payment link has been paid using the same verify-order.php endpoint.

Parameter	Type	Status	Description
order_id	string	Required	For payment links, prefix the slug with `LINK_` — e.g., `LINK_yourname-abc123`

CHECK IF PAYMENT LINK IS PAID

GET https://famgateway.in/api/verify-order.php?api_key=YOUR_KEY&order_id=LINK_yourname-abc123

PAYMENT LINK URL FORMAT

https://famgateway.in/pay/your-custom-slug

📋 Create links from Dashboard: Go to Payment Links in your merchant dashboard to create and manage reusable payment links with custom slugs, amounts, and expiry times.

7

Webhook Signature Verification

When a payment succeeds, FamGateway sends a signed HTTP POST to your webhook endpoint. You must verify the signature to ensure the request genuinely came from us.

Header	Description
HTTP_X_FAMGATEWAY_SIGNATURE	HMAC SHA256 signature of the raw JSON body, signed using your `api_key`.

PHP WEBHOOK VERIFICATION EXAMPLE

<?php
$API_KEY = 'YOUR_API_KEY'; // Use your API key as the secret
$rawBody  = file_get_contents('php://input');
$sigHeader = $_SERVER['HTTP_X_FAMGATEWAY_SIGNATURE'] ?? '';

// Verify using HMAC SHA256
$expected = hash_hmac('sha256', $rawBody, $API_KEY);

if (!hash_equals($expected, $sigHeader)) {
    http_response_code(401);
    die('Invalid signature — request ignored.');
}

// Signature verified! Process the event.
$event = json_decode($rawBody, true);
if ($event['event'] === 'payment.success') {
    // Fulfill the order in your DB
    // $event['order_id'], $event['utr'], $event['amount']
    echo 'OK';
}

8

HTTP Status & Error Codes

All error responses follow a consistent JSON format: {"status": "error_type", "message": "Human-readable description"}

HTTP Code	Status Field	When it happens	Fix
401	`unauthorized`	Missing or invalid `api_key`	Check your API key in API Keys
403	`suspended`	Account banned by admin	Contact support
404	`not_found`	`order_id` does not exist or belongs to another user	Verify the order_id is correct
408	`expired`	5-minute payment window exceeded	Create a new order and show fresh QR
429	`error`	Rate limit exceeded (20 req/min per IP)	Slow down polling to every 5 seconds minimum
500	`error`	Gmail IMAP not connected or server error	Check Gmail connection in Dashboard

Building with ChatGPT, Claude, or Cursor?