SMB UPI API Reference

Welcome to the SMB UPI REST API documentation. SMB UPI provides a lightweight, robust UPI-focused payment gateway engine that detects actual QR payments directly to your own merchant account.

Using our APIs, you can easily create checkout orders, generate dynamic payment landing links, redirect customers, verify transactions instantly, and receive real-time webhook status updates once they finish paying.

Authentication

All REST API endpoints require secure authentication headers. Your credentials consist of a live public Key and a secret Key which you must generate inside your API Settings page.

Include the keys as custom HTTP headers with every request:

Production API

SMB UPI operates in production mode only. Every created checkout can accept a real payment through the merchant account connected to the payment-link owner.

Keep API secrets server-side and use a small-value order when validating a new integration. The base endpoint is:

https://smbupi.com/api

Create Order

Creates a transaction order in our database and returns a unique, secure `payment_url`. Redirect your customer to this URL to trigger the checkout flow.

Request Body Parameters

curl -X POST https://smbupi.com/api/create-order \
  -H "X-API-Key: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "order_id": "ORD_20261110_2242",
    "customer_name": "Raushan Kumar",
    "description": "Order simulation purchase",
    "callback_url": "https://yourwebsite.com/callback.php"
  }'

<?php
$payload = [
    'amount' => '100.00',
    'order_id' => 'ORD_20261110_2242',
    'customer_name' => 'Raushan Kumar',
    'description' => 'Order simulation purchase',
    'callback_url' => 'https://yourwebsite.com/callback.php'
];

$ch = curl_init('https://smbupi.com/api/create-order');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-API-Key: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx',
        'X-API-Secret: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx'
    ]
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
unset($ch);

if (isset($data['status']) && $data['status'] === 'success') {
    $checkoutUrl = $data['data']['payment_url'];
    // Redirect customer to $checkoutUrl
    header("Location: " . $checkoutUrl);
    exit;
} else {
    echo "Error creating order: " . ($data['error'] ?? 'Unknown error');
}
?>

const fetch = require('node-fetch');

const payload = {
  amount: '100.00',
  order_id: 'ORD_20261110_2242',
  customer_name: 'Raushan Kumar',
  description: 'Order simulation purchase',
  callback_url: 'https://yourwebsite.com/callback.php'
};

fetch('https://smbupi.com/api/create-order', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'pi_live_xxxxxxxxxxxxxxxxxxxxxxxx',
    'X-API-Secret': 'sk_live_xxxxxxxxxxxxxxxxxxxxxxxx'
  },
  body: JSON.stringify(payload)
})
.then(res => res.json())
.then(json => {
  if (json.status === 'success') {
    console.log('Redirect URL:', json.data.payment_url);
  } else {
    console.error('API Error:', json.error);
  }
})
.catch(err => console.error(err));

import requests

payload = {
    "amount": "100.00",
    "order_id": "ORD_20261110_2242",
    "customer_name": "Raushan Kumar",
    "description": "Order simulation purchase",
    "callback_url": "https://yourwebsite.com/callback.php"
}

headers = {
    "Content-Type": "application/json",
    "X-API-Key": "pi_live_xxxxxxxxxxxxxxxxxxxxxxxx",
    "X-API-Secret": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
}

response = requests.post("https://smbupi.com/api/create-order", json=payload, headers=headers)
data = response.json()

if data.get("status") == "success":
    print("Redirect user to:", data["data"]["payment_url"])
else:
    print("Error:", data.get("error"))

Success Response Schema (201 Created)

{
  "status": "success",
  "message": "Order created successfully",
  "data": {
    "payment_url": "https://smbupi.com/pay/LRd7jTFOV2sFyhMyOBzbJLL1SQzMxe5V",
    "order_id": "ORD_20261110_2242",
    "token": "LRd7jTFOV2sFyhMyOBzbJLL1SQzMxe5V",
    "amount": 100.00,
    "currency": "INR",
    "customer_name": "Raushan Kumar",
    "expires_at": "2026-06-06 11:15:30",
    "created_at": "2026-06-05 11:15:30"
  }
}

