API Documentation
Create UPI QR codes and verify FamPay payments from your bot or backend. All endpoints return JSON with a status of "success" or "error".
Authentication
Every request needs your API key. Get it from the dashboard. Send it as a header (recommended):
or as a query parameter for quick tests: ?key=YOUR_API_KEY
Base URL
Live playground
Try the API with your key right here.
POST/api/payment/generate
Creates a UPI QR code for a fixed amount that pays to your account's UPI ID. The QR is valid for 10 minutes.
Body
| Field | Type | Description |
|---|---|---|
| amountrequired | number | Amount in ₹, from 1 to 100000 |
Response
POST/api/payment/verify
Searches your connected Gmail for the payment confirmation email. Waits up to 30 seconds for the email to arrive. Each UTR can be verified only once.
Body
| Field | Type | Description |
|---|---|---|
| utrrequired | string | 12-digit UTR, or the FamPay transaction ID (FMPIB… or its 10 digits) |
| transaction_idoptional | string | The transaction_id from Generate QR. When sent, that QR is marked paid and the paid amount must match the QR amount. |
Response
transaction_id when you have it. Without it, any payment email with that UTR is accepted whatever its amount.GET/api/transaction/:id
Returns one of your transactions by its transaction_id. Use it to check whether a QR has been paid.
GET/api/transactions
Lists your transactions, newest first.
| Query | Type | Description |
|---|---|---|
| limitoptional | number | 1–200, default 50 |
POST/api/invoices
Creates a shareable payment link. Your customer opens it, pays by UPI, enters their UTR, and the invoice turns paid. No code needed on your side, or poll the invoice from your bot.
Body
| Field | Type | Description |
|---|---|---|
| amountrequired | number | ₹1 to ₹1,00,000 (paise allowed) |
| descriptionoptional | string | What the payment is for, max 200 characters |
| customer_nameoptional | string | Shown on the payment page, max 80 characters |
| expires_in_daysoptional | number | 1, 7 (default), 30, or 0 for never |
Response
Other invoice endpoints
| Endpoint | Description |
|---|---|
| GET /api/invoices | Your invoices, newest first. ?status=pending|paid|expired|cancelled, ?page= |
| GET /api/invoices/:id | One invoice: status, paid_amount, utr, paid_at |
| POST /api/invoices/:id/cancel | Stop a pending link from accepting payments |
paid_amount.Gmail connection
Payments are verified from the Gmail inbox that receives your FamPay emails. Connect it once from the dashboard, or through the API. There are two ways: a Gmail App Password (needs 2-Step Verification, works for any account) or Google sign-in.
| Endpoint | Description |
|---|---|
| POST /api/gmail/app-password | Body {"email": "you@gmail.com", "app_password": "abcd efgh ijkl mnop"}. We test the login first, then store the password encrypted. |
| GET /api/gmail/connect | Returns auth_url, the Google sign-in page. Add ?redirect=true to be redirected straight there. |
| GET /api/gmail/status | connected, method (imap or oauth) and the linked email |
| DELETE /api/gmail/disconnect | Unlinks Gmail from your account |
Errors
Errors return {"status": "error", "code": "…", "message": "…"}.
| Code | HTTP | Meaning |
|---|---|---|
| MISSING_API_KEY | 401 | No API key sent |
| INVALID_API_KEY | 401 | Key is wrong or was replaced |
| INVALID_AMOUNT | 400 | Amount missing or ≤ 0 |
| PAYMENT_NOT_FOUND | 404 | No matching payment email within 30 seconds |
| ALREADY_VERIFIED | 409 | This UTR or QR was already verified |
| AMOUNT_MISMATCH | 400 | Paid amount differs from the QR amount |
| TRANSACTION_EXPIRED | 410 | QR is older than 10 minutes |
| GMAIL_NOT_CONNECTED | 503 | Connect Gmail first |
| GMAIL_AUTH_EXPIRED | 503 | Gmail access expired or the App Password was revoked, reconnect it |
| IMAP_AUTH_FAILED | 400 | Gmail rejected the App Password |
| (rate limit) | 429 | Too many requests, slow down |