# SwiftUPI API — full reference for AI assistants Base URL: https://app.swiftupi.com Format: JSON over HTTPS. Amounts are strings in rupees with up to 2 decimals ("499.00"). Machine-readable spec: https://app.swiftupi.com/openapi.json ## How a payment works 1. Your SERVER creates a payment: `POST /api/orders` with your secret key. 2. The customer pays on the hosted checkout (`payment_url`), in a popup on your page (checkout.js), or directly in their UPI app (`upi_intent`). 3. SwiftUPI confirms the payment (Paytm / PhonePe status APIs, bank SMS, bank email or merchant review) and sends a signed webhook `payment.success` to your server. 4. Your server verifies the webhook signature and marks the order paid. The webhook (or `GET /api/orders/{id}`) is the source of truth — never the browser. Money always settles to the merchant's own UPI account. SwiftUPI never holds funds. ## Authentication - Header `X-API-Key: ` (or `Authorization: Bearer `). - `sk_test_…` keys: simulated payments. The checkout shows "Payment succeeds" / "Payment fails" buttons; the QR cannot receive real money. Webhooks fire with `"mode": "test"`. - `sk_live_…` keys: real payments. Available after the merchant account is approved. - Keep keys on the server (environment variables). Never put them in browser code or mobile apps. ## POST /api/orders — create a payment Headers: `X-API-Key`, `Content-Type: application/json`, optional `Idempotency-Key: ` (retrying with the same key returns the same payment). | Field | Type | Notes | |---|---|---| | amount | string, required | Rupees, e.g. "499.00". Max 1,00,000 per payment (plan limits may apply). | | client_order_id | string | Your order id. Letters, digits, `-`, `_`; max 64. Sending the same value again returns the existing payment. | | note | string | Max 50 characters. Shown in the customer's UPI app. | | redirect_url | string | Full http(s) URL. Customer is sent here after paying, with `?order_id=…` appended. Must match the merchant's allowed redirect domains if set. | | customer_name, customer_mobile, customer_email | string | Optional; shown in the merchant dashboard. | | expiry_minutes | int | 2–10080. Default 10. | | account_id | int | Force a specific merchant UPI account. | Response `201 Created` (or `200` if it already existed): ```json { "order_id": "ORD7F5A6A1878FA89CD", "client_order_id": "order_1024", "mode": "live", "amount": "499.00", "requested_amount": "499.00", "refunded_amount": "0.00", "currency": "INR", "status": "pending", "method": "upi", "utr": null, "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, "customer": {"name": null, "mobile": null, "email": null} } ``` Unique paise: on some merchant accounts `amount` is a few paise above the requested price (₹450 → ₹450.56) so the payment can be matched automatically. Show/charge `amount`; compare `requested_amount` with your own price. ## GET /api/orders/{order_id or client_order_id} — get a payment Same object as above. `status` values: - `pending` — waiting for the customer - `review` — customer submitted a UTR; merchant must approve or reject - `cash` — customer chose cash at counter (4-digit code shown) - `cod` — cash on delivery, not yet collected - `paid` — captured; `utr` holds the bank reference - `failed` — payment attempt failed and the QR expired (`failure_reason`) - `expired` — no payment before expiry - `cancelled` — cancelled by the merchant A payment made up to 30 minutes after expiry is still captured and moves to `paid`. ## POST /api/orders/{order_id}/refunds — record a refund Body: `{"amount": "50.00", "reason": "…", "reference": "UTR of the refund you sent"}`. UPI refunds are sent by the merchant from their own UPI app (the money is in their account); this records it and sends `payment.refunded`. `GET` the same URL lists refunds. ## GET /api/orders/{order_id}/status — public status (no key) Used by the checkout page. Returns `{status, expires_at, method, receipt}`. ## GET /api/me Returns `{merchant, status, mode}` — use it to check a key. ## Webhooks Configure the URL in the dashboard → Webhooks. Events: `payment.success`, `payment.failed`, `payment.review`, `payment.refunded`. ``` POST https://merchant.example.com/upi-webhook Content-Type: application/json X-Gateway-Timestamp: 1795000123 X-Gateway-Signature: 5f2c… (hex) {"event":"payment.success","mode":"live","data":{ …payment object… }} ``` Signature: `hex(HMAC_SHA256(webhook_secret, timestamp + "." + raw_body))`. Rules: - Verify against the RAW request body bytes, before any JSON parsing or re-serialisation. - Use a constant-time comparison (`hmac.compare_digest`, `crypto.timingSafeEqual`, `hash_equals`). - Reject timestamps older than 5 minutes. - Respond 2xx quickly. Non-2xx responses are retried with backoff for about 9 hours. - Be idempotent: the same event can be delivered more than once. - On `payment.success`: look up your order by `data.client_order_id`, check `data.requested_amount` and `data.mode`, then mark it paid and store `data.utr`. Examples: ```python import hmac, hashlib expected = hmac.new(SECRET.encode(), f"{timestamp}.{raw_body}".encode(), hashlib.sha256).hexdigest() valid = hmac.compare_digest(expected, signature) ``` ```js const expected = crypto.createHmac('sha256', SECRET).update(`${timestamp}.${rawBody}`).digest('hex'); const valid = expected.length === signature.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature)); ``` ```php $valid = hash_equals(hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret), $signature); ``` ## Popup checkout (websites) ```html ``` On phones it opens as a bottom sheet. The browser callback is for UX only. ## Mobile apps Create the order on your backend. In the app, open `upi_intent` to jump into the customer's UPI app (Android `Intent.ACTION_VIEW`, Flutter `url_launcher`, React Native `Linking.openURL`), or open `payment_url` in an in-app browser. When the app resumes, ask your backend for the status. ## SDKs - PHP: https://app.swiftupi.com/sdk/swiftupi.php — `$gw = new SwiftUPI($key, 'https://app.swiftupi.com'); $gw->createOrder([...]); SwiftUPI::verifyWebhook($raw, $ts, $sig, $secret);` - Node.js: https://app.swiftupi.com/sdk/swiftupi.js — `new SwiftUPI(key, base).createOrder({...}); SwiftUPI.verifyWebhook(body, ts, sig, secret)` - Python: https://app.swiftupi.com/sdk/swiftupi.py — `SwiftUPI(key, base).create_order({...}); SwiftUPI.verify_webhook(body, ts, sig, secret)` - WooCommerce: https://app.swiftupi.com/plugins/swiftupi-woocommerce.zip - Shopify: no code — dashboard → Settings → Shopify. ## Errors `{"error": "message"}` with HTTP 401 (bad key), 403 (suspended / live key before approval), 404 (not found or other mode), 422 (validation), 429 (rate limit: 300 requests/minute per merchant). ## Checklist for an integration - [ ] Order created on the server with `client_order_id` and `Idempotency-Key` - [ ] Customer sent to `payment_url` / popup / `upi_intent` - [ ] Webhook endpoint verifies the signature on the raw body and is idempotent - [ ] Order marked paid only from the webhook or a server-side `GET /api/orders/{id}` - [ ] Keys in environment variables; tested end to end with an `sk_test_` key