{/* Header */}

Back to blog

UPI API Integration: The Complete Developer Guide

Integrating UPI payments should not take weeks. With the right API, it takes an afternoon. This guide walks you through the entire process, from creating orders to verifying webhooks securely.

{/* Content Body */}

Prerequisites

• API Key and Secret: Obtain these from your UPI Gateways dashboard. Keep the secret safe on your server.
• Webhook URL: An endpoint on your server ready to receive POST requests (e.g., `https://your-server.com/api/webhooks/upi`).
• **HTTPS Endpoint:** Webhooks must be delivered to an HTTPS-enabled server for security.

## Step 1: Create a Payment Order When a user clicks "Pay", your backend should initiate a payment order by calling the API. This ensures the payment parameters cannot be tampered with on the client side. Request (cURL) ``{`curl -X POST https://api.upigateways.in/v1/orders \\ -H "X-API-Key: ug_live_..." \\ -H "X-API-Secret: sk_live_..." \\ -H "Content-Type: application/json" \\ -d '{ "amount": "499.00", "order_id": "ORD-001", "customer_name": "Rahul K", "callback_url": "https://your-site.com/thanks" }'`}`` The API responds with the newly created order details, including the `pay_url`. Response (JSON) ``{`{ "status": "success", "data": { "order_id": "ORD-001", "upi_intent": "upi://pay?pa=merchant@bank&pn=Merchant&am=499.00", "pay_url": "https://pay.upigateways.in/ORD-001" } }`}`` ## Step 2: Redirect or Embed the Payment Page You can either use the `upi_intent` URL directly if you are building a native mobile app to open GPay/PhonePe automatically, or redirect the user to the `pay_url` where they will see a dynamically generated QR code (on desktop) or a "Pay Now" button (on mobile). ## Step 3: Handle the Webhook When the payment is successful, our servers will send a POST request to your configured webhook URL. **Always verify the signature** to prevent spoofing. Here is a Node.js/Express example: webhook.js ``{`const crypto = require('crypto'); const express = require('express'); const app = express(); app.post('/api/webhooks/upi', express.json(), (req, res) => { const payload = req.body; const signature = req.headers['x-upi-signature']; const secret = process.env.UPI_API_SECRET; const expectedSignature = crypto .createHmac('sha256', secret) .update(JSON.stringify(payload)) .digest('hex'); if (signature === expectedSignature) { if (payload.status === 'SUCCESS') { // Mark order as paid in DB console.log('Payment successful for', payload.order_id); } res.status(200).send('OK'); } else { res.status(401).send('Invalid signature'); } });`}`` ## Step 4: Verify Payment Status In addition to webhooks, you can manually poll the payment status before showing the success screen to the user. GET Request ``{`curl -X GET https://api.upigateways.in/v1/orders/ORD-001 \\ -H "X-API-Key: ug_live_..." \\ -H "X-API-Secret: sk_live_..."`}`` ## Error Codes Reference Error Code Meaning Action ERR_INVALID_AUTH API Key or Secret is incorrect Check your credentials ERR_AMOUNT_INVALID Amount format is invalid Ensure amount is passed as a string with 2 decimal places ERR_ORDER_EXISTS Order ID already used Generate a unique Order ID for every request ## SDK and Framework Examples Because our API is a standard REST interface, it works perfectly across any language or framework (Python/Django, PHP/Laravel, Go, Rust, Ruby). The underlying principle of creating an order via POST, redirecting the user, and listening for the webhook remains the same. ### Read the Full Documentation Explore all endpoints, parameters, and advanced features in our official API reference. `View API Docs`