inPAY.uz API Documentation
v1.0 · Stable Yordam
Developer Documentation

inPAY.uz REST API

Merchantlarga to'lov tranzaksiyalarini xavfsiz va tezkor yaratish imkoniyati. RESTful arxitekturasi, JSON format, Bearer Token autentifikatsiya.

Xavfsizlik
Bearer Token + IP Whitelist
Real-time
Tezkor to'lov jarayoni
Webhook
Avtomatik bildirishnomalar
Boshlash uchun: inPAY.uz platformasida ro'yxatdan o'tib, merchant hisobingizni yarating va merchant_id hamda merchant_token oling.

Autentifikatsiya

GET/authorization/

API bilan ishlash uchun Bearer Token olish kerak. Token 24 soat amal qiladi. Har bir so'rovda Authorization: Bearer {token} headerini yuboring.

Query Parametrlar
ParametrTipMajburiyTavsif
merchant_idinteger✓ HaMerchant identifikatori
merchant_tokenstring✓ HaMerchant token (32 belgili)
Headers
HTTP
Accept: application/json
cURL
curl -X GET "https://inPAY.uz/api/v1/authorization/?merchant_id=1353&merchant_token=6a7bf375b302cfcda6692e6f60402cb3" \
  -H "Accept: application/json"
PHP
<?php
$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL            => 'https://inPAY.uz/api/v1/authorization/?merchant_id=1353&merchant_token=6a7bf375b302cfcda6692e6f60402cb3',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => ['Accept: application/json'],
]);
$response = curl_exec($curl);
curl_close($curl);
$data = json_decode($response, true);
// Tokenni keshda saqlang (24 soat amal qiladi)
cache_set('inpay_token', $data['bearer_token'], 86400);
?>
Response (Success)
JSON
{
  "success": true,
  "bearer_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6MTM1MywiaWF0IjoxNjk..."
}
Eslatma: Bearer token 24 soat amal qiladi. Har so'rovda yangi token olish o'rniga, tokenni keshda saqlang va muddati tugaganda yangilang.

To'lov Yaratish

POST/create

Yangi to'lov tranzaksiyasini yaratish. Muvaffaqiyatli bo'lsa foydalanuvchini pay_url ga yo'naltiring.

Headers
HTTP
Content-Type: application/json
Authorization: Bearer {your_bearer_token}
Body Parametrlar (JSON)
ParametrTipMajburiyTavsif
merchant_idstring✓ HaMerchant ID
tokenstring✓ HaMerchant token
amountnumber✓ HaTo'lov summasi (min: 1 000 so'm)
descriptionstring— IxtiyoriyTo'lov haqida izoh
payment_methodstring— IxtiyoriyTo'lov usuli (click, payme, inPAY)
callback_urlstring— IxtiyoriyWebhook URL manzili
phonestring— IxtiyoriyTelefon raqami (998901234567)
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"
  }'
PHP
<?php
$data = [
  "merchant_id"    => "1353",
  "token"          => "6a7bf375b302cfcda6692e6f60402cb3",
  "amount"         => 15000,
  "description"    => "Telefon uchun tolov",
  "payment_method" => "inPAY",
  "phone"          => "998335717717",
  "callback_url"   => "https://merchant.uz/payment/callback",
];

$curl = curl_init('https://inPAY.uz/api/v1/create');
curl_setopt_array($curl, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_POSTFIELDS     => json_encode($data),
  CURLOPT_HTTPHEADER     => [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $bearerToken,
  ],
]);
$result = json_decode(curl_exec($curl), true);
curl_close($curl);

if ($result['success']) {
  // Foydalanuvchini pay_url ga yo'naltiring
  header('Location: ' . $result['pay_url']);
}
?>
JavaScript (Node.js / axios)
const axios = require('axios');

const result = await axios.post('https://inPAY.uz/api/v1/create', {
  merchant_id:    "1353",
  token:          "6a7bf375b302cfcda6692e6f60402cb3",
  amount:         15000,
  description:    "Telefon uchun tolov",
  payment_method: "click",
  phone:          "998335717717",
  callback_url:   "https://merchant.uz/payment/callback",
}, {
  headers: {
    'Content-Type':  'application/json',
    'Authorization': `Bearer ${bearerToken}`,
  }
});

