Developer Ledger · API Reference

UREST API Documentation

Integrate automated UPI checkout, callbacks, and webhooks.

Introduction

v2.0 REST API

Welcome to the UPIFlow Developer Reference. A simple REST API layer for automated UPI payment collection & callbacks.

Developer Credentials

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:

HeaderValue
X-API-Keyor X-Guru-Key
X-API-Secret
Content-Typeapplication/json

Only call the API from your server. Never put X-API-Secret in browser or mobile-app code.

Base Endpoint URL

BASE URL

Create Payment Order

POST

Initiates a new payment order for a customer and returns checkout URLs, raw UPI intent deep links, and dynamic QR data.

POST

Request Parameters (JSON Body)

ParameterTypePresenceDescription
order_idstringRequiredYour unique merchant order or invoice ID. Max 64 chars.
amountfloat / numberRequiredAmount in INR (e.g. 100.00, minimum 1.00).
customer_namestringOptionalCustomer's full name.
customer_mobilestringOptionalCustomer's 10-digit mobile number for SMS/receipt notifications.
customer_emailstring (email)OptionalCustomer email for transaction receipts.
callback_urlstring (url)OptionalCustomer return redirect URL after payment completes.
descriptionstringOptionalBrief order description or item summary.

JSON Success Response (HTTP 200)

Error Responses

HTTPMeaningWhat to do
400Missing or invalid field (e.g. amount < 1.00)Check the details field in the response.
401Invalid or missing API Key / SecretVerify headers; regenerate keys in the dashboard if needed.
409Duplicate order_idUse a new unique order ID per attempt.
429Plan order limit or rate limit reachedRetry later or upgrade your plan.
5xxTemporary server / provider issueRetry with back-off; status is safe to re-check.

Check Order Status

POST / GET

Poll order status by your merchant order_id or payment token.

POST

Success Status Response (Paid)

Possible status values

successpendingfailedexpired

Direct Dynamic QR & Mobile UPI Intent API

Custom White-Label

Don'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.

No-Redirect White-Label Embed

How it Works:

  1. Call POST from your backend.
  2. Show qr_image_url inside an <img> tag on your website.
  3. On mobile browsers, link a "Pay via UPI App" button to upi_intent to open UPI apps instantly.
  4. 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 Global

Accept international payments in USDT, BTC and other cryptocurrency via Binance Pay.

POST

Automated Webhook System

HMAC-SHA256 Signed

When a payment is completed or confirmed, UPIFlow sends an asynchronous server-to-server HTTP POST request to your configured Webhook URL.

Incoming Webhook Headers

HeaderSample ValueDescription
X-Webhook-Signaturee9b6a87b1c3…HMAC-SHA256 signature (hex) of the raw request body, using your Webhook Secret.
X-Eventpayment.successEvent name (payment.success or payment.failed).
Content-Typeapplication/jsonPayload is serialized as UTF-8 JSON.

Incoming Webhook Payload Example:

Webhook best practices
  • 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_id hasn't already been marked paid.
  • Check that amount matches the order in your database.
  • Reply HTTP 200 quickly; 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 Providers

For hosting and cloud providers running WHMCS billing systems.

  1. Upload modules/gateways/upiflow.php into your WHMCS root directory.
  2. Configure Gateway credentials: Setup → Payments → Payment Gateways → Activate UPIFlow.
  3. Paste your API Key () and API Secret.
  4. WHMCS invoice links will now redirect to UPIFlow instant QR payments!

WordPress / WooCommerce Plugin

Ready-to-Install

Download our official WooCommerce UPI QR Code Payment Gateway plugin. Install in 1 click to collect payments with instant automated order status updates.

Official WooCommerce Plugin (ZIP)

Supports WooCommerce 7.x, 8.x, 9.x+ & WordPress 6.x. Auto-reconcile enabled.

Download Plugin (.ZIP)

Installation Steps:

  1. Download the .zip file using the button above.
  2. Go to your WordPress Admin Panel → Plugins → Add New → Upload Plugin.
  3. Select the zip file and click Install Now → Activate Plugin.
  4. Go to WooCommerce → Settings → Payments → UPIFlow.
  5. Enter your API Key () and API Secret, then click Save!

Shopify Integration

Step-by-step instructions to add UPIFlow to your Shopify store checkout.

  1. In your Shopify Admin, navigate to Settings → Payments.
  2. Under Manual Payment Methods, click Add manual payment method → Custom Payment Method.
  3. Set the Name to: UPI Instant QR (GooglePay / PhonePe / Paytm).
  4. 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.
  5. For automated checkout, configure a Shopify Webhook (Order Creation) calling your backend script, which calls POST .

Universal AI Integration Master Prompt

ChatGPT · Claude · Cursor · Windsurf

Copy 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.

Pre-configured with your credentials: