Developer documentation

Integrate PAYFLUX into my existing application. Inspect its framework, authentication, products and order storage first; preserve its design and working features. Implement the integration, not just example snippets.

PAYFLUX BASE URL: https://payflux.rajnishcodex.shop
Keep a single merchant API key in the server environment as PAYFLUX_API_KEY. Never expose it in frontend JavaScript, an Android APK, logs, URLs or browser storage. No public/secret key pair is needed.

1. CREATE AN ORDER FROM MY SERVER
POST /api/public/v1/create-order
Headers: X-API-KEY: <server environment key>, Content-Type: application/json
JSON: amount (number > 0 and <= 200000), optional customer_email (valid email, <=255 characters), optional note (<=120 characters), optional expires_in_minutes (integer 1–60, default 5).
Calculate amount from my trusted product catalogue, never trust a browser-submitted price. Persist my internal purchase ID, authenticated customer ID, expected amount/currency and returned PAYFLUX order_id before returning a payment link.
Response: order_id, amount, currency='INR', status='PENDING', payment_url, checkout_url, verify_url, upi_uri, qr_code, pay_instructions, expires_at.
There is no idempotency-key contract. Do not automatically retry a timed-out creation request as if it were safe; reconcile an existing purchase first to prevent duplicate orders.

2. HOSTED PAYMENT SCREEN
Open the returned payment_url or checkout_url. The payment_url opens the hosted checkout in a browser. FamPay uses QR-only: customer enters the exact order amount; do not force a UPI intent for this provider. Paytm for Business supports QR and UPI intent. The receiver UPI address is not displayed as a copy control but remains encoded in payment payloads; this is not encryption or anonymity.

3. VERIFY WITHOUT A REQUIRED WEBHOOK
GET /api/payment/{order_id}?format=json requires no API key. Alternatively GET /api/public/payment/{order_id}?format=json uses the publication-safe public prefix.
Returns order_id, amount, currency, status, utr (string or null), paid_at, expires_at, payment_url. There is no is_paid property; check status === 'SUCCESS'.
For server-side fulfilment prefer GET /api/public/v1/check-status/{order_id} with X-API-KEY, which scopes the result to the merchant. Its response has order_id, amount, status, utr, paid_at, expires_at (no currency field).
Poll about every 3 seconds with one request in flight, bounded retries and a timeout. Stop on SUCCESS or FAILED; handle HTTP/network errors separately from unpaid status. FAILED includes an expired payment window. Do not require a customer to enter a UTR. An automatically detected UTR is a receipt reference, not user-supplied proof.

4. SECURE FULFILMENT
Only my server may grant access or mark my purchase paid. Confirm that the provider order_id belongs to the signed-in customer and merchant, the amount matches the stored expected amount, and status is SUCCESS. Use an atomic, idempotent state transition so repeated polls cannot deliver twice. Never trust a browser success alert, screenshot, query parameter or submitted UTR. A return from a UPI app does not prove payment.
Do not allow my status proxy to fetch arbitrary caller-supplied URLs: construct the fixed provider URL from the purchase's stored order ID.

5. OPTIONAL WEBHOOK
The current gateway sends payment.success notifications and retains the legacy X-ZapGateway-Event header for existing integrations. Do not invent a webhook signature scheme; re-check the order using the authenticated status endpoint before fulfilment. Polling works without a webhook, including a Telegram bot running in polling mode.

6. ERRORS AND LIMITATIONS
Handle 400 validation, 401 missing/invalid/revoked key, 404 unknown or non-owned order, 409 no merchant UPI configured, and unexpected 5xx without leaking credentials.
FamPay verification depends on valid Gmail authorization and receipt emails arriving. Matching by amount can be ambiguous for concurrent equal-value payments; do not promise collision-proof verification. Paytm's current status integration is unofficial: MID alone is not a guarantee of verification and must be tested with authorized business access. Do not invent PhonePe/BharatPe companion integration.

7. DELIVERABLES
Provide working server endpoints, purchase persistence, checkout link, pending/success/expired/error states, and setup instructions with environment variable names only. Add tests for server-calculated prices, ownership checks, mismatched amount, duplicate success notifications and network failures. Run available tests. Clearly state which live-payment checks need my real account and have not been performed. Do not claim production readiness without an end-to-end paid-order test.