🏪 HumoCard Kassa API

To'lovlarni qabul qilish uchun kuchli va xavfsiz API

Version 1.0 | Active

🔐 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:

ParametrTurMajburiyTavsif
shop_idstring✅ HaSizning shop ID
signaturestring✅ HaHMAC-SHA256 signature
amountfloat✅ HaTo'lov summasi (min 1000 UZS)
order_idstring❌ Yo'qSizning 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:

ParametrTurMajburiyTavsif
shop_idstring✅ HaSizning shop ID
signaturestring✅ HaHMAC-SHA256 signature
payment_idstring✅ HaTo'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:

ParametrTurMajburiyTavsif
user_idstring✅ HaTelegram 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 CodeXatolikTavsif
400Invalid signatureSignature noto'g'ri
400Shop not foundShop ID topilmadi
400Minimal 1000 UZSSumma juda kichik
404Payment not foundTo'lov topilmadi
500Internal server errorServer 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";
    }
}
?>