MTPAY Developer REST API

Integrate lightning-fast UPI payment processing into your e-commerce store, SaaS platform, or mobile app with zero intermediary transaction fees.

⚡

Dynamic UPI QR & Intents

Generate instant checkout links and deep links supporting all popular UPI client applications.

🛡️

Real-Time Settlement Matching

Automated UTR and transaction reconciliation with intelligent order state updates.

🔒

HMAC-SHA256 Webhooks

Cryptographically signed callbacks notify your store server within 500ms of bank settlement.

Authentication

All API requests require authentication using your merchant API Key. You can pass the key in either the X-API-Key request header or as a standard Authorization: Bearer <key> header.

HTTP HEADERS

X-API-Key: tcp_live_9b4e82f10c83a79d...
Content-Type: application/json
Accept: application/json

Security Note: Always keep your API keys secure on your backend server. Never expose live API keys in front-end client-side JavaScript or public repositories.

Base URL

Use the root API v1 endpoint below for all HTTP REST requests:

REST ENDPOINT BASE

https://mtpay.shop/api/v1

Idempotency Keys

To prevent double-charging or duplicate orders due to network timeouts or retries, pass an Idempotency-Key header with a unique UUID string. If a duplicate request is received within 24 hours, the identical cached response is returned without creating a new order.

HEADER

Idempotency-Key: 7b9e84b2-e1d5-4702-8692-f04bfba5ea1b

POST /api/v1/orders

Initializes a payment session, registers the customer details, assigns the merchant's configured UPI handle, and generates dynamic payment URLs with real-time countdown.

Request Parameters

Field	Type	Requirement	Description
merchant_order_id	string	Required	Your store's internal reference ID (e.g. `INV-2026-904`). Max 100 characters.
amount	float	Required	Order total in INR (e.g. `250.00`). Min: 1.00.
redirect_url	string (URL)	Recommended	URL where customer is redirected after payment verification (with `order_id` and `utr`).
webhook_url	string (URL)	Optional	Per-order server-to-server webhook destination for settlement events.
description	string	Optional	Payment purpose or line item memo displayed on the checkout page.
customer_name	string	Optional	Name of the paying customer.
customer_email	string	Optional	Email address for receipt delivery.
customer_mobile	string	Optional	10-digit mobile number of the customer.
expiry_minutes	integer	Optional	Session lifetime before order expires (Default: `15`, Range: 5-60).

Example Request

JSON BODY

{
  "merchant_order_id": "INV-2026-904",
  "amount": 250.00,
  "description": "Premium Pro Access - 1 Month",
  "redirect_url": "https://mystore.com/order-success.php",
  "webhook_url": "https://mystore.com/api/webhook.php",
  "customer_name": "Rahul Sharma",
  "customer_email": "[email protected]",
  "customer_mobile": "9876543210",
  "expiry_minutes": 15
}

Example Response (HTTP 201 Created)

JSON RESPONSE

{
  "success": true,
  "data": {
    "gateway_order_id": "TC2610281204019",
    "merchant_order_id": "INV-2026-904",
    "amount": 250.05,
    "amount_inr": 250.05,
    "amount_paise": 25005,
    "currency": "INR",
    "upi_id": "merchant@upi",
    "qr_data": "upi://pay?pa=merchant@upi&pn=TMPay&am=250.05&cu=INR&tn=TC2610281204019",
    "checkout_url": "https://mtpay.shop/checkout.php?order_id=TC2610281204019",
    "payment_url": "https://mtpay.shop/checkout.php?order_id=TC2610281204019",
    "redirect_url": "https://mystore.com/order-success.php",
    "status": "pending",
    "expires_at": "2026-10-28 12:19:01"
  }
}

GET /api/v1/orders/{order_id}/status

Poll or verify the settlement status of an order. Once paid, the response includes the bank 12-digit UTR reference number.

Response (Verified)

JSON RESPONSE

{
  "success": true,
  "data": {
    "gateway_order_id": "TC2610281204019",
    "merchant_order_id": "INV-2026-904",
    "amount": 250.05,
    "amount_inr": 250.05,
    "amount_paise": 25005,
    "currency": "INR",
    "status": "verified",
    "utr": "429819283741",
    "customer_name": "Rahul Sharma",
    "redirect_url": "https://mystore.com/order-success.php",
    "verified_at": "2026-10-28 12:05:42"
  }
}

GET /api/v1/orders

Retrieve a paginated list of payment orders with optional status filtering.

Query Parameters

Param	Type	Default	Description
status	string	`all`	Filter by status: `pending`, `verified`, `expired`.
limit	integer	`20`	Number of records per page (max 100).
page	integer	`1`	Page number offset.

POST /api/v1/devices/pair

Pairs an authorized merchant terminal or integration device with the merchant account using a temporary 6-digit verification code.

REQUEST BODY

{
  "pairing_code": "849201",
  "device_model": "Samsung Galaxy S23",
  "android_version": "14",
  "fcm_token": "fcm_token_string_here..."
}

POST /api/v1/devices/evidence

Called by the authorized merchant connector service or webhook bridge when settlement confirmation is received.

