🔐 Autentifikatsiya
API dan foydalanish uchun sizga Shop ID va Secret Key kerak. Bu ma'lumotlar bot orqali kassa yaratganingizda beriladi.
📌 Eslatma: Barcha so'rovlarda
X-Signature headeri yoki signature parametri talab qilinadi.
Signature yaratish:
// PHP da signature yaratish
$shop_id = "1734567890123";
$secret_key = "your_secret_key_here";
$signature = hash_hmac('sha256', $shop_id, $secret_key);
// cURL da ishlatish
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'X-Shop-Id: ' . $shop_id,
'X-Signature: ' . $signature
]);
💳 To'lov yaratish
Yangi to'lov yaratish uchun ushbu API dan foydalaning.
POST
https://checkout.knyazuz.ru/api.php?action=create
So'rov parametrlari:
| Parametr | Tur | Majburiy | Tavsif |
|---|---|---|---|
| shop_id | string | ✅ Ha | Sizning shop ID |
| signature | string | ✅ Ha | HMAC-SHA256 signature |
| amount | float | ✅ Ha | To'lov summasi (min 1000 UZS) |
| order_id | string | ❌ Yo'q | Sizning order ID (default: uniqid) |
cURL misoli:
curl -X POST "https://checkout.knyazuz.ru/api.php?action=create" \
-H "Content-Type: application/json" \
-H "X-Shop-Id: YOUR_SHOP_ID" \
-H "X-Signature: YOUR_SIGNATURE" \
-d '{
"amount": 50000,
"order_id": "ORDER_12345"
}'
PHP misoli:
<?php
$shop_id = "YOUR_SHOP_ID";
$secret_key = "YOUR_SECRET_KEY";
$signature = hash_hmac('sha256', $shop_id, $secret_key);
$ch = curl_init("https://checkout.knyazuz.ru/api.php?action=create");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'amount' => 50000,
'order_id' => 'ORDER_12345'
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'X-Shop-Id: ' . $shop_id,
'X-Signature: ' . $signature
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
?>
Javob:
{
"status": "ok",
"payment_id": "1734567890123456",
"amount": 50000,
"expires": "2024-01-15 12:00:00"
}
🔍 To'lov tekshirish
To'lov statusini tekshirish uchun ushbu API dan foydalaning.
GET
https://checkout.knyazuz.ru/api.php?action=check
So'rov parametrlari:
| Parametr | Tur | Majburiy | Tavsif |
|---|---|---|---|
| shop_id | string | ✅ Ha | Sizning shop ID |
| signature | string | ✅ Ha | HMAC-SHA256 signature |
| payment_id | string | ✅ Ha | To'lov ID |
cURL misoli:
curl -X GET "https://checkout.knyazuz.ru/api.php?action=check&shop_id=YOUR_SHOP_ID&signature=YOUR_SIGNATURE&payment_id=PAYMENT_ID"
PHP misoli:
<?php
$shop_id = "YOUR_SHOP_ID";
$secret_key = "YOUR_SECRET_KEY";
$payment_id = "PAYMENT_ID";
$signature = hash_hmac('sha256', $shop_id, $secret_key);
$url = "https://checkout.knyazuz.ru/api.php?action=check&shop_id=$shop_id&signature=$signature&payment_id=$payment_id";
$response = file_get_contents($url);
$data = json_decode($response, true);
print_r($data);
?>
Javob:
{
"status": "ok",
"payment_status": "completed",
"amount": 50000,
"order_id": "ORDER_12345"
}
💰 Balans tekshirish
Bot egasining balansini tekshirish (Signature talab qilinmaydi).
GET
https://checkout.knyazuz.ru/api.php?action=balance
So'rov parametrlari:
| Parametr | Tur | Majburiy | Tavsif |
|---|---|---|---|
| user_id | string | ✅ Ha | Telegram user ID |
cURL misoli:
curl -X GET "https://checkout.knyazuz.ru/api.php?action=balance&user_id=123456789"
Javob:
{
"status": "ok",
"balance": 1250000.50
}
⚡ Webhook
To'lov kelganda sizning serveringizga avtomatik xabar yuboriladi.
📌 Webhook URL format: Botda "⚡ Webhook" tugmasi orqali o'z URL manzilingizni sozlashingiz mumkin.
Webhook so'rov formati:
{
"payment_id": "1734567890123456",
"user_id": "123456789",
"amount": 50000,
"card_last4": "0356",
"time": "2024-01-15 17:53:00",
"raw_text": "🎉 To'ldirish ➕ 50.000,00 UZS...",
"status": "completed",
"created_at": "2024-01-15 17:53:00"
}
Webhook qabul qiluvchi PHP skript:
<?php
// webhook.php
$data = json_decode(file_get_contents('php://input'), true);
$payment_id = $data['payment_id'];
$amount = $data['amount'];
$card_last4 = $data['card_last4'];
// To'lovni o'z bazangizga saqlash
file_put_contents("payment_$payment_id.json", json_encode($data));
// Yoki ma'lumotlar bazasiga yozish
// $db->query("INSERT INTO payments ...");
// Telegram botga xabar yuborish (ixtiyoriy)
// file_get_contents("https://api.telegram.org/botTOKEN/sendMessage?chat_id=ID&text=Yangi to'lov: $amount UZS");
http_response_code(200);
echo json_encode(['status' => 'ok']);
?>
📝 Kod misollari
Python misoli:
import requests
import hmac
import hashlib
import json
shop_id = "YOUR_SHOP_ID"
secret_key = "YOUR_SECRET_KEY"
signature = hmac.new(secret_key.encode(), shop_id.encode(), hashlib.sha256).hexdigest()
# To'lov yaratish
url = "https://checkout.knyazuz.ru/api.php?action=create"
headers = {
"Content-Type": "application/json",
"X-Shop-Id": shop_id,
"X-Signature": signature
}
data = {"amount": 50000, "order_id": "ORDER123"}
response = requests.post(url, headers=headers, json=data)
print(response.json())
# To'lov tekshirish
check_url = f"https://checkout.knyazuz.ru/api.php?action=check&shop_id={shop_id}&signature={signature}&payment_id=PAYMENT_ID"
response = requests.get(check_url)
print(response.json())
JavaScript/Node.js misoli:
const crypto = require('crypto');
const axios = require('axios');
const shop_id = "YOUR_SHOP_ID";
const secret_key = "YOUR_SECRET_KEY";
const signature = crypto.createHmac('sha256', secret_key).update(shop_id).digest('hex');
// To'lov yaratish
async function createPayment() {
try {
const response = await axios.post(
'https://checkout.knyazuz.ru/api.php?action=create',
{ amount: 50000, order_id: 'ORDER123' },
{
headers: {
'Content-Type': 'application/json',
'X-Shop-Id': shop_id,
'X-Signature': signature
}
}
);
console.log(response.data);
} catch(error) {
console.error(error);
}
}
createPayment();
JavaScript (Frontend) misoli:
// Frontend da to'lov yaratish (Server orqali)
fetch('/api/create_payment.php', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
amount: 50000,
order_id: 'ORDER_' + Date.now()
})
})
.then(response => response.json())
.then(data => {
if(data.status === 'ok') {
console.log('To\'lov yaratildi:', data.payment_id);
// To'lov statusini kuzatish
checkPayment(data.payment_id);
}
});
function checkPayment(payment_id) {
setInterval(() => {
fetch(`/api/check_payment.php?payment_id=${payment_id}`)
.then(res => res.json())
.then(data => {
if(data.payment_status === 'completed') {
console.log('To\'lov tugallandi!');
// Muvaffaqiyatli sahifaga o'tish
window.location.href = '/success.html';
}
});
}, 3000);
}
❌ Xatoliklar
API dan kelishi mumkin bo'lgan xatoliklar:
| HTTP Code | Xatolik | Tavsif |
|---|---|---|
| 400 | Invalid signature | Signature noto'g'ri |
| 400 | Shop not found | Shop ID topilmadi |
| 400 | Minimal 1000 UZS | Summa juda kichik |
| 404 | Payment not found | To'lov topilmadi |
| 500 | Internal server error | Server xatoligi |
Xatolik javobi formati:
{
"status": "error",
"error": "Xatolik haqida ma'lumot"
}
🚀 To'liq ishlaydigan misol
<?php
// complete_example.php
class HumoCardAPI {
private $shop_id;
private $secret_key;
private $api_url;
public function __construct($shop_id, $secret_key) {
$this->shop_id = $shop_id;
$this->secret_key = $secret_key;
$this->api_url = "https://checkout.knyazuz.ru";
}
private function getSignature() {
return hash_hmac('sha256', $this->shop_id, $this->secret_key);
}
public function createPayment($amount, $order_id = null) {
$order_id = $order_id ?? uniqid();
$signature = $this->getSignature();
$ch = curl_init($this->api_url . "/api.php?action=create");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'amount' => $amount,
'order_id' => $order_id
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'X-Shop-Id: ' . $this->shop_id,
'X-Signature: ' . $signature
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
return json_decode($response, true);
}
public function checkPayment($payment_id) {
$signature = $this->getSignature();
$url = $this->api_url . "/api.php?action=check&shop_id={$this->shop_id}&signature={$signature}&payment_id={$payment_id}";
$response = file_get_contents($url);
return json_decode($response, true);
}
}
// Ishlatish
$api = new HumoCardAPI("YOUR_SHOP_ID", "YOUR_SECRET_KEY");
// To'lov yaratish
$payment = $api->createPayment(50000, "ORDER_123");
if($payment['status'] == 'ok') {
echo "To'lov ID: " . $payment['payment_id'] . "\n";
// 10 sekund kutib, tekshirish
sleep(10);
$check = $api->checkPayment($payment['payment_id']);
if($check['payment_status'] == 'completed') {
echo "To'lov tugallandi! Summa: " . $check['amount'] . " UZS\n";
}
}
?>