MixPay API

Oddiy REST API: JSON yuborasiz, JSON olasiz. Asosiy manzil:

https://mixpay.nurlihost.uz/api/v1

Ulanish tartibi:

1. Panelda kassa oching. Test kalit (mp_test_) darhol ishlaydi.
2. POST /payments bilan to'lov yarating va mijozni pay_url ga yuboring.
3. Mijoz Click, Payme, Paynet yoki Alif orqali to'laydi.
4. Serveringizga payment.paid webhook keladi. Ixtiyoriy ravishda GET /payments/{id} bilan tekshiring.

Kassa admin tomonidan tasdiqlangach jonli kalit (mp_live_) ham ishlay boshlaydi.

Autentifikatsiya

Har bir so'rovga API kalitni Authorization sarlavhasida qo'shing:

Authorization: Bearer mp_live_XXXXXXXXXXXXXXXX

Kalit faqat yaratilgan paytda bir marta ko'rsatiladi. Uni faqat serveringizda saqlang, brauzer yoki mobil ilova kodiga qo'ymang. Kalit oshkor bo'lsa, panelda darhol yangilang.

Limit: bir kassaga daqiqasiga 120 ta so'rov.

To'lov yaratish

curl -X POST https://mixpay.nurlihost.uz/api/v1/payments \
  -H "Authorization: Bearer mp_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50000, "order_id": "1024", "description": "Buyurtma #1024"}'

Javob (201)

{
  "id": "pay_8f2c1e0b9a7d6c5e4f3a",
  "number": 10000042,
  "kassa_id": 7,
  "order_id": "1024",
  "amount": 50000,
  "commission": 0,
  "net_amount": 0,
  "status": "created",
  "provider": null,
  "description": "Buyurtma #1024",
  "test": false,
  "pay_url": "https://mixpay.nurlihost.uz/pay/pay_8f2c1e0b9a7d6c5e4f3a",
  "created_at": "2026-10-29T18:00:00+00:00",
  "paid_at": null,
  "expires_at": "2026-10-29T19:00:00+00:00"
}

To'lov 60 daqiqa davomida amal qiladi, keyin expired bo'ladi.

To'lov holati

id o'rniga 8 xonali number ham ishlatish mumkin.

paid holatida commission (2.5%) va net_amount (balansingizga yozilgan summa) ham qaytadi.

To'lovlar ro'yxati

Javob: {"count", "limit", "offset", "results": [...]}

Bekor qilish

Faqat created holatidagi to'lovni bekor qilish mumkin.

Balans

{ "kassa_id": 7, "name": "Do'konim", "status": "active", "balance": 975000, "commission_percent": "2.50", "test": false }

Webhook

Kassa sozlamalarida Callback URL kiriting (faqat https://). To'lov holati o'zgarganda shu manzilga POST yuboriladi:

POST https://sizning-sayt.uz/mixpay/webhook
Content-Type: application/json
X-MixPay-Event: payment.paid
X-MixPay-Kassa: 7
X-MixPay-Timestamp: 1761760800
X-MixPay-Signature: sha256=5f2b...

{"event":"payment.paid","data":{"id":"pay_8f2c...","order_id":"1024","amount":50000,"status":"paid", ...}}

Hodisalar: payment.paid, payment.cancelled, payment.expired, payment.refunded.

Imzoni tekshirish (majburiy)

Imzo = HMAC_SHA256(webhook_secret, timestamp + "." + body). Tekshirishda xom (raw) body ishlatiladi. Vaqt farqi 5 daqiqadan oshsa so'rovni rad eting.

<?php
$secret = "whsec_XXXX";                       // kassa sozlamalaridagi webhook secret
$body = file_get_contents("php://input");
$ts   = $_SERVER["HTTP_X_MIXPAY_TIMESTAMP"] ?? "";
$sig  = $_SERVER["HTTP_X_MIXPAY_SIGNATURE"] ?? "";

$expected = "sha256=" . hash_hmac("sha256", $ts . "." . $body, $secret);
if (!hash_equals($expected, $sig) || abs(time() - (int)$ts) > 300) {
    http_response_code(401); exit;
}
$event = json_decode($body, true);
if ($event["event"] === "payment.paid") {
    $orderId = $event["data"]["order_id"];
    // buyurtmani to'langan deb belgilang (bir necha marta kelsa ham bir marta bajaring)
}
http_response_code(200);
echo "ok";

Qayta yuborish

Serveringiz 2xx qaytarmasa, xabar 1 daq, 5 daq, 30 daq, 2 soat va 6 soatdan keyin qayta yuboriladi. Bir xabar bir necha marta kelishi mumkin, shuning uchun buyurtmani id bo'yicha bir marta bajaring.

Test rejimi

mp_test_ kalit bilan yaratilgan to'lovning sahifasida "Test: to'landi" va "Test: rad etildi" tugmalari chiqadi. Webhook va holatlar haqiqiydagidek ishlaydi, lekin balansga pul yozilmaydi. Test va jonli to'lovlar bir-biridan ajratilgan.

Xatolar

Xato bo'lsa HTTP kodi 4xx/5xx bo'ladi, javob tanasi esa doim bir xil shaklda keladi:

{
  "error": {
    "code": "validation_error",
    "message": "Minimal summa 1000 so'm",
    "fields": { "amount": ["Minimal summa 1000 so'm"] }
  }
}