REQUEST BODY

{
  "sender": "BANK_NOTIFICATION",
  "message": "UPI Credit Settlement Ref 429819283741 Confirmed.",
  "timestamp": 1793164800
}

Webhook Cryptographic Verification

Every webhook dispatched by MTPAY includes an X-TC-Signature header generated with HMAC-SHA256 to verify authenticity and prevent tampering or replay attacks.

Signature Header

X-TC-Signature

Hex-encoded HMAC-SHA256 of timestamp + raw JSON body.

Timestamp Header

X-TC-Timestamp

Unix epoch timestamp (seconds). Enforces a 300-second freshness window.

Production PHP Verification Snippet

PHP (webhook.php)

<?php
// 1. Read raw payload and headers
$rawPayload = file_get_contents('php://input');
$signature  = $_SERVER['HTTP_X_TC_SIGNATURE'] ?? '';
$timestamp  = (int)($_SERVER['HTTP_X_TC_TIMESTAMP'] ?? 0);
$secret     = 'whsec_YOUR_WEBHOOK_SECRET'; // From Dashboard -> Webhooks

// 2. Prevent replay attacks (5 minute window)
if (abs(time() - $timestamp) > 300) {
    http_response_code(401);
    die(json_encode(['error' => 'Webhook timestamp expired']));
}

// 3. Compute expected cryptographic signature
$expectedSignature = hash_hmac('sha256', $timestamp . '.' . $rawPayload, $secret);

// 4. Constant-time comparison
if (!hash_equals($expectedSignature, $signature)) {
    http_response_code(401);
    die(json_encode(['error' => 'Invalid HMAC signature']));
}

// 5. Parse verified event payload
$event = json_decode($rawPayload, true);
if ($event['event'] === 'order.verified') {
    $orderId = $event['data']['merchant_order_id'];
    $bankUtr = $event['data']['utr'];
    
    // Mark order as paid in your database
    // updateOrderStatus($orderId, 'paid', $bankUtr);
}

// Return 200 OK to acknowledge delivery
http_response_code(200);
echo json_encode(['received' => true]);

Webhook Event Payloads

When an order is successfully verified by the settlement engine, the following JSON event is posted to your endpoint:

EVENT: order.verified

{
  "event": "order.verified",
  "id": "evt_7f9b201a4e8d",
  "created_at": 1793164800,
  "data": {
    "gateway_order_id": "TC2610281204019",
    "merchant_order_id": "INV-2026-904",
    "amount": 250.05,
    "amount_inr": 250.05,
    "amount_paise": 25005,
    "currency": "INR",
    "status": "verified",
    "utr": "429819283741",
    "customer_name": "Rahul Sharma",
    "customer_email": "[email protected]",
    "customer_mobile": "9876543210",
    "verified_at": "2026-10-28 12:05:42"
  }
}

E-Commerce Redirect Flow

When integrating with your online store (WooCommerce, Magento, Shopify or custom PHP/Node cart):

Your store calls POST /api/v1/orders and receives checkout_url.
Redirect your buyer to the checkout_url.
The buyer pays using any UPI app (GPay / PhonePe / Paytm) or scans the dynamic QR code.
The matching engine verifies the transaction in under 2 seconds.
The checkout screen confirms the payment with an animated checkmark and shows a 3-second countdown.
The buyer is automatically redirected to your redirect_url with parameters:
https://yourstore.com/order-success.php?order_id=TC2610281204019&status=verified&utr=429819283741

Official PHP SDK

The official PHP client library makes creating orders and verifying signatures completely effortless:

PHP SDK EXAMPLE

require_once __DIR__ . '/sdk/php/TcPayReader.php';

// Initialize Client
$client = new \TCPay\SDK\TcPayReader([
    'api_key'  => 'tcp_live_YOUR_API_KEY',
    'base_url' => 'https://mtpay.shop',
]);

// Create Order
$order = $client->createOrder([
    'merchant_order_id' => 'CART-' . time(),
    'amount'            => 499.00,
    'description'       => 'Ecommerce Store Purchase',
    'redirect_url'      => 'https://mystore.com/order-success.php',
    'webhook_url'       => 'https://mystore.com/api/webhook.php',
    'customer_name'     => 'Aditi Verma',
    'customer_email'    => '[email protected]',
    'customer_mobile'   => '9820098200',
]);

// Redirect Buyer to Hosted Checkout
header('Location: ' . $order['checkout_url']);
exit;

Live Sample Store

Want to see the end-to-end flow in action? We have included a full turnkey e-commerce store with simulated checkout, auto-redirect, and webhook verification right in this installation.

Launch MTPAY Demo Store

Select test products, experience 1-click UPI checkout, and watch the instant redirect back to the order success page with real bank UTR references.

🚀 Open Demo Store ↗

🎮 Launch Game Top-Up Demo (Player UID + Phone) Turnkey Gamer Flow

Built for gaming platforms, diamond recharge portals, and custom apps. The buyer enters Player UID and Mobile, generates dynamic QR with theme selector, and receives instant credit via HMAC webhook!

🕹️ Open Game Demo ↗