Authentication
All requests use JSON over HTTPS. Send your secret key in the X-API-Key header (or Authorization: Bearer). Get keys from Dashboard → API keys.
sk_test_ create simulated payments (the QR cannot receive real money). Keys starting with sk_live_ create real payments into your UPI accounts. Try it end to end in the live demo store.Integrate with AI (ChatGPT, Claude, Gemini)
Don't want to read the whole reference? Pick your stack, copy the prompt, and paste it into ChatGPT, Claude, Gemini, Cursor or Copilot. It already contains every endpoint, field, the webhook signature rule and test-mode tips for https://app.swiftupi.com, so the AI writes working code for your app — a food delivery app, a store, a booking site, anything.
AI tools can also read /llms.txt and the full plain-text reference at /llms-full.txt. Always review AI-written code before going live, and test with an sk_test_ key first.
SDKs
Download a ready-made client — no dependencies. Each one creates orders, reads status, records refunds and verifies webhooks.
require 'swiftupi.php';
$gw = new SwiftUPI('sk_live_xxx', 'https://app.swiftupi.com');
// 1. create the payment on your server
$order = $gw->createOrder(['amount' => '499.00', 'client_order_id' => 'order_1024',
'redirect_url' => 'https://yoursite.com/thanks']);
header('Location: ' . $order['payment_url']); // or open it as a popup with checkout.js
// 2. webhook.php — confirm the payment
$raw = file_get_contents('php://input');
if (!SwiftUPI::verifyWebhook($raw, $_SERVER['HTTP_X_GATEWAY_TIMESTAMP'] ?? '', $_SERVER['HTTP_X_GATEWAY_SIGNATURE'] ?? '', 'whsec_xxx')) {
http_response_code(400); exit;
}
$event = json_decode($raw, true);
if ($event['event'] === 'payment.success') { /* mark $event['data']['client_order_id'] as paid */ }
http_response_code(200);
const SwiftUPI = require('./swiftupi');
const gw = new SwiftUPI('sk_live_xxx', 'https://app.swiftupi.com');
const order = await gw.createOrder({ amount: '499.00', client_order_id: 'order_1024' });
res.redirect(order.payment_url);
app.post('/upi-webhook', express.raw({ type: 'application/json' }), (req, res) => {
if (!SwiftUPI.verifyWebhook(req.body.toString(), req.get('X-Gateway-Timestamp'), req.get('X-Gateway-Signature'), 'whsec_xxx')) return res.sendStatus(400);
const event = JSON.parse(req.body); // event.event === 'payment.success'
res.sendStatus(200);
});
from swiftupi import SwiftUPI
gw = SwiftUPI("sk_live_xxx", "https://app.swiftupi.com")
order = gw.create_order({"amount": "499.00", "client_order_id": "order_1024"})
return redirect(order["payment_url"])
@app.post("/upi-webhook")
def hook():
if not SwiftUPI.verify_webhook(request.get_data(as_text=True), request.headers.get("X-Gateway-Timestamp"),
request.headers.get("X-Gateway-Signature"), "whsec_xxx"):
return "", 400
event = request.get_json() # event["event"] == "payment.success"
return "", 200
curl -X POST https://app.swiftupi.com/api/orders \
-H "X-API-Key: sk_live_xxx" -H "Idempotency-Key: order_1024" \
-H "Content-Type: application/json" \
-d '{"amount":"499.00","client_order_id":"order_1024"}'
Plugins: WooCommerce & Shopify
- Download the plugin and upload it in WordPress → Plugins → Add New → Upload, then activate.
- Open WooCommerce → Settings → Payments → SwiftUPI UPI and paste your secret key and webhook secret.
- Copy the webhook URL shown there into Dashboard → Webhooks.
Customers choose “UPI” at checkout, pay on the SwiftUPI checkout (redirect or popup), and the order is marked Processing automatically with the UTR saved.
⬇ Download WooCommerce plugin (.zip)- In Shopify, add a manual payment method named
UPI (SwiftUPI)(Settings → Payments). - Create a custom app with the
read_ordersandwrite_ordersscopes and copy its Admin API token. - In Dashboard → Settings → Shopify, enter your shop domain and token. We show you the webhook URL and the order-status snippet to paste.
When a customer places an order with UPI, they get a pay button on the order status page (and by email). Once paid, the Shopify order is marked Paid automatically.
Connect Shopify →Using another platform (Laravel, OpenCart, WHMCS, a custom app)? Use the REST API or an SDK below — any language that can send an HTTPS request works.
OpenAPI specification
The full API is described in an OpenAPI 3 file. Import it into Postman, Insomnia or Swagger UI, or generate a client for Java, Go, C#, Dart and more.
# generate a client, e.g. for Java
npx @openapitools/openapi-generator-cli generate -i https://app.swiftupi.com/openapi.json -g java -o swiftupi-java
Create a payment
POST/api/orders
| Field | Type | Description |
|---|---|---|
amount * | string | Rupees with up to 2 decimals, e.g. "499.00". Max 1,00,000. |
client_order_id | string | Your order number (letters, digits, -, _; max 64). Idempotent — sending it again returns the same payment. |
note | string | Shown to the customer in their UPI app (max 50). |
redirect_url | string | Customer is sent here after payment, with ?order_id=…. Must match your allowed redirect domains if you set any. |
customer_name, customer_mobile, customer_email | string | Optional, shown in your dashboard. |
expiry_minutes | int | QR validity, 2–10080. Default 10. |
account_id | int | Force a specific UPI account. Omit to use your rotation setting. |
curl -X POST https://app.swiftupi.com/api/orders \
-H "X-API-Key: sk_live_xxx" -H "Content-Type: application/json" \
-d '{"amount":"499.00","client_order_id":"order_1024","redirect_url":"https://yoursite.com/thanks"}'
Response 201
{
"order_id": "ORD7F5A6A1878FA89CD",
"client_order_id": "order_1024",
"mode": "live",
"amount": "499.00",
"currency": "INR",
"status": "pending",
"payment_url": "https://app.swiftupi.com/pay/ORD7F5A6A1878FA89CD",
"qr_url": "https://app.swiftupi.com/qr/ORD7F5A6A1878FA89CD.svg",
"upi_intent": "upi://pay?pa=...&am=499.00&tr=ORD7F5A6A1878FA89CD...",
"expires_at": 1795000000, ...
}
Send the customer to payment_url (hosted checkout with QR and UPI app buttons), or render qr_url / upi_intent yourself.
Safe retries
Send an Idempotency-Key header (any unique string, e.g. your order number). Retrying with the same key returns the original payment instead of creating a new one.
Unique paise: on accounts with phone auto-verify, amount in the response can be a few paise more than you asked (₹450 → ₹450.56). That is the amount the customer pays, and it lets the payment be matched automatically. requested_amount is your original price.
Embedded checkout (popup on your site)
Create the order on your server, then open our checkout as a popup on your own page. On phones it slides up as a bottom sheet. After success, the popup closes on its own and your handler is called.
<script src="https://app.swiftupi.com/checkout.js"></script>
<!-- no-code: any element with data-swiftupi-order -->
<button data-swiftupi-order="ORD7F5A6A1878FA89CD" data-swiftupi-redirect="/thanks">Pay ₹499</button>
<script>
// or JavaScript
SwiftUPI({
order_id: "ORD7F5A6A1878FA89CD",
handler: function (r) { /* {order_id, status:"paid", amount, utr} */ },
onfailure: function (r) { /* {order_id, status: failed|expired|cancelled} */ },
modal: { ondismiss: function () { /* customer closed it */ } }
}).open();
window.addEventListener("swiftupi:paid", function (e) { console.log(e.detail); });
</script>
The browser callback is for user experience only. Always confirm the payment with the webhook or GET /api/orders/{id} before delivering.
Get a payment
GET/api/orders/{order_id or client_order_id}
Returns the same object. status is one of:
| Status | Meaning |
|---|---|
pending | Waiting for the customer to pay. |
review | Manual UPI account only: the customer submitted a UTR and the merchant must approve or reject it in the dashboard. |
paid | Captured. utr holds the bank reference. |
failed | The customer's payment attempt failed and the QR expired. See failure_reason. |
expired | No payment before expiry. |
cancelled | Cancelled from the dashboard. |
A payment made up to 30 minutes after expiry is still captured automatically, and its status changes from expired/failed to paid. Always treat the webhook or a fresh GET as the source of truth.
Refunds
POST/api/orders/{order_id}/refunds with {"amount":"50.00","reason":"…","reference":"UTR of your refund transfer"}
UPI refunds are sent by you from your own UPI app, because the money is in your account. This endpoint records the refund (full or partial), shows it in the dashboard and sends a payment.refunded webhook. GET the same URL to list refunds.
Webhooks
Set your endpoint in Dashboard → Webhooks. Events: payment.success, payment.failed, payment.review (customer submitted a UTR on a manual account), payment.refunded. Every delivery, along with your server's response, appears in Dashboard → Webhooks, where you can replay it. We retry with backoff for ~9 hours until you return HTTP 2xx.
POST https://yoursite.com/upi-webhook
X-Gateway-Timestamp: 1795000123
X-Gateway-Signature: 5f2c... (hex HMAC-SHA256)
{"event":"payment.success","mode":"live","data":{ ...payment object... }}
Verify the signature
# Python
import hmac, hashlib
expected = hmac.new(SECRET.encode(), f"{timestamp}.{raw_body}".encode(), hashlib.sha256).hexdigest()
valid = hmac.compare_digest(expected, signature)
// Node.js
const expected = crypto.createHmac('sha256', SECRET).update(`${timestamp}.${rawBody}`).digest('hex');
const valid = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
// PHP
$valid = hash_equals(hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret), $signature);
Reject events whose timestamp is more than 5 minutes old, and make your handler idempotent (the same event can arrive twice).
Errors
| HTTP | Meaning |
|---|---|
| 401 | Missing or invalid API key |
| 403 | Account suspended, or live key used before approval |
| 404 | Payment not found (or belongs to another mode) |
| 422 | Validation error — see error |
| 429 | Rate limit (300 requests/minute per merchant) |
{"error": "amount must be a positive number with max 2 decimals"}