Check Status

Retrieves the details and verification status of a transaction using your unique `order_id` reference.

Request Body Parameters

curl -X POST https://smbupi.com/api/check-status \
  -H "X-API-Key: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ORD_20261110_2242"
  }'

<?php
$payload = [
    'order_id' => 'ORD_20261110_2242'
];

$ch = curl_init('https://smbupi.com/api/check-status');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-API-Key: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx',
        'X-API-Secret: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx'
    ]
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
unset($ch);

if (isset($data['status']) && $data['status'] === 'success') {
    $paymentStatus = $data['data']['payment_status']; // 'success', 'pending', or 'failed'
    echo "Transaction Status: " . strtoupper($paymentStatus);
} else {
    echo "Error checking status: " . ($data['error'] ?? 'Unknown error');
}
?>

const fetch = require('node-fetch');

fetch('https://smbupi.com/api/check-status', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'pi_live_xxxxxxxxxxxxxxxxxxxxxxxx',
    'X-API-Secret': 'sk_live_xxxxxxxxxxxxxxxxxxxxxxxx'
  },
  body: JSON.stringify({ order_id: 'ORD_20261110_2242' })
})
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));

Success Response Schema (200 OK)

{
  "status": "success",
  "data": {
    "order_id": "ORD_20261110_2242",
    "amount": 100.00,
    "currency": "INR",
    "payment_status": "success",
    "customer_name": "Raushan Kumar",
    "customer_mobile": "9999999999",
    "utr": "615372849102",
    "payment_method": "UPI QR",
    "provider": "paytm",
    "gateway_txn_id": "TXN_9201938561",
    "paid_at": "2026-06-05 11:16:45",
    "payment_url": "https://smbupi.com/pay/LRd7jTFOV2sFyhMyOBzbJLL1SQzMxe5V",
    "callback_url": "https://yourwebsite.com/callback.php",
    "expires_at": "2026-06-06 11:15:30",
    "created_at": "2026-06-05 11:15:30"
  }
}

Webhooks

Webhooks are used to receive real-time updates directly on your server whenever a transaction is completed successfully. Instead of polling our check status API, we will send an asynchronous HTTP POST request to your configured webhook URL.

You can manage and add webhooks in your Webhooks Portal.

Signature Validation

To ensure webhook payloads are authentically generated by SMB UPI, every webhook request contains a custom header named `X-Signature`.

This signature represents the HMAC-SHA256 hash of the raw POST body payload, signed using your unique **Webhook Secret Key**.

Sample PHP Webhook Receiver & Verification

<?php
// Retrieve the signature header
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? $_SERVER['HTTP_X_PAYINDIA_SIGNATURE'] ?? '';

// Get Webhook Secret from your settings
$webhookSecret = "your_webhook_secret_key";

// Read raw POST body payload
$payload = file_get_contents('php://input');

// Calculate expected signature
$expectedSignature = hash_hmac('sha256', $payload, $webhookSecret);

// Verify match
if (hash_equals($expectedSignature, $signature)) {
    // Valid request! Parse JSON
    $data = json_decode($payload, true);
    $orderId = $data['order_id'];
    $amount = $data['amount'];
    $utr = $data['utr'];
    $status = $data['status']; // 'success'
    
    if ($data['event'] === 'payment.success') {
        // 1. Mark order as Paid in your database
        // 2. Deliver goods to customer
    }
    
    // Respond with 200 OK to acknowledge receipt
    http_response_code(200);
    echo json_encode(['received' => true]);
} else {
    // Invalid signature, ignore/fail
    http_response_code(400);
    echo "Invalid signature";
}
?>

Callbacks & Redirect

If you passed a `callback_url` when creating the order, SMB UPI will automatically redirect your customer's browser to this URL immediately after a successful checkout verification.

