API Documentation — TUMAN GATEWAY

Authentication

The TUMAN GATEWAY API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

All API requests require your unique 64-character API Key to be sent in the header.

X-API-KEY: YOUR_API_KEY

Keep your API key secure. Do not share it in publicly accessible areas such as GitHub, client-side code, or public forums. All API requests must be made from your secure backend server.

Base URL

All API endpoints operate under the following base URL:

https://www.tuman.abhrostore.in/api/v1/

1. Create Payment

Creates a new dynamic payment session and generates a unique checkout URL. The user must be redirected to this URL to complete the payment.

POST /api/v1/create.php

Request Parameters

Parameter	Type	Required	Description
`amount`	Float	Yes	Amount to be charged in INR (e.g. 199.00)
`order_id`	String	Yes	Your internal unique order ID
`customer_name`	String	No	Name of the customer
`customer_email`	String	No	Email address of the customer
`customer_phone`	String	No	Phone number of the customer
`redirect_url`	String	No	URL to redirect the user to after payment success
`webhook_url`	String	No	Overrides default webhook URL for this specific transaction

Example Request

PHP (cURL)

Python (Req)

Node.js

$ch = curl_init('https://www.tuman.abhrostore.in/api/v1/create.php');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-KEY: YOUR_API_KEY',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'order_id' => 'ORD_' . time(),
    'amount' => 499.00,
    'customer_email' => 'user@example.com',
    'redirect_url' => 'https://yourwebsite.com/success.php'
]));

$response = curl_exec($ch);
$data = json_decode($response, true);
echo $data['payment_url'];

import requests
import time

url = "https://www.tuman.abhrostore.in/api/v1/create.php"
headers = {
    "X-API-KEY": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "order_id": f"ORD_{int(time.time())}",
    "amount": 499.00,
    "customer_email": "user@example.com",
    "redirect_url": "https://yourwebsite.com/success.php"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json()['payment_url'])

const axios = require('axios');

axios.post('https://www.tuman.abhrostore.in/api/v1/create.php', {
    order_id: `ORD_${Date.now()}`,
    amount: 499.00,
    customer_email: 'user@example.com',
    redirect_url: 'https://yourwebsite.com/success.php'
}, {
    headers: { 'X-API-KEY': 'YOUR_API_KEY' }
}).then(response => {
    console.log(response.data.payment_url);
}).catch(error => console.error(error));

Example Response

{
    "status": "success",
    "payment_url": "https://tuman.abhrostore.in/pay/?id=abcd1234efgh5678",
    "order_id": "ORD_1680000000",
    "internal_txn_id": "abcd1234efgh5678",
    "amount": 499.00,
    "expires_at": "2026-04-24 19:30:00"
}

                    

2. Verify Payment

Retrieves the live status of a payment. If the payment timer has expired but the status is still pending in our DB, calling this endpoint will actively ping Paytm servers to fetch the absolute real-time result.

POST /api/v1/verify.php

Request Parameters

Parameter	Type	Required	Description
`order_id`	String	Yes	The order_id you passed during creation

Example Request

PHP

$ch = curl_init('https://www.tuman.abhrostore.in/api/v1/verify.php');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-KEY: YOUR_API_KEY',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'order_id' => 'ORD_1680000000'
]));

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

if ($data['payment_status'] === 'success') {
    echo "Payment completed via: " . $data['payment_mode'];
}

Example Response

{
    "status": "success",
    "payment_status": "success",
    "amount": "499.00",
    "paytm_txn_id": "2026042411121280011016800000000",
    "internal_txn_id": "abcd1234efgh5678",
    "payment_mode": "UPI",
    "upi_id": "user@upi",
    "paid_at": "2026-04-24 19:15:22"
}

                    

Webhooks & Events

Webhooks allow you to receive real-time notifications on your server when a payment succeeds, fails, or is refunded. All payloads are sent via POST as JSON.

Payload Structure

{
    "event": "payment.success",
    "platform": "TUMAN_GATEWAY",
    "order_id": "ORD_1680000000",
    "internal_txn_id": "abcd1234efgh5678",
    "paytm_txn_id": "2026042411121280011016800000000",
    "amount": "499.00",
    "payment_mode": "UPI",
    "upi_id": "user@upi",
    "timestamp": "2026-04-24 19:15:22"
}

                    

Signature Verification (Security)

Every webhook request contains an X-TUMAN-SIGNATURE header. This is an HMAC-SHA256 signature generated using your Webhook Secret and the raw request body. You must verify this to prevent spoofing attacks.

PHP Verify

