Official API Docs v1.0Bank UTR Idempotency Active

Developer Documentation & API Reference

FamFlow By </> Zyrex · Direct 0% P2P Settlement Engine

Integrate zero-fee automated peer-to-peer UPI payment verification into your website, store, Telegram Bot, or SaaS in under 5 minutes with real-time IMAP mail scraping and bank-grade idempotency locks.

1. Overview & Architecture

FamFlow is a 100% free non-custodial UPI verification gateway. Unlike aggregators that hold merchant funds in escrow and charge 2–3% transaction fees, FamFlow routes payments directly into your personal FamPay UPI ID and verifies settlements via automated IMAP confirmation inspection and Bank UTR locking.

0% Commission

Keep 100% of your earnings forever with zero decimal adjustments.

Dual Verification

Verify via 12-digit Bank UTR or unique embedded Order ID note.

24h Expiry Support

Create links that stay valid from 5 minutes up to 7 days.

2. Authentication

All merchant API requests require your private API key passed via the standard HTTP Authorization header:

Authorization: Bearer fam_8a752bce3d47058f3554d23d4e73d679a1b4

POST

/api/create-order

Dispatches a new order session with a dynamic vector QR code, customer note, and custom expiration window.

Field	Type	Required	Description
amount	Number	Yes	Payment amount in INR (e.g. 499.00)
expiry_minutes	Number	Optional	Order validity in minutes. Default: 5, Max: 10080 (7 days)
redirect_url	String	Optional	URL to redirect the customer upon payment completion
customer_name	String	Optional	Buyer's name or username

curl Request Example

curl -X POST https://famflow.cyou/api/create-order \
  -H "Authorization: Bearer fam_8a752bce3d47058f..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 499.00,
    "expiry_minutes": 1440,
    "redirect_url": "https://your-store.com/checkout/success"
  }'

Example Response (200 OK):

{
  "status": "success",
  "order_id": "fg_WZ4F5TGO",
  "amount": 499.00,
  "currency": "INR",
  "checkout_url": "https://famflow.cyou/pay/fg_WZ4F5TGO",
  "upi_uri": "upi://pay?pa=rapidfirezyrex.gogoi@fam&pn=Store&am=499.00&cu=INR&tn=fg_WZ4F5TGO",
  "customer_note": "WZ4F5TGO",
  "expires_at": 1756559772,
  "expires_in_seconds": 86400
}

POST

/api/verify-order

Verifies whether a payment was completed. Supports automatic verification via Gmail IMAP receipt scanning, exact 12-digit Bank UTR idempotency locking, and Order ID note verification.

cURL Request Example

curl -X POST https://famflow.cyou/api/verify-order \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "fg_WZ4F5TGO",
    "utr": "614791407763"
  }'

Example Success Response (200 OK):

{
  "verified": true,
  "order_id": "fg_WZ4F5TGO",
  "amount": 499.00,
  "utr": "614791407763",
  "txn_id": "FMPIB6672406744",
  "verified_via": "bank_utr",
  "message": "Payment verified & captured successfully via Bank UTR Idempotency"
}

GET

/api/order-status

Query the current real-time state of an order: PENDING, CAPTURED, or EXPIRED.

GET /api/order-status?id=fg_WZ4F5TGO

6. Anti-Collision & Replay Prevention Mechanism

When multiple customers pay identical amounts (e.g. two separate users buying a ₹499 item simultaneously), FamFlow prevents collisions through three distinct defensive layers:

Layer 1: Unique Embedded Order ID Note (&tn=fg_...)

Every dynamic UPI QR embeds a unique transaction note. When FamPay dispatches the receipt email, the note is echoed back (e.g. Note: fgWZ4F5TGO). FamFlow matches the exact note to the pending order.

Layer 2: Atomic Bank UTR Idempotency Locking

Each 12-digit Bank Reference Number (UTR / RRN) can only ever be claimed once across the entire system. Once claimed by Order #1, any subsequent verification attempts with the same UTR return 409 Conflict.

Layer 3: Timestamp Window & Debit Protection

FamFlow extracts email timestamps to reject historical receipts predating the order. It also filters out debits ("You paid...") and updated wallet balances so outgoing expenses are never treated as incoming customer payments.

7. HMAC-SHA256 Webhook Signatures

When a payment is captured, FamFlow sends an HTTP POST request to all active webhook endpoints. The request includes the X-FamFlow-Signature header containing the HMAC-SHA256 signature generated with your merchant API Secret.

Node.js Webhook Verification

const crypto = require('crypto');

function verifyFamFlowWebhook(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
}

8. Standard Error Codes

Status Code	Error Code	Meaning & Resolution
400 Bad Request	INVALID_AMOUNT	Order amount must be greater than ₹0.00.
401 Unauthorized	INVALID_API_KEY	Check that your Bearer API key matches your FamFlow dashboard.
404 Not Found	ORDER_NOT_FOUND	The requested Order ID does not exist in the database.
409 Conflict	UTR_ALREADY_CLAIMED	Double-spend blocked. This 12-digit UTR was already attributed to another order.
410 Gone	ORDER_EXPIRED	Order passed its expiration window. Recoverable by submitting the 12-digit UTR.