When redirecting, we append key transaction details as URL query parameters:

https://yourwebsite.com/callback.php?status=success&order_id=ORD_20261110_2242&amount=100.00&utr=615372849102

PHP Integration Flow

Here is a complete, step-by-step implementation showcasing how to create a payment checkout, redirect the user, and process the callback securely.

<?php
/**
 * Step 1: Initialize Payment Order
 */
function initiatePayment($orderId, $amount, $customerName) {
    $apiKey = "pi_live_xxxxxxxxxxxxxxxxxxxxxxxx";
    $apiSecret = "sk_live_xxxxxxxxxxxxxxxxxxxxxxxx";
    
    $payload = [
        'amount' => number_format($amount, 2, '.', ''),
        'order_id' => $orderId,
        'customer_name' => $customerName,
        'callback_url' => 'http://' . $_SERVER['HTTP_HOST'] . $_SERVER['PHP_SELF'] . '?action=callback'
    ];

    $ch = curl_init('https://smbupi.com/api/create-order');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => json_encode($payload),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Content-Type: application/json',
            'X-API-Key: ' . $apiKey,
            'X-API-Secret: ' . $apiSecret
        ]
    ]);

    $response = curl_exec($ch);
    $data = json_decode($response, true);
    unset($ch);

    if (isset($data['status']) && $data['status'] === 'success') {
        // Redirect customer to PayIndia payment card
        header("Location: " . $data['data']['payment_url']);
        exit;
    } else {
        die("Payment initiation failed: " . ($data['error'] ?? 'Unknown Error'));
    }
}

/**
 * Step 2: Handle Browser Redirect Callback
 */
function handleCallback() {
    $orderId = $_GET['order_id'] ?? '';
    $status = $_GET['status'] ?? '';
    
    if (empty($orderId) || $status !== 'success') {
        die("Payment was not successful or was cancelled.");
    }
    
    // Now verify status securely on the backend
    $apiKey = "pi_live_xxxxxxxxxxxxxxxxxxxxxxxx";
    $apiSecret = "sk_live_xxxxxxxxxxxxxxxxxxxxxxxx";
    
    $ch = curl_init('https://smbupi.com/api/check-status');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => json_encode(['order_id' => $orderId]),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Content-Type: application/json',
            'X-API-Key: ' . $apiKey,
            'X-API-Secret: ' . $apiSecret
        ]
    ]);

    $response = curl_exec($ch);
    $data = json_decode($response, true);
    unset($ch);

    if (isset($data['status']) && $data['status'] === 'success' && $data['data']['payment_status'] === 'success') {
        $amount = $data['data']['amount'];
        $utr = $data['data']['utr'];
        
        echo "<h1 style='color:green;'>Payment Successful!</h1>";
        echo "<p>Thank you, your order <strong>$orderId</strong> of ₹$amount has been paid successfully.</p>";
        echo "<p>UTR Reference: $utr</p>";
    } else {
        echo "<h1 style='color:red;'>Verification Failed</h1>";
        echo "<p>The payment verification returned an unconfirmed status.</p>";
    }
}

// Simple Router Trigger
$action = $_GET['action'] ?? '';
if ($action === 'pay') {
    $randomOrderId = 'ORD_' . uniqid();
    initiatePayment($randomOrderId, 100.00, 'Raushan Kumar');
} elseif ($action === 'callback') {
    handleCallback();
} else {
    // Show initiation button
    echo "<a href='?action=pay' style='padding:12px 24px; background:#F97316; color:#ffffff; text-decoration:none; border-radius:8px; font-family:sans-serif; font-weight:bold;'>Pay ₹100 using " . htmlspecialchars($siteName) . "</a>";
}
?>

Merchant KYC Verification & Compliance

