UREST API Documentation
Integrate automated UPI checkout, callbacks, and webhooks.
Introduction
v2.0 REST APIWelcome to the UPIFlow Developer Reference. A simple REST API layer for automated UPI payment collection & callbacks.
Welcome Merchant! Your active keys & webhook secret are pre-populated in every example on this page.
Authentication
Pass these HTTP headers with every API request:
| Header | Value | |
|---|---|---|
X-API-Keyor X-Guru-Key | | |
X-API-Secret | | |
Content-Type | application/json |
Only call the API from your server. Never put X-API-Secret in browser or mobile-app code.
Base Endpoint URL
Create Payment Order
POSTInitiates a new payment order for a customer and returns checkout URLs, raw UPI intent deep links, and dynamic QR data.
Request Parameters (JSON Body)
| Parameter | Type | Presence | Description |
|---|---|---|---|
order_id | string | Required | Your unique merchant order or invoice ID. Max 64 chars. |
amount | float / number | Required | Amount in INR (e.g. 100.00, minimum 1.00). |
customer_name | string | Optional | Customer's full name. |
customer_mobile | string | Optional | Customer's 10-digit mobile number for SMS/receipt notifications. |
customer_email | string (email) | Optional | Customer email for transaction receipts. |
callback_url | string (url) | Optional | Customer return redirect URL after payment completes. |
description | string | Optional | Brief order description or item summary. |
JSON Success Response (HTTP 200)
Error Responses
| HTTP | Meaning | What to do |
|---|---|---|
| 400 | Missing or invalid field (e.g. amount < 1.00) | Check the details field in the response. |
| 401 | Invalid or missing API Key / Secret | Verify headers; regenerate keys in the dashboard if needed. |
| 409 | Duplicate order_id | Use a new unique order ID per attempt. |
| 429 | Plan order limit or rate limit reached | Retry later or upgrade your plan. |
| 5xx | Temporary server / provider issue | Retry with back-off; status is safe to re-check. |
Check Order Status
POST / GETPoll order status by your merchant order_id or payment token.
Success Status Response (Paid)
Possible status values
Direct Dynamic QR & Mobile UPI Intent API
Custom White-LabelDon't want customers to leave your website or mobile app? Render our dynamic QR image inside your own modal, or open PhonePe / Google Pay / Paytm directly using the raw upi_intent string.
How it Works:
- Call
POSTfrom your backend. - Show
qr_image_urlinside an<img>tag on your website. - On mobile browsers, link a "Pay via UPI App" button to
upi_intentto open UPI apps instantly. - Poll
POST(through your backend) or listen to the Webhook to detect payment completion.
Simple HTML Modal Embed Example:
Binance Pay & Global Crypto Checkout
USDT / BTC / ETH GlobalAccept international payments in USDT, BTC and other cryptocurrency via Binance Pay.
Automated Webhook System
HMAC-SHA256 SignedWhen a payment is completed or confirmed, UPIFlow sends an asynchronous server-to-server HTTP POST request to your configured Webhook URL.
Incoming Webhook Headers
| Header | Sample Value | Description |
|---|---|---|
X-Webhook-Signature | e9b6a87b1c3… | HMAC-SHA256 signature (hex) of the raw request body, using your Webhook Secret. |
X-Event | payment.success | Event name (payment.success or payment.failed). |
Content-Type | application/json | Payload is serialized as UTF-8 JSON. |
Incoming Webhook Payload Example:
- Verify the signature on the raw body, before parsing JSON.
- Compare signatures with a constant-time function (
hash_equals,timingSafeEqual,compare_digest). - Make the handler idempotent: the same event can arrive more than once. Check the
utr/order_idhasn't already been marked paid. - Check that
amountmatches the order in your database. - Reply
HTTP 200quickly; do slow work (emails etc.) afterwards.
Callbacks & Webhook Verification (PHP)
Always verify the X-Webhook-Signature header before crediting users or updating your orders to protect against spoofing.
PHP Integration (Create Order & Redirect)
Server-side checkout for Core PHP and Laravel controllers.
Node.js / Express Webhook Verification
Verify signatures in Node.js applications with crypto and Express raw bodies.
Python (FastAPI / Flask) Webhook Verification
Verify signatures and accept payment notifications in Python backends.
WHMCS Payment Gateway Module
Hosting ProvidersFor hosting and cloud providers running WHMCS billing systems.
- Upload
modules/gateways/upiflow.phpinto your WHMCS root directory. - Configure Gateway credentials: Setup → Payments → Payment Gateways → Activate UPIFlow.
- Paste your API Key (
) and API Secret. - WHMCS invoice links will now redirect to UPIFlow instant QR payments!
WordPress / WooCommerce Plugin
Ready-to-InstallDownload our official WooCommerce UPI QR Code Payment Gateway plugin. Install in 1 click to collect payments with instant automated order status updates.
Supports WooCommerce 7.x, 8.x, 9.x+ & WordPress 6.x. Auto-reconcile enabled.
Installation Steps:
- Download the
.zipfile using the button above. - Go to your WordPress Admin Panel → Plugins → Add New → Upload Plugin.
- Select the zip file and click Install Now → Activate Plugin.
- Go to WooCommerce → Settings → Payments → UPIFlow.
- Enter your API Key (
) and API Secret, then click Save!
Shopify Integration
Step-by-step instructions to add UPIFlow to your Shopify store checkout.
- In your Shopify Admin, navigate to Settings → Payments.
- Under Manual Payment Methods, click Add manual payment method → Custom Payment Method.
- Set the Name to:
UPI Instant QR (GooglePay / PhonePe / Paytm). - In the instructions box, paste your dynamic checkout link or QR page instruction:
Please scan the UPI QR code or pay to our verified UPI ID. Your order will be confirmed immediately once payment is completed.
- For automated checkout, configure a Shopify Webhook (Order Creation) calling your backend script, which calls
POST.
Universal AI Integration Master Prompt
ChatGPT · Claude · Cursor · WindsurfCopy this master prompt and paste it into ChatGPT, Claude, Cursor, Copilot, or Windsurf. The AI will inspect your repository and integrate UPIFlow into any language or framework (Next.js, Laravel, Django, Express, Flutter, Go, etc.) without breaking existing code.