API v1

MIPL Payment Gateway API

MIPL Payment Gateway is a REST API that lets you accept UPI payments on your website or app. Customer money goes directly to your bank account — MIPL Payment Gateway only provides the payment page, verification and notification technology.

BASE URL https://pay.moldable.in/api/v1/
  • All requests must be made over HTTPS.
  • Send the request body as application/json (or form-data).
  • All responses are JSON. Amounts are always in rupees (not paise), e.g. 499.00.
  • All timestamps are in IST (Asia/Kolkata) using the YYYY-MM-DD HH:MM:SS format.

Payment flow

  1. Order create — Your server calls the create_order API.
  2. Redirect — Send the customer to the payment_url from the response. It shows a QR code, UPI ID and UPI app buttons.
  3. Payment — The customer pays with any UPI app. The money arrives in your bank.
  4. Verification — The Listener App detects the payment from your bank SMS / UPI notification (or the customer submits a UTR and you approve it).
  5. Webhook — MIPL Payment Gateway sends a signed payment.success event to your webhook_url. Complete the order / credit the wallet here.
  6. Redirect back — The customer is automatically returned to your redirect_url after seeing "Payment Successful".

Quick start (5 minutes)

  1. Create an account and add your UPI ID in Dashboard → Settings.
  2. Copy your API Key and API Secret from Dashboard → API Keys.
  3. Set your Webhook URL and Redirect URL in Settings (or send them with each order).
  4. Connect your business phone from Dashboard → Listener App (for automatic verification).
  5. Create your first test order (₹1–10) with the Create order API below.

Authentication

Send these two headers with every API request:

HeaderValue
X-Api-KeyYour public API key, e.g. mipl_live_…
X-Api-SecretYour secret key, e.g. sk_…
🔒 Never put your API Secret in frontend code (browser JavaScript, Android/iOS apps). Call the API only from your server. If the secret leaks, regenerate it immediately in Dashboard → API Keys.

Create order

Creates a new payment order and returns a payment link for the customer.

POST /api/v1/create_order.php

Request parameters

ParameterTypeDescription
amount requirednumberAmount in rupees, from 1 to 100,000. Example: 499 or 499.50
order_id requiredstringUnique order ID from your system (A-Z, a-z, 0-9, _, -; max 80). Each order_id can be used only once.
customer_name optionalstringCustomer name
customer_mobile optionalstring10-digit mobile
customer_email optionalstringCustomer email
note optionalstringOrder description (max 255)
redirect_url optionalurlThe customer is sent here after payment. If omitted, the default from Settings is used.
webhook_url optionalurlThe webhook for this order is sent here. If omitted, the default from Settings is used.

Example request

curl -X POST "https://pay.moldable.in/api/v1/create_order.php" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: mipl_live_xxxxxxxxxxxx" \
  -H "X-Api-Secret: YOUR_API_SECRET" \
  -d '{
    "amount": 499,
    "order_id": "INV1001",
    "customer_name": "Rahul Kumar",
    "customer_mobile": "9876543210",
    "note": "Wallet top-up",
    "redirect_url": "https://yoursite.com/payment-return.php",
    "webhook_url": "https://yoursite.com/mipl-webhook.php"
  }'
<?php
$payload = [
    'amount'          => 499,
    'order_id'        => 'INV1001',
    'customer_name'   => 'Rahul Kumar',
    'customer_mobile' => '9876543210',
    'redirect_url'    => 'https://yoursite.com/payment-return.php',
    'webhook_url'     => 'https://yoursite.com/mipl-webhook.php',
];
$ch = curl_init('https://pay.moldable.in/api/v1/create_order.php');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'X-Api-Key: mipl_live_xxxxxxxxxxxx',
        'X-Api-Secret: YOUR_API_SECRET',
    ],
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($res['status']) {
    header('Location: ' . $res['data']['payment_url']); // send the customer to the payment page
    exit;
}
echo $res['error']['message'];
const res = await fetch('https://pay.moldable.in/api/v1/create_order.php', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'mipl_live_xxxxxxxxxxxx',
    'X-Api-Secret': process.env.MIPL_SECRET,
  },
  body: JSON.stringify({ amount: 499, order_id: 'INV1001', redirect_url: 'https://yoursite.com/return' }),
});
const json = await res.json();
if (json.status) res.redirect(json.data.payment_url); // Express example
import requests