Python Verify

$webhook_secret = 'YOUR_WEBHOOK_SECRET';

// 1. Get raw POST body
$payload = file_get_contents('php://input');

// 2. Get signature from headers
$headers = getallheaders();
$signature = $headers['X-TUMAN-SIGNATURE'] ?? '';

// 3. Generate expected signature
$expected_signature = hash_hmac('sha256', $payload, $webhook_secret);

// 4. Constant-time comparison
if (hash_equals($expected_signature, $signature)) {
    $data = json_decode($payload, true);
    if ($data['event'] === 'payment.success') {
        // Mark order as paid in your DB
        http_response_code(200);
        echo "Webhook processed securely.";
    }
} else {
    http_response_code(401);
    die("Invalid Signature");
}

from flask import Flask, request, abort
import hmac
import hashlib

app = Flask(__name__)
WEBHOOK_SECRET = 'YOUR_WEBHOOK_SECRET'

@app.route('/webhook', methods=['POST'])
def webhook():
    payload = request.get_data()
    signature = request.headers.get('X-TUMAN-SIGNATURE')
    
    # Generate expected signature
    expected_signature = hmac.new(
        WEBHOOK_SECRET.encode('utf-8'), 
        payload, 
        hashlib.sha256
    ).hexdigest()
    
    # Constant-time comparison
    if hmac.compare_digest(expected_signature, signature):
        data = request.json
        if data['event'] == 'payment.success':
            # Process payment...
            return "OK", 200
    else:
        abort(401)

Telegram Bot Integration

Because TUMAN GATEWAY handles the entire UI and Paytm routing natively, integrating payments into a Telegram bot is incredibly simple. Below is a complete working example using Python's pyTelegramBotAPI.

Python (pyTelegramBotAPI)

import telebot
import requests
import time
from telebot.types import InlineKeyboardMarkup, InlineKeyboardButton

BOT_TOKEN = "YOUR_TELEGRAM_BOT_TOKEN"
API_KEY = "YOUR_API_KEY"
GATEWAY_URL = "https://www.tuman.abhrostore.in/api/v1"

bot = telebot.TeleBot(BOT_TOKEN)

@bot.message_handler(commands=['buy'])
def send_payment_link(message):
    order_id = f"BOT_{message.chat.id}_{int(time.time())}"
    
    # 1. Call TUMAN GATEWAY API
    response = requests.post(f"{GATEWAY_URL}/create.php", json={
        "order_id": order_id,
        "amount": 99.00
    }, headers={"X-API-KEY": API_KEY}).json()
    
    if response['status'] == 'success':
        pay_url = response['payment_url']
        
        # 2. Create Inline Keyboard
        markup = InlineKeyboardMarkup()
        markup.add(InlineKeyboardButton("Pay ₹99 via UPI", url=pay_url))
        markup.add(InlineKeyboardButton("Verify Payment", callback_data=f"verify_{order_id}"))
        
        bot.send_message(message.chat.id, "Invoice generated. Click below to pay:", reply_markup=markup)

@bot.callback_query_handler(func=lambda call: call.data.startswith('verify_'))
def verify_payment(call):
    order_id = call.data.split('_')[1]
    
    # 3. Call TUMAN GATEWAY Verify API
    res = requests.post(f"{GATEWAY_URL}/verify.php", json={"order_id": order_id}, headers={"X-API-KEY": API_KEY}).json()
    
    if res['payment_status'] == 'success':
        bot.answer_callback_query(call.id, "Payment Successful! Premium activated.", show_alert=True)
        bot.edit_message_text("Thank you for your purchase.", call.message.chat.id, call.message.message_id)
    elif res['payment_status'] == 'pending':
        bot.answer_callback_query(call.id, "Payment is pending. Try again after paying.", show_alert=True)
    else:
        bot.answer_callback_query(call.id, "Payment failed or expired.", show_alert=True)

bot.polling()

Error Codes

HTTP Status	Error Code	Meaning
`401 Unauthorized`	MISSING_API_KEY	No X-API-KEY header provided.
`401 Unauthorized`	INVALID_API_KEY	The API key provided is incorrect or regenerated.
`402 Payment Required`	ACCOUNT_SUSPENDED	Developer account is suspended by Admin.
`403 Forbidden`	IP_NOT_WHITELISTED	API request came from an unapproved IP address.
`429 Too Many Requests`	RATE_LIMIT_EXCEEDED	You have exceeded your per-minute request limit.
`409 Conflict`	ORDER_ALREADY_PAID	Attempted to create a session for an order_id that is already paid.