Asosiy qismga oʻtish

2-bob · API integratsiya

Webhooklar va imzoni tekshirish

Webhook manzilini ulash, hodisalar, MirPay-Signature imzosini tekshirish va qayta yuborish tartibi.

3 daqiqada oʻqiladi

Shu sahifada
  1. Webhook manzilini qoʻshish
  2. Hodisalar
  3. Soʻrov koʻrinishi
  4. Imzoni tekshirish
  5. Javob va qayta yuborish
  6. Eski callback (v1/v2)

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

  1. Dasturchilar → Webhooklar sahifasini oching (kerakli rejimda — Test yoki Live).
  2. Manzil qoʻshish tugmasini bosing.
  3. Manzil (URL) ni kiriting. Live rejimda faqat HTTPS; ichki tarmoq va localhost manzillari qabul qilinmaydi.
  4. Barcha hodisalar yoki Tanlangan hodisalar ni belgilang va Saqlash tugmasini bosing.
  5. 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

  1. MirPay-Signature sarlavhasini vergul boʻyicha ajrating: t — vaqt, v1 — imzo (bir nechta boʻlishi mumkin).
  2. t + "." + xom_tana satrini tuzing va sir bilan HMAC-SHA256 (hex) hisoblang.
  3. Natijani har bir v1 bilan doimiy vaqtli taqqoslash orqali solishtiring.
  4. t joriy 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 2xx bilan javob bering. Yoʻnaltirishlar (3xx) kuzatilmaydi va xato hisoblanadi. Ogʻir ishni javobdan keyin bajaring.
  • 2xx kelmasa, 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 yetkazish failed boʻladi.
  • Bir hodisa bir necha marta kelishi mumkin — MirPay-Event-Id ni saqlab, takrorlarini oʻtkazib yuboring.
  • Hodisalar tartibi kafolatlanmaydi; muhim amaldan oldin obyektni GET bilan qayta oling.
  • Oʻtkazib yuborilgan hodisalarni GET /api/v3/events orqali 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.

Maqola foydali boʻldimi?

Javob topmadingizmi?

Murojaat yuboring — mutaxassis hisobingizni koʻrib, javob beradi.