r = requests.post(
    "https://pay.moldable.in/api/v1/create_order.php",
    json={"amount": 499, "order_id": "INV1001", "redirect_url": "https://yoursite.com/return"},
    headers={"X-Api-Key": "mipl_live_xxxxxxxxxxxx", "X-Api-Secret": "YOUR_API_SECRET"},
    timeout=20,
)
data = r.json()
if data["status"]:
    payment_url = data["data"]["payment_url"]

Success response 201

{
  "status": true,
  "message": "Order created",
  "data": {
    "payment_id": "MPG261120A1B2C3D4E5",
    "order_id": "INV1001",
    "amount": 499,
    "pay_amount": 499.07,
    "currency": "INR",
    "status": "pending",
    "payment_url": "https://pay.moldable.in/pay/?id=MPG261120A1B2C3D4E5",
    "upi_id": "yourshop@okaxis",
    "upi_intent": "upi://pay?pa=yourshop%40okaxis&pn=Your%20Shop&am=499.07&cu=INR&tn=Pay%20MPG261120A1B2C3D4E5",
    "qr_string": "upi://pay?...same as upi_intent...",
    "expires_at": "2026-11-20 16:45:00"
  }
}
FieldDescription
payment_idMIPL Payment Gateway unique payment reference
pay_amountThe exact amount the customer must pay (with unique paise). Why?
payment_urlHosted payment page — redirect the customer here (recommended)
upi_intent / qr_stringIf you want to build your own payment UI, use this string to generate a QR or a "Pay with UPI" button
expires_atThe payment page stays active until this time (10 minutes)

Payment page & redirect

Hosted payment page (payment_url) shows the customer:

  • Dynamic UPI QR code (fixed amount)
  • UPI ID copy button
  • PhonePe / GPay / Paytm / any UPI app buttons on mobile
  • 10 -minute countdown timer and live status (checked every 3 seconds)
  • Backup: "Submit UTR" form

As soon as the payment succeeds, the page shows "Payment Successful" and redirects to your redirect_url within 3 seconds, with these query params:

https://yoursite.com/payment-return.php?order_id=INV1001&payment_id=MPG261120A1B2C3D4E5&status=success
⚠️ Do NOT credit a wallet or complete an order based on status=success in the redirect URL. Anyone can type that URL. Credit wallets only from the webhook, or after verifying with the Order status API.

Webhooks

When a payment succeeds or fails, MIPL Payment Gateway sends a POST request to your webhook URL.

Headers

HeaderDescription
Content-Typeapplication/json
X-MIPL-Eventpayment.success | payment.failed | test
X-MIPL-SignatureHMAC-SHA256 (hex) of the raw request body, using your API Secret

Payload

{
  "event": "payment.success",
  "data": {
    "payment_id": "MPG261120A1B2C3D4E5",
    "order_id": "INV1001",
    "amount": 499,
    "pay_amount": 499.07,
    "status": "success",
    "utr": "432198765012",
    "paid_via": "auto",
    "customer": { "name": "Rahul Kumar", "mobile": "9876543210", "email": null },
    "note": "Wallet top-up",
    "created_at": "2026-11-20 16:35:00",
    "paid_at": "2026-11-20 16:36:12"
  }
}

paid_via: auto (Listener App / automatic UTR match) or manual (approved by the merchant in the dashboard).

Verify the signature

<?php
// mipl-webhook.php
$secret = 'YOUR_API_SECRET';
$raw    = file_get_contents('php://input');
$sig    = $_SERVER['HTTP_X_MIPL_SIGNATURE'] ?? '';

if (!hash_equals(hash_hmac('sha256', $raw, $secret), $sig)) {
    http_response_code(401);
    exit('invalid signature');
}
$event = json_decode($raw, true);

if ($event['event'] === 'payment.success') {
    $p = $event['data'];
    // IDEMPOTENT update: only mark pending orders as paid
    $st = $pdo->prepare("UPDATE wallet_topups SET status='paid', utr=? WHERE order_id=? AND status='pending' AND amount=?");
    $st->execute([$p['utr'], $p['order_id'], $p['amount']]);
    if ($st->rowCount() === 1) {
        // credit the user's wallet here
    }
}
http_response_code(200);
echo 'OK';
const crypto = require('crypto');
// Express: raw body required — app.use('/mipl-webhook', express.raw({ type: 'application/json' }))
app.post('/mipl-webhook', (req, res) => {
  const expected = crypto.createHmac('sha256', process.env.MIPL_SECRET).update(req.body).digest('hex');
  const sig = req.get('X-MIPL-Signature') || '';
  if (sig.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).send('invalid signature');
  }
  const event = JSON.parse(req.body.toString());
  if (event.event === 'payment.success') { /* credit wallet (idempotent) */ }
  res.send('OK');
});
import hmac, hashlib, json
from flask import request, abort

