Webhooklar va imzoni tekshirish
Webhook manzilini ulash, hodisalar, MirPay-Signature imzosini tekshirish va qayta yuborish tartibi.
Shu sahifada
Webhook — toʻlov holati oʻzgarganda MirPay serveringizga yuboradigan HTTP soʻrov. Roʻyxatlarni tez-tez soʻrab turish oʻrniga webhooklarga tayaning.
Webhook manzilini qoʻshish
- Dasturchilar → Webhooklar sahifasini oching (kerakli rejimda — Test yoki Live).
- Manzil qoʻshish tugmasini bosing.
- Manzil (URL) ni kiriting. Live rejimda faqat HTTPS; ichki tarmoq va localhost manzillari qabul qilinmaydi.
- Barcha hodisalar yoki Tanlangan hodisalar ni belgilang va Saqlash tugmasini bosing.
- Manzil sahifasida Imzo sirini koʻrsatish orqali
whsec_…sirini oling va serveringizda saqlang.
Har bir rejimda koʻpi bilan 10 ta manzil. Manzillarni API orqali ham boshqarish mumkin: /api/v3/webhook_endpoints. Live hodisalar kassaning barcha toʻlovlari uchun yuboriladi, v2 orqali yaratilganlari ham.
Test hodisa yuborish tugmasi serveringizga webhook.test hodisasini yuboradi — javob Yetkazishlar roʻyxatida koʻrinadi.
Hodisalar
| Hodisa | Qachon |
|---|---|
payment.succeeded |
Toʻlov muvaffaqiyatli oʻtdi. |
payment.failed |
Toʻlov amalga oshmadi. |
payment.canceled |
Toʻlov API orqali yoki mijoz tomonidan bekor qilindi. |
payment.expired |
Toʻlov muddati oʻtdi. |
Kelajakda yangi turlar qoʻshilishi mumkin: notanish turlarni eʼtiborsiz qoldiring, lekin baribir 2xx qaytaring.
Soʻrov koʻrinishi
MirPay-Signature: t=<unix>,v1=<hex>
MirPay-Event-Id: evt_...
MirPay-Event-Type: payment.succeeded
MirPay-Delivery-Id: whd_...
Content-Type: application/json
Tana (event):
{
"id": "evt_...",
"object": "event",
"type": "payment.succeeded",
"livemode": true,
"created": 1731234567,
"api_version": "2026-11-11",
"data": { "object": { "id": "...", "object": "payment", "status": "succeeded", "...": "..." } }
}
Imzoni tekshirish
MirPay-Signaturesarlavhasini vergul boʻyicha ajrating:t— vaqt,v1— imzo (bir nechta boʻlishi mumkin).t + "." + xom_tanasatrini tuzing va sir bilan HMAC-SHA256 (hex) hisoblang.- Natijani har bir
v1bilan doimiy vaqtli taqqoslash orqali solishtiring. tjoriy vaqtdan 300 soniyadan koʻp farq qilsa, soʻrovni rad eting.
Imzoni xom soʻrov tanasi boʻyicha hisoblang — freymvork JSONʼni qayta kodlasa, imzo mos kelmaydi.
<?php
$secret = getenv("MIRPAY_WEBHOOK_SECRET"); // whsec_...
$body = file_get_contents("php://input");
$header = $_SERVER["HTTP_MIRPAY_SIGNATURE"] ?? "";
$t = 0; $sigs = [];
foreach (explode(",", $header) as $pair) {
[$k, $v] = array_pad(explode("=", trim($pair), 2), 2, "");
if ($k === "t") $t = (int) $v;
if ($k === "v1") $sigs[] = $v;
}
$expected = hash_hmac("sha256", $t . "." . $body, $secret);
$valid = $t > 0 && abs(time() - $t) <= 300;
$valid = $valid && array_filter($sigs, fn ($s) => hash_equals($expected, $s));
if (!$valid) { http_response_code(400); exit; }
$event = json_decode($body, true);
if ($event["type"] === "payment.succeeded") {
$payment = $event["data"]["object"];
// $payment["id"], $payment["order_id"], $payment["amount"]
}
http_response_code(200);
Javob va qayta yuborish
- 10 soniya ichida istalgan
2xxbilan javob bering. Yoʻnaltirishlar (3xx) kuzatilmaydi va xato hisoblanadi. Ogʻir ishni javobdan keyin bajaring. 2xxkelmasa, qayta yuboriladi: darhol, keyin 1 daq, 5 daq, 30 daq, 2 soat, 6 soat, 12 soat, 24 soat — jami 8 urinish (taxminan 3 kun). Shundan keyin yetkazishfailedboʻladi.- Bir hodisa bir necha marta kelishi mumkin —
MirPay-Event-Idni saqlab, takrorlarini oʻtkazib yuboring. - Hodisalar tartibi kafolatlanmaydi; muhim amaldan oldin obyektni
GETbilan qayta oling. - Oʻtkazib yuborilgan hodisalarni
GET /api/v3/eventsorqali olish mumkin (30 kun saqlanadi).
Avtomatik oʻchirish: manzilga 72 soat davomida birorta ham muvaffaqiyatli yetkazish boʻlmasa, u Oʻchirilgan holatiga oʻtadi va hodisa olmay qoʻyadi. Muammoni tuzatgach, manzil sahifasida Qayta yoqish tugmasini bosing. Yetkazilmagan hodisani Qayta yuborish tugmasi bilan qoʻlda yuborish mumkin.
Sir sizib chiqsa — Sirni almashtirish (eski sir darhol ishlamay qoladi).
Eski callback (v1/v2)
v1/v2 callbacki oʻzgarishsiz ishlaydi va v3 webhooklariga qoʻshimcha ravishda yuborilaveradi. U kassa sozlamalaridagi Webhook manziliga application/x-www-form-urlencoded POST qilinadi va Callback maxfiy kaliti bilan imzolanadi (sir: Virtual kassa → Batafsil → Kalitlar):
X-MirPay-Kassa-Id: <kassa ID>
X-MirPay-Timestamp: <unix>
X-MirPay-Signature: <hex>
signature = HMAC_SHA256(timestamp + "." + raw_body, callback_secret)
Callback muvaffaqiyatsiz boʻlsa, 5 martagacha qayta yuboriladi — ishlov beruvchingiz bir xil payid ikki marta kelganda buyurtmani ikki marta bajarmasligi kerak.