<developer docs>

Build with the SwiftUPI API

Create UPI payments from any language, get signed webhooks when they're paid, or drop in a plugin. Test keys (sk_test_) never move real money.

Base URL: https://app.swiftupi.com

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.

Test vs live: keys starting with 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);

Plugins: WooCommerce & Shopify

Woo
WooCommerceWordPress plugin
  1. Download the plugin and upload it in WordPress → Plugins → Add New → Upload, then activate.
  2. Open WooCommerce → Settings → Payments → SwiftUPI UPI and paste your secret key and webhook secret.
  3. 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)
S
ShopifyConnector — no app review needed
  1. In Shopify, add a manual payment method named UPI (SwiftUPI) (Settings → Payments).
  2. Create a custom app with the read_orders and write_orders scopes and copy its Admin API token.
  3. 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

FieldTypeDescription
amount *stringRupees with up to 2 decimals, e.g. "499.00". Max 1,00,000.
client_order_idstringYour order number (letters, digits, -, _; max 64). Idempotent — sending it again returns the same payment.
notestringShown to the customer in their UPI app (max 50).
redirect_urlstringCustomer is sent here after payment, with ?order_id=…. Must match your allowed redirect domains if you set any.
customer_name, customer_mobile, customer_emailstringOptional, shown in your dashboard.
expiry_minutesintQR validity, 2–10080. Default 10.
account_idintForce 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.

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:

StatusMeaning
pendingWaiting for the customer to pay.
reviewManual UPI account only: the customer submitted a UTR and the merchant must approve or reject it in the dashboard.
paidCaptured. utr holds the bank reference.
failedThe customer's payment attempt failed and the QR expired. See failure_reason.
expiredNo payment before expiry.
cancelledCancelled 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

HTTPMeaning
401Missing or invalid API key
403Account suspended, or live key used before approval
404Payment not found (or belongs to another mode)
422Validation error — see error
429Rate limit (300 requests/minute per merchant)
{"error": "amount must be a positive number with max 2 decimals"}