@app.post("/mipl-webhook")
def mipl_webhook():
    raw = request.get_data()
    expected = hmac.new(SECRET.encode(), raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, request.headers.get("X-MIPL-Signature", "")):
        abort(401)
    event = json.loads(raw)
    if event["event"] == "payment.success":
        pass  # credit wallet (idempotent)
    return "OK"

Retry policy

  • A webhook counts as delivered when your endpoint returns HTTP 2xx.
  • Failed deliveries are retried up to 5 times (with increasing gaps).
  • The same webhook may arrive more than once — make your handler idempotent (check order_id + status).
  • Every attempt appears in Dashboard → Webhook Logs, and you can "Resend" manually from the order page.

Order status

Check the current status of any order. Use it on your redirect page or for double verification if a webhook is missed.

GET /api/v1/order_status.php?order_id=INV1001
ParameterDescription
order_idYour order ID
payment_idOr the MIPL Payment Gateway payment ID (one of the two is required)
curl "https://pay.moldable.in/api/v1/order_status.php?order_id=INV1001" \
  -H "X-Api-Key: mipl_live_xxxxxxxxxxxx" \
  -H "X-Api-Secret: YOUR_API_SECRET"
{
  "status": true,
  "data": {
    "payment_id": "MPG261120A1B2C3D4E5",
    "order_id": "INV1001",
    "amount": 499,
    "pay_amount": 499.07,
    "status": "success",
    "utr": "432198765012",
    "paid_via": "auto",
    "customer": { "name": "Rahul Kumar", "mobile": "9876543210", "email": null },
    "note": "Wallet top-up",
    "created_at": "2026-11-20 16:35:00",
    "paid_at": "2026-11-20 16:36:12"
  }
}

Order statuses

StatusMeaningFinal?
pendingOrder created, customer has not paid yetNo
pending_verifyCustomer submitted a UTR, awaiting merchant verificationNo
successPayment confirmed — complete the orderYes
expiredTime ran out without payment. (A late payment within 60 min can still auto-match → success)Mostly
failedMerchant rejected the UTRYes

Errors

Errors return status: false with an HTTP error code:

{ "status": false, "error": { "code": "validation_error", "message": "amount must be between 1 and 100000" } }
HTTPcodeWhen
400bad_requestMerchant UPI ID not set / bad request
401unauthorizedAPI key / secret wrong or missing
402insufficient_balanceInsufficient fee wallet balance — recharge from the dashboard
403forbiddenMerchant account blocked
403kyc_limitKYC pending and the order/daily limit was exceeded
404not_foundOrder not found
405method_not_allowedWrong HTTP method (create_order is POST only)
409duplicate_orderorder_id already used
422validation_errorInvalid / missing parameter
429too_many_pendingToo many pending orders for the same amount — try again shortly
500server_errorServer issue — please retry

Why a unique amount (paise)?

Money goes straight to your bank, so the bank SMS contains only the amount and UTR, not the order ID. To tell pending orders apart, MIPL Payment Gateway adds 1–99 unique paise to each amount, e.g. ₹499 → ₹499.07.

  • Webhooks and status responses include both amount (your original) and pay_amount (what the customer paid).
  • Always credit amount to the wallet. The extra paise are a tiny round-off for the customer.
  • If the customer pays a round amount without the paise and only one order matches, it is still matched automatically. Otherwise the customer submits the UTR and you verify it in the review queue.

Complete example: Wallet top-up

The complete "Add Money" flow for a recharge / BBPS-portal style website:

