inPAY API Hujjatlari
v1.0 · Stable Yordam
Developer Documentation

To'lovlarni qabul qiling — bir necha daqiqada

inPAY REST API merchantlarga to'lov tranzaksiyalarini xavfsiz va tezkor yaratish imkoniyatini beradi. RESTful arxitektura, JSON format, Bearer Token autentifikatsiya.

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

Tezkor boshlash

5 daqiqada to'lov qabul qilishni boshlang

1
Hisob ma'lumotlarini oling
inPAY platformasida ro'yxatdan o'ting va kassa yarating. Tasdiqlangach merchant_id va merchant_token oling.
2
Bearer token oling
GET /authorization/ chaqirib 24 soatlik tokenni oling.
3
To'lov yarating
POST /create/ orqali tranzaksiya yarating va pay_url oling.
4
Foydalanuvchini yo'naltiring
Mijozni pay_url ga yuboring — u to'lovni amalga oshiradi.
5
Webhookni qabul qiling
callback_url ga POST so'rov keladi — bazani yangilang va HTTP 200 qaytaring.

Autentifikatsiya

24 soatlik Bearer token olish

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 parametrlari
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=...',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => ['Accept: application/json'],
]);
$res = json_decode(curl_exec($curl), true);
curl_close($curl);

// Tokenni keshda saqlang (24 soat)
apcu_store('inpay_token', $res['bearer_token'], 86400);
Python
import requests

r = requests.get(
    "https://inpay.uz/api/v1/authorization/",
    params={"merchant_id": 1353, "merchant_token": "..."},
    headers={"Accept": "application/json"},
    timeout=10,
)
token = r.json()["bearer_token"]
# Save token to cache for 24 hours
Muvaffaqiyatli javob
JSON · 200 OK
{
  "success": true,
  "bearer_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
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

Yangi tranzaksiyani boshlash

POST/create/

Yangi to'lov tranzaksiyasini yaratish. Muvaffaqiyatli bo'lsa foydalanuvchini pay_url ga yo'naltiring. Endpoint oxirida / belgisi shart.

Headers
HTTP
Content-Type: application/json
Authorization: Bearer {your_bearer_token}
Body (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":    "Order #12345",
    "payment_method": "click",
    "phone":          "998901234567",
    "callback_url":   "https://merchant.uz/payment/callback"
  }'
PHP
<?php
$payload = [
  'merchant_id'    => '1353',
  'token'          => '6a7bf375b302cfcda6692e6f60402cb3',
  'amount'         => 15000,
  'description'    => 'Order #12345',
  'payment_method' => 'click',
  'phone'          => '998901234567',
  'callback_url'   => 'https://merchant.uz/payment/callback',
];

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

if ($res['success']) {
  header('Location: ' . $res['pay_url']);
  exit;
}
Node.js / axios
const axios = require('axios');

const { data } = await axios.post('https://inpay.uz/api/v1/create/', {
  merchant_id:    '1353',
  token:          '6a7bf375b302cfcda6692e6f60402cb3',
  amount:         15000,
  description:    'Order #12345',
  payment_method: 'click',
  phone:          '998901234567',
  callback_url:   'https://merchant.uz/payment/callback',
}, {
  headers: {
    'Content-Type':  'application/json',
    'Authorization': `Bearer ${bearerToken}`,
  },
});

console.log('order_id:', data.order_id);
console.log('pay_url: ', data.pay_url);
Python
import requests

payload = {
    "merchant_id":    "1353",
    "token":          "6a7bf375b302cfcda6692e6f60402cb3",
    "amount":         15000,
    "description":    "Order #12345",
    "payment_method": "click",
    "phone":          "998901234567",
    "callback_url":   "https://merchant.uz/payment/callback",
}
r = requests.post(
    "https://inpay.uz/api/v1/create/",
    json=payload,
    headers={"Authorization": f"Bearer {bearer_token}"},
    timeout=15,
)
data = r.json()
print(data["pay_url"])
Muvaffaqiyatli javob
JSON · 200 OK
{
  "success":  true,
  "order_id": "1ff2f5a6d66f6e9c",
  "pay_url":  "https://inpay.uz/checkout/1ff2f5a6d66f6e9c",
  "phone":    "998901234567",
  "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.

Tranzaksiya holati

order_id orqali holatni tekshirish

GET/transactions/?order_id=...
Query parametrlari
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
$orderId = '1ff2f5a6d66f6e9c';
$ch = curl_init();
curl_setopt_array($ch, [
  CURLOPT_URL            => "https://inpay.uz/api/v1/transactions/?order_id={$orderId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => ['Accept: application/json'],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

// $data['status'] => pending | success | failed | cancelled
Misol
JSON · 200 OK
{
  "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

Webhook bildirishnomalar

To'lov holati o'zgarganda real-time xabar

Muhim: To'lov amalga oshganda, inPAY 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 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 (JSON)
ParametrTipTavsif
amountstringTo'lov summasi (masalan: "15000.00")
statusstringTo'lov holati: success yoki failed
order_idstringBuyurtma identifikatori
transaction_idintegerinPAY tizimidagi tranzaksiya ID
created_atstringYaratilgan vaqt (ISO format)
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
$input = file_get_contents('php://input');
$data  = json_decode($input, true);

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

if (($data['status'] ?? '') === 'success') {
  // Update order in your DB
  $pdo->prepare('UPDATE orders SET status=?, paid_at=NOW() WHERE order_id=?')
      ->execute(['paid', $data['order_id']]);
}

// Always respond 200 OK
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) => {
  const { amount, status, order_id, transaction_id } = req.body;

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

  res.status(200).send('OK');
});
Flask
from flask import Flask, request

app = Flask(__name__)

@app.route("/payment/callback", methods=["POST"])
def callback():
    data = request.get_json(silent=True) or {}

    if data.get("status") == "success":
        # update DB
        mark_paid(data["order_id"])

    return "OK", 200
  • 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

Xato kodlari

API javob xatolari va ularning ma'nosi

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 javobi 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 xatolarida biroz kuting va qayta urinib ko'ring
  • 500 xatolarida support bilan bog'laning: @merchants_uz

Xavfsizlik

IP Whitelist, Rate Limiting va token himoyasi

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 so'rovda Authorization: Bearer {token} headerini yuboring
  • Muddati tugagandan so'ng yangi token oling
Domain Whitelist

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

Eng yaxshi amaliyotlar

Ishonchli integratsiya uchun tavsiyalar

Bearer tokenni keshda saqlang
Har so'rovda yangi token olish o'rniga, tokenni 24 soat davomida keshda saqlang va muddati tugaganda yangilang.
Webhookdan 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.
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.