API haqida
inPAY.uz API merchantlarga to'lov tranzaksiyalarini xavfsiz va tezkor yaratish imkoniyatini beradi. API RESTful arxitekturasiga asoslangan va JSON formatida ma'lumotlar almashadi.
Muhim eslatma
API bilan ishlashni boshlashdan oldin, inPAY.uz platformasida ro'yxatdan o'tib, merchant hisobingizni yaratishingiz va merchant_id hamda merchant_token olishingiz kerak.
Autentifikatsiya
API bilan ishlash uchun Bearer Token olish kerak. Token 24 soat amal qiladi.
Endpoint:
GET /authorization/
Query Parametrlar:
| Parametr | Turi | Majburiy | Tavsif |
|---|---|---|---|
| merchant_id | integer | ✓ | Merchant identifikatori |
| merchant_token | string | ✓ | Merchant token (32 belgili) |
Headers:
Accept: application/json
Misol so'rov (cURL):
curl -X GET "https://inPAY.uz/api/v1/authorization/?merchant_id=1353&merchant_token=6a7bf375b302cfcda6692e6f60402cb3" \ -H "Accept: application/json"
Misol so'rov (PHP):
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://inPAY.uz/api/v1/authorization/?merchant_id=1353&merchant_token=6a7bf375b302cfcda6692e6f60402cb3',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'Accept: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
$data = json_decode($response, true);
echo $data['bearer_token'];
?>
Javob namunasi (Success):
{
"success": true,
"bearer_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6MTM1MywiaWF0IjoxNjk..."
}
Eslatma: Bearer token 24 soat amal qiladi. Token muddati tugagandan so'ng, yangi token olish uchun qayta so'rov yuborishingiz kerak.
To'lov yaratish
Yangi to'lov tranzaksiyasini yaratish va foydalanuvchiga to'lov havolasini olish.
Endpoint:
POST /create
Headers:
Content-Type: application/json
Authorization: Bearer {your_bearer_token}
Body parametrlari (JSON):
| Parametr | Turi | Majburiy | Tavsif |
|---|---|---|---|
| merchant_id | string | ✓ | Merchant ID |
| token | string | ✓ | Merchant token |
| amount | number | ✓ | To'lov summasi (min: 1000 so'm) |
| description | string | - | To'lov haqida izoh |
| payment_method | string | - | To'lov usuli (click, payme) |
| callback_url | string | - | Webhook URL manzili |
| phone | string | - | Telefon raqami (998901234567 yoki 901234567) |
Misol so'rov (cURL):
curl -X POST "https://inPAY.uz/api/v1/create" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
-d '{
"merchant_id": "1353",
"token": "6a7bf375b302cfcda6692e6f60402cb3",
"amount": 15000,
"description": "Telefon uchun tolov",
"payment_method": "click",
"phone": "998335717717",
"callback_url": "https://merchant.uz/payment/callback"
}'
Misol so'rov (PHP):
<?php
$curl = curl_init();
$data = array(
"merchant_id" => "1353",
"token" => "6a7bf375b302cfcda6692e6f60402cb3",
"amount" => 15000,
"description" => "Telefon uchun tolov",
"payment_method" => "inPAY",
"phone" => "998335717717",
"callback_url" => "https://merchant.uz/payment/callback"
);
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://inPAY.uz/api/v1/create',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => json_encode($data),
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
),
));
$response = curl_exec($curl);
curl_close($curl);
$result = json_decode($response, true);
if ($result['success']) {
echo "Order ID: " . $result['order_id'];
echo "Pay URL: " . $result['pay_url'];
}
?>
Misol so'rov (JavaScript/Node.js):
const axios = require('axios');
const data = {
merchant_id: "1353",
token: "6a7bf375b302cfcda6692e6f60402cb3",
amount: 15000,
description: "Telefon uchun tolov",
payment_method: "click",
phone: "998335717717",
callback_url: "https://merchant.uz/payment/callback"
};
axios.post('https://inPAY.uz/api/v1/create', data, {
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
}
})
.then(response => {
console.log('Order ID:', response.data.order_id);
console.log('Pay URL:', response.data.pay_url);
})
.catch(error => {
console.error('Error:', error.response.data);
});
Javob namunasi (Success):
{
"success": true,
"order_id": "1ff2f5a6d66f6e9c",
"pay_url": "https://inPAY.uz/checkout/1ff2f5a6d66f6e9c",
"phone": "998335717717",
"message": "invoice yaratildi",
"security": {
"ip_mode": "optional",
"ip_check": "IP verified (optional)"
}
}
Keyingi qadamlar:
- Foydalanuvchini
pay_urlga yo'naltiring - Foydalanuvchi to'lovni amalga oshiradi
- To'lov muvaffaqiyatli bo'lsa, webhook orqali bildirishnoma olasiz
- order_id orqali to'lov holatini tekshirishingiz mumkin
Webhook xabarnomalar
Muhim: To'lov muvaffaqiyatli amalga oshganda, inPAY.uz tizimi sizning callback_url manzilingizga POST so'rov yuboradi.
Webhook qanday ishlaydi:
- Foydalanuvchi to'lovni muvaffaqiyatli amalga oshiradi
- inPAY.uz tizimi sizning callback_url ga POST so'rov yuboradi
- Sizning serveringiz JSON ma'lumotlarni qabul qiladi
- Buyurtma holatini yangilaysiz
- HTTP 200 status kod bilan "OK" javob qaytarasiz
Webhook ma'lumotlari:
| Parametr | Turi | Tavsif |
|---|---|---|
| amount | string | To'lov summasi (15000.00) |
| status | string | To'lov holati (success, failed) |
| order_id | string | Buyurtma identifikatori |
| transaction_id | integer | inPAY.uz tizimidagi tranzaksiya ID |
| created_at | string | Yaratilgan vaqt (2025-12-10 05:14:52) |
Webhook JSON namuna:
{
"amount": "15000.00",
"status": "success",
"order_id": "1ff2f5a6d66f6e9c",
"transaction_id": 149,
"created_at": "2025-12-10 05:14:52"
}
PHP Webhook handler namunasi:
<?php
// JSON ma'lumotlarni o'qish
$input = file_get_contents("php://input");
$data = json_decode($input, true);
// Tekshiruv
if (!$data) {
http_response_code(400);
exit('Invalid JSON');
}
// Ma'lumotlarni olish
$amount = $data['amount'];
$status = $data['status'];
$order_id = $data['order_id'];
$transaction_id = $data['transaction_id'];
$created_at = $data['created_at'];
// Logga yozish (debugging uchun)
file_put_contents('webhook_log.txt', date('Y-m-d H:i:s') . " - " . json_encode($data) . "\n", FILE_APPEND);
// Agar to'lov muvaffaqiyatli bo'lsa
if ($status === 'success') {
// Database connection
include 'db.php'; // PDO yoki mysqli connection
// Buyurtma holatini yangilash
$stmt = $pdo->prepare("UPDATE orders SET status = 'paid', paid_at = NOW() WHERE order_id = ?");
$stmt->execute([$order_id]);
// Yoki boshqa logika:
// - Email yuborish
// - SMS yuborish
// - Mahsulotni yetkazish
// - Service aktivlashtirish
}
// inPAY.uz ga javob qaytarish
echo "OK";
http_response_code(200);
?>
Node.js/Express Webhook handler:
const express = require('express');
const app = express();
app.use(express.json());
app.post('/payment/callback', async (req, res) => {
try {
const { amount, status, order_id, transaction_id, created_at } = req.body;
// Logga yozish
console.log('Webhook received:', req.body);
// Agar to'lov muvaffaqiyatli bo'lsa
if (status === 'success') {
// Database yangilash
await db.query(
'UPDATE orders SET status = ? WHERE order_id = ?',
['paid', order_id]
);
// Qo'shimcha logika
// - Email yuborish
// - Push notification
// - Service aktivlashtirish
}
// inPAY.uz ga javob
res.status(200).send('OK');
} catch (error) {
console.error('Webhook error:', error);
res.status(500).send('Error');
}
});
app.listen(3000);
Muhim eslatmalar:
- Webhook URL ni to'lov yaratishda callback_url parametrida yuboring
- Agar callback_url yuborilmasa, kassadagi default callback URL ishlatiladi
- Webhook handler JSON formatini qabul qilishi shart
- Handler HTTP 200 status kod bilan javob qaytarishi kerak
- Webhook URL HTTPS bo'lishi tavsiya etiladi
Tranzaksiya holati
Tranzaksiya holatini tekshirish uchun order_id orqali so'rov yuboring.
Endpoint:
GET /transactions/?order_id={order_id}
Headers:
Accept: application/json
Query Parametrlar:
| Parametr | Turi | Majburiy | Tavsif |
|---|---|---|---|
| order_id | string | ✓ | Buyurtma identifikatori |
Misol so'rov (cURL):
curl -X GET "https://inPAY.uz/api/v1/transactions/?order_id=1ff2f5a6d66f6e9c" \ -H "Accept: application/json"
Misol so'rov (PHP):
<?php
$order_id = "1ff2f5a6d66f6e9c";
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://inPAY.uz/api/v1/transactions/?order_id={$order_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array('Accept: application/json'),
));
$response = curl_exec($curl);
curl_close($curl);
$data = json_decode($response, true);
if ($data['success']) {
echo "Status: " . $data['status'];
echo "Amount: " . $data['amount'];
}
?>
Javob namunasi (Pending):
{
"success": true,
"order_id": "1ff2f5a6d66f6e9c",
"status": "pending",
"amount": 15000,
"payment_method": "click",
"created_at": "2025-12-10 05:14:52",
"paid_at": null
}
Javob namunasi (Success):
{
"success": true,
"order_id": "1ff2f5a6d66f6e9c",
"status": "success",
"amount": 15000,
"payment_method": "click",
"created_at": "2025-12-10 05:14:52",
"paid_at": "2025-12-10 05:15:23"
}
Status holatlari:
Xato kodlari
API bilan ishlashda quyidagi xato kodlari qaytarilishi mumkin:
| Xato kodi | HTTP Status | Tavsif |
|---|---|---|
| MISSING_AUTH_TOKEN | 401 | Authorization token topilmadi |
| INVALID_TOKEN | 401 | Bearer token noto'g'ri yoki muddati tugagan |
| MISSING_MERCHANT_ID | 400 | merchant_id parametri topilmadi |
| MERCHANT_NOT_FOUND | 404 | Merchant topilmadi |
| IP_NOT_WHITELISTED_STRICT | 403 | IP manzil whitelist da yo'q (Strict mode) |
| RATE_LIMIT_EXCEEDED | 429 | So'rovlar soni limitdan oshdi (100/soat) |
| CALLBACK_NOT_WHITELISTED | 403 | Callback URL whitelist da yo'q |
| MERCHANT_WEBSITE_NOT_WHITELISTED | 403 | Merchant website whitelist da active emas |
| AMOUNT_TOO_LOW | 400 | Summa juda kam (min: 1000 so'm) |
| AMOUNT_TOO_HIGH | 400 | Summa maksimal limitdan oshdi |
| TRANSACTION_SAVE_FAILED | 500 | Tranzaksiya saqlanmadi (server xatosi) |
Xato javob namunasi:
{
"success": false,
"message": "* Minimal toʻlov summasi 1000 soʻm",
"error_code": "AMOUNT_TOO_LOW"
}
Xatolar bilan ishlash:
- Har doim
successmaydonini tekshiring error_codeasosida xatolarni boshqaring- 401/403 xatolarida autentifikatsiyani qayta tekshiring
- 429 xatolarda biroz kuting va qayta urinib ko'ring
- 500 xatolarida support bilan bog'laning
Xavfsizlik
🔐 IP Whitelist
inPAY.uz uchta IP whitelist rejimini qo'llab-quvvatlaydi:
⚡ Rate Limiting
Har bir IP manzil uchun soatiga 100 ta so'rov limitiga ega.
Limit oshirilsa, RATE_LIMIT_EXCEEDED xatosi qaytariladi.
🔒 Bearer Token
Bearer token xavfsizligi:
- Token 24 soat amal qiladi
- Tokenni xavfsiz joyda saqlang
- Tokenni hech kimga bermang
- Token muddati tugagandan so'ng yangi token oling
- Har bir so'rovda Authorization header da yuboring
🌐 Domain Whitelist
Callback URL va merchant website whitelist da bo'lishi kerak. Whitelist ga qo'shish uchun inPAY.uz platformasida sozlamalardan foydalaning.
Eng yaxshi amaliyotlar
Bearer tokenni keshda saqlang
Har bir so'rovda yangi token olish o'rniga, tokenni 24 soat davomida keshda saqlang va qayta ishlating.
Webhook dan foydalaning
To'lov holatini doimiy tekshirish o'rniga, webhook orqali real-time bildirishnomalarni qabul qiling.
Xatolarni to'g'ri boshqaring
Har doim error_code ni tekshiring va foydalanuvchiga tushunarli xabar ko'rsating.
Barcha tranzaksiyalarni saqlang
order_id va tranzaksiya ma'lumotlarini o'z bazangizda saqlang va webhook kelganda yangilang.
HTTPS dan foydalaning
Webhook URL va callback URL lar HTTPS protokolida bo'lishi kerak.
Test muhitida sinab ko'ring
Production ga o'tishdan oldin, barcha funksiyalarni test muhitida sinab ko'ring.