-- In your database
CREATE TABLE wallet_topups (
  id INT AUTO_INCREMENT PRIMARY KEY,
  order_id VARCHAR(80) UNIQUE,
  user_id INT,
  amount DECIMAL(12,2),
  status ENUM('pending','paid','failed') DEFAULT 'pending',
  utr VARCHAR(30) NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
<?php
// add-money.php
require 'MiplPay.php';
$pg = new MiplPay('mipl_live_xxxxxxxxxxxx', 'YOUR_API_SECRET', 'https://pay.moldable.in');

$orderId = 'WAL' . $userId . 'T' . time();
$pdo->prepare("INSERT INTO wallet_topups (order_id, user_id, amount) VALUES (?,?,?)")
    ->execute([$orderId, $userId, $amount]);

$order = $pg->createOrder([
    'amount'       => $amount,
    'order_id'     => $orderId,
    'redirect_url' => 'https://yoursite.com/payment-return.php',
    'webhook_url'  => 'https://yoursite.com/mipl-webhook.php',
]);
header('Location: ' . $order['payment_url']);

Then credit the wallet in your webhook handler, and show the status on payment-return.php using $pg->orderStatus(['order_id' => $_GET['order_id']]).

Listener App API

The official Listener App uses this API. To build your own custom listener (e.g. Tasker / MacroDroid / your own app):

POST /api/v1/listener.php
ParameterDescription
device_key requiredFrom Dashboard → Listener App (or the X-Device-Key header)
actionping (every 1 minute, for online status) or payment (default)
messageFull text of the bank SMS / UPI notification — the server extracts the amount and UTR
amount, utrOptional — if your app parses them itself
senderOptional — SMS sender ID / app package (e.g. VM-SBIINB)
curl -X POST "https://pay.moldable.in/api/v1/listener.php" \
  -d "device_key=dev_xxxxxxxx" \
  -d "sender=VM-SBIUPI" \
  --data-urlencode "message=Rs.499.07 credited to a/c XX1234 by UPI Ref No 432198765012"

# Response
{ "status": true, "matched": true, "payment_id": "MPG261120A1B2C3D4E5", "message": "Payment matched", "amount": 499.07, "utr": "432198765012" }

PHP SDK & examples

A single-file SDK — no Composer dependencies.

⬇ MiplPay.php (SDK) checkout.php webhook.php payment-return.php

<?php
require 'MiplPay.php';
$pg = new MiplPay('mipl_live_xxxxxxxxxxxx', 'YOUR_API_SECRET', 'https://pay.moldable.in');

// Order
$order = $pg->createOrder(['amount' => 499, 'order_id' => 'INV1001']);
header('Location: ' . $order['payment_url']);

// Status
$pg->isPaid('INV1001', 499);            // true / false
$pg->orderStatus(['order_id' => 'INV1001']);

// Webhook
$event = $pg->verifyWebhook(file_get_contents('php://input'), $_SERVER['HTTP_X_MIPL_SIGNATURE'] ?? '');
if ($event === null) { http_response_code(401); exit; }

WooCommerce plugin

  1. Download the plugin zip.
  2. WordPress → Plugins → Add New → Upload Plugin → select the zip → Activate.
  3. WooCommerce → Settings → Payments → MIPL Payment Gateway (UPI) → enter your API Key, API Secret and Gateway URL.
  4. The webhook URL is set automatically (/?wc-api=mipl_upi). The order moves to "Processing" as soon as payment succeeds.

KYC & limits

Until KYC is approved: max ₹2,000 per order and ₹10,000 per day. Exceeding a limit makes create_order return 403 kyc_limit. Upload your PAN, address and a document in Dashboard → KYC.

Listener App

Download the APK from Dashboard → Listener App. The app checks for new versions automatically and shows an update prompt.

Testing checklist

  1. Create a ₹1 link in Dashboard → Payment Link and pay it yourself. With the Listener App online, it should turn SUCCESS within 5–10 seconds.
  2. Use Settings → Send test webhook to check that your webhook endpoint returns HTTP 200.
  3. Create an order via the API, pay it, and check that the webhook arrived, the wallet was credited and the page redirected.
  4. UTR flow test: turn off the Listener App and pay → submit the UTR on the payment page → approve it in Dashboard → Needs Review.
  5. Duplicate webhook test: click "Resend webhook" on the order page — the wallet must not be credited again.

Security best practices

  • Keep the API Secret only on the server, in an environment variable / config file (never commit it to git).
  • Always verify the webhook signature and match amount against the amount in your DB.
  • Keep wallet credits idempotent (WHERE status='pending').
  • Do not trust redirect URL parameters — verify with the status API.
  • Before approving a manual UTR, confirm the exact amount and UTR in your bank statement / UPI app.
  • Use a business / current account UPI ID.

Fees

A platform fee of 0.3% (min ₹0.25, max ₹15) is deducted from your prepaid fee wallet on every successful payment. Customers are never charged extra, and there is no fee on failed/expired orders. If the wallet balance is too low, create_order returns 402 insufficient_balance.

Support: +91 8811054210 • support@moldable.in