To adhere to regulatory mandates under the Information Technology Act, 2000 and the Prevention of Money Laundering Act (PMLA), 2002, all merchants on SMB UPI must undergo mandatory compliance verification before routing commercial payments.

Stage 1: Business / Personal PAN Verification

Merchants provide their 10-digit PAN (Permanent Account Number). Our automated verification engine cross-references the record with Income Tax Department databases to ensure legitimate taxpayer status.

Stage 2: DigiLocker Aadhaar eKYC (Official Government Handshake)

Merchants authenticate their identity using their Aadhaar number via the government-backed DigiLocker portal with an OTP sent to their UIDAI-registered mobile number.

Stage 3: Interactive Live Video KYC (V-KYC)

Merchants must complete a brief interactive video verification call with an authorized compliance officer within 7 days (1 week) of plan selection:

• Present physical original PAN Card and identification document on camera.
• Timestamped, geotagged photograph proof is captured and watermarked with IP logs.
• Ensures that fake or stolen identity documents cannot be exploited by bad actors.

8-Month Encrypted Regulatory Data Retention

In compliance with UIDAI regulations and statutory compliance guidelines, all verified merchant Aadhaar demographic data, masked UID numbers, photos, and Video KYC proof snapshots are cryptographically encrypted (AES-256) and archived for an immutable retention period of 8 Months (retained_until). This data is viewable by authorized compliance officers and auditors from the Admin Inspection Console.

Acceptable Use & Anti-Fraud Policy

SMB UPI operates a strict Zero-Tolerance Policy against fraud, deceptive practices, and illegal financial operations. Our automated risk engine monitors transaction velocity, UTR submission patterns, and buyer complaint flags.

Direct-to-Merchant Settlement Non-Custodial Architecture

All consumer payments flow directly from the customer's UPI app into the merchant's connected bank account. SMB UPI does not hold or escrow merchant funds. The merchant assumes 100% legal and commercial liability for order fulfillment, customer refunds, and tax compliance.

Gateway Setup: Paytm Business

Connect your verified Paytm Merchant account to accept UPI QR, Paytm Wallet, and UPI Intent payments with real-time webhook confirmation.

Integration Steps

1. Log in to your SMB UPI Merchant Dashboard.
2. Navigate to Connected Gateways → Paytm Business.
3. Paste your production Merchant ID (MID) and Merchant Key.
4. Click Save & Validate Connection. Transactions will immediately route and settle directly into your Paytm linked bank account.

Gateway Setup: BharatPe QR

BharatPe enables zero-MDR instant UPI settlements directly into your primary bank account via BharatPe's automated banking network.

Integration Steps

1. Open Connected Gateways → BharatPe in the Merchant Console.
2. Authorize your BharatPe merchant handle or provide your secure BharatPe merchant auth token.
3. SMB UPI will automatically sync live transaction webhooks and match incoming UPI customer payments.

Gateway Setup: Manual UPI QR & Instant UTR Matcher

Accept payments to any Indian Bank UPI VPA handle (e.g. store@okhdfcbank, business@upi, shop@icici) with dynamic QR generation and automated 12-digit UTR reconciliation.

How It Works

1. Enter your UPI VPA Identifier and Payee Display Name in Merchant Accounts.
2. When a customer clicks your checkout link, our system generates a dynamic UPI QR code with the exact transaction amount encoded.
3. The customer completes payment via their preferred UPI app (Google Pay, PhonePe, Paytm, CRED).
4. The customer submits the 12-digit Bank UTR reference number on the payment page for instant automated verification and webhook dispatch.

Gateway Setup: Binance Pay (USDT Crypto)

Accept global cryptocurrency payments in USDT (Tether) with instant wallet settlement into your verified Binance account.

Integration Steps

1. Obtain your Binance Pay Merchant API Key and Secret Key from your Binance Merchant account.
2. Enter credentials in Merchant Dashboard → Binance Pay.
3. Customers can scan with their Binance mobile app to pay seamlessly with zero chargeback risk.