console.log('Order ID:', result.data.order_id);
console.log('Pay URL:',  result.data.pay_url);
Response (Success)
JSON
{
  "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_url ga yo'naltiring → u to'lovni amalga oshiradi → webhook orqali bildirishnoma olasiz → order_id orqali holatni tekshirishingiz mumkin.

Webhook Xabarnomalar

To'lov muvaffaqiyatli bo'lganda avtomatik bildirishnoma

Muhim: To'lov amalga oshganda, inPAY.uz tizimi sizning callback_url manzilingizga POST so'rov yuboradi. Handler HTTP 200 bilan javob qaytarishi shart.
Jarayon
1
Foydalanuvchi to'lovni amalga oshiradi
Checkout sahifasida to'lov tugmasi bosiladi
2
inPAY.uz webhook yuboradi
Sizning callback_url ga POST so'rov keladi
3
Serveringiz JSON qabul qiladi
Ma'lumotlarni parse qiling va bazani yangilang
4
HTTP 200 "OK" qaytaring
Aks holda inPAY qayta urinib ko'radi
Webhook Ma'lumotlari
ParametrTipTavsif
amountstringTo'lov summasi (masalan: "15000.00")
statusstringTo'lov holati: success yoki failed
order_idstringBuyurtma identifikatori
transaction_idintegerinPAY.uz tizimidagi tranzaksiya ID
created_atstringYaratilgan vaqt (2025-12-10 05:14:52)
Webhook JSON namuna
JSON · POST body
{
  "amount":         "15000.00",
  "status":         "success",
  "order_id":       "1ff2f5a6d66f6e9c",
  "transaction_id": 149,
  "created_at":     "2025-12-10 05:14:52"
}
callback.php
<?php
// JSON ma'lumotlarni o'qish
$input = file_get_contents("php://input");
$data  = json_decode($input, true);

if (!$data) {
    http_response_code(400);
    exit('Invalid JSON');
}

$amount         = $data['amount'];
$status         = $data['status'];
$order_id       = $data['order_id'];
$transaction_id = $data['transaction_id'];

// Logga yozish (debugging)
file_put_contents('webhook_log.txt',
    date('Y-m-d H:i:s') . " - " . json_encode($data) . "\n",
    FILE_APPEND
);

if ($status === 'success') {
    include 'db.php';
    $stmt = $pdo->prepare("UPDATE orders SET status='paid', paid_at=NOW() WHERE order_id=?");
    $stmt->execute([$order_id]);
    // Email yuborish, SMS, servisni aktivlashtirish...
}

// inPAY.uz ga OK javob qaytarish (majburiy!)
http_response_code(200);
echo "OK";
?>
Express.js
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 } = req.body;
    console.log('Webhook:', req.body);

    if (status === 'success') {
      await db.query(
        'UPDATE orders SET status=? WHERE order_id=?',
        ['paid', order_id]
      );
      // Push notification, email, service aktivatsiya...
    }

    // Majburiy: HTTP 200 qaytarish
    res.status(200).send('OK');

  } catch (err) {
    console.error(err);
    res.status(500).send('Error');
  }
});
  • Webhook URL ni callback_url da yuboring — aks holda kassadagi default URL ishlatiladi
  • Handler JSON formatini qabul qilishi va HTTP 200 qaytarishi shart
  • Webhook URL HTTPS bo'lishi tavsiya etiladi

Tranzaksiya Holati

GET/transactions/?order_id={order_id}
ParametrTipMajburiyTavsif
order_idstring✓ HaTo'lov yaratishda qaytarilgan buyurtma ID
cURL
curl -X GET "https://inPAY.uz/api/v1/transactions/?order_id=1ff2f5a6d66f6e9c" \
  -H "Accept: application/json"
PHP
<?php
$order_id = "1ff2f5a6d66f6e9c";
$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL            => "https://inPAY.uz/api/v1/transactions/?order_id={$order_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => ['Accept: application/json'],
]);
$data = json_decode(curl_exec($curl), true);
curl_close($curl);

if ($data['success']) {
    echo "Status: "  . $data['status'];
    echo "Amount: "  . $data['amount'];
    echo "Paid at: " . $data['paid_at'];
}
?>
Pending
{
  "success":        true,
  "order_id":       "1ff2f5a6d66f6e9c",
  "status":         "pending",
  "amount":         15000,
  "payment_method": "click",
  "created_at":     "2025-12-10 05:14:52",
  "paid_at":        null
}
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
pending
To'lov kutilmoqda
success
To'lov muvaffaqiyatli
failed
To'lov muvaffaqiyatsiz
cancelled
To'lov bekor qilindi

Xato Kodlari

API dan qaytariladigan xato kodlari

Xato kodiHTTPTavsif
MISSING_AUTH_TOKEN401Authorization token topilmadi
INVALID_TOKEN401Bearer token noto'g'ri yoki muddati tugagan
MISSING_MERCHANT_ID400merchant_id parametri topilmadi
MERCHANT_NOT_FOUND404Merchant topilmadi
IP_NOT_WHITELISTED_STRICT403IP manzil whitelist da yo'q (Strict mode)
RATE_LIMIT_EXCEEDED429So'rovlar soni limitdan oshdi (100/soat)
CALLBACK_NOT_WHITELISTED403Callback URL whitelist da yo'q
MERCHANT_WEBSITE_NOT_WHITELISTED403Merchant website whitelist da active emas
AMOUNT_TOO_LOW400Summa juda kam (min: 1 000 so'm)
AMOUNT_TOO_HIGH400Summa maksimal limitdan oshdi
TRANSACTION_SAVE_FAILED500Tranzaksiya saqlanmadi (server xatosi)
Xato javob namunasi
JSON
{
  "success":    false,
  "message":    "* Minimal to'lov summasi 1000 so'm",
  "error_code": "AMOUNT_TOO_LOW"
}
  • Har doim success maydonini tekshiring, so'ng error_code asosida xatolarni boshqaring
  • 401/403 xatolarida autentifikatsiyani qayta tekshiring
  • 429 xatolarda biroz kuting va qayta urinib ko'ring
  • 500 xatolarida support bilan bog'laning: @merchants_uz

Xavfsizlik

IP Whitelist, Rate Limiting, Bearer Token

IP Whitelist rejimlari
strict
IP whitelist majburiy. Faqat ro'yxatdagi IP lardan so'rov qabul qilinadi.
optional
Whitelist ixtiyoriy. Barcha IP lardan so'rov qabul qilinadi.
disabled
IP tekshiruvi o'chirilgan. Test rejimi uchun.
Rate Limiting

Har bir IP manzil uchun soatiga 100 ta so'rov limiti. Limit oshirilsa, RATE_LIMIT_EXCEEDED xatosi qaytariladi.

Bearer Token xavfsizligi
  • Token 24 soat amal qiladi — keshda saqlang
  • Tokenni server-side saqlang, hech kimga bermang
  • Har bir so'rovda Authorization: Bearer {token} headerida yuboring
  • Muddati tugagandan so'ng yangi token oling
Domain Whitelist

Callback URL va merchant website whitelist da bo'lishi kerak. Sozlamalar uchun inPAY.uz platformasiga kiring.

Eng Yaxshi Amaliyotlar

Integratsiya sifatini oshirish uchun tavsiyalar

Bearer tokenni keshda saqlang
Har so'rovda yangi token olish o'rniga, tokenni 24 soat davomida keshda saqlang va muddati tugaganda yangilang. Bu rate limit ni tejaydi.
Webhook dan foydalaning
To'lov holatini doimiy polling qilish o'rniga webhook orqali real-time bildirishnomalarni qabul qiling. Bu aniqroq va tejamkor.
Xatolarni to'g'ri boshqaring
Har doim error_code ni tekshiring va foydalanuvchiga tushunarli xabar ko'rsating. Barcha so'rovlarni loglang.
Tranzaksiyalarni bazada saqlang
order_id va tranzaksiya ma'lumotlarini o'z bazangizda saqlang. Webhook kelganda bazani yangilang — ikki marta tekshiring.
HTTPS dan foydalaning
Webhook URL va callback URL lar HTTPS protokolida bo'lishi kerak. HTTP so'rovlar rad etiladi.
Test muhitida sinab ko'ring
Production ga o'tishdan oldin barcha funksiyalarni test muhitida sinab ko'ring: to'lov yaratish, webhook, status tekshirish.