inPAY.uz API

Raqamli to'lovlar uchun ishonchli API integratsiya

Version
v1.0

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.

🔒 Xavfsizlik
Bearer Token autentifikatsiya
⚡ Tezlik
Real-time to'lov jarayoni
🔔 Webhook
Avtomatik bildirishnomalar

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.

GET

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.

POST

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:

  1. Foydalanuvchini pay_url ga yo'naltiring
  2. Foydalanuvchi to'lovni amalga oshiradi
  3. To'lov muvaffaqiyatli bo'lsa, webhook orqali bildirishnoma olasiz
  4. order_id orqali to'lov holatini tekshirishingiz mumkin
WEBHOOK

Webhook xabarnomalar

Muhim: To'lov muvaffaqiyatli amalga oshganda, inPAY.uz tizimi sizning callback_url manzilingizga POST so'rov yuboradi.

Webhook qanday ishlaydi:

  1. Foydalanuvchi to'lovni muvaffaqiyatli amalga oshiradi
  2. inPAY.uz tizimi sizning callback_url ga POST so'rov yuboradi
  3. Sizning serveringiz JSON ma'lumotlarni qabul qiladi
  4. Buyurtma holatini yangilaysiz
  5. 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
GET

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:

pending
To'lov kutilmoqda
success
To'lov muvaffaqiyatli
failed
To'lov muvaffaqiyatsiz
cancelled
To'lov bekor qilindi

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 success maydonini tekshiring
  • 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

Xavfsizlik

🔐 IP Whitelist

inPAY.uz uchta IP whitelist rejimini qo'llab-quvvatlaydi:

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 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.