API v3 orqali toʻlov yaratish
POST /payments soʻrovi, maydonlar, javob, idempotentlik va xatolar.
Shu sahifada
API v3 — REST API: JSON soʻrov va javoblar, standart HTTP kodlari. Toʻliq hujjat: https://mirpay.uz/api-docs.
Asosiy qoidalar
- Asosiy manzil:
https://mirpay.uz/api/v3. Faqat HTTPS. - Har bir soʻrovda sarlavha:
Authorization: Bearer sk_test_…(yokisk_live_…). - Summalar butun son, soʻmda:
250000= 250 000 soʻm. Valyuta faqatUZS. - Kalitni faqat serverda ishlating — APIʼni brauzer yoki mobil ilovadan toʻgʻridan-toʻgʻri chaqirmang.
- Cheklov: bitta kalit uchun daqiqasiga 300 soʻrov. Oshsa —
429vaRetry-Aftersarlavhasi.
Endpointlar
POST /api/v3/payments — create a payment
GET /api/v3/payments/{id} — retrieve a payment
GET /api/v3/payments — list payments
POST /api/v3/payments/{id}/cancel — cancel a pending payment
GET /api/v3/balance — cashbox balance
Toʻlov yaratish
- Serveringizdan
POST /api/v3/paymentsyuboring. - Javobdagi
checkout_urlga mijozni yoʻnaltiring. - Natijani webhook (
payment.succeeded) yokiGET /api/v3/payments/{id}orqali tekshiring.
curl https://mirpay.uz/api/v3/payments \
-H "Authorization: Bearer sk_test_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1001" \
-d '{
"amount": 250000,
"description": "Order #1001",
"order_id": "1001",
"return_url": "https://example.com/pay/return",
"cancel_url": "https://example.com/pay/cancel",
"metadata": {"customer_id": "42"}
}'
| Maydon | Majburiy | Tavsif |
|---|---|---|
amount |
ha | Summa soʻmda, butun son, 1 000 dan 100 000 000 gacha. Live rejimda kassaning bitta tranzaksiya va kunlik limitlari ham tekshiriladi. |
description |
ha | Tavsif, 255 belgigacha. Toʻlov sahifasida mijozga koʻrsatiladi. |
order_id |
yoʻq | Buyurtma raqamingiz, 128 belgigacha. Unikalligi tekshirilmaydi. |
return_url |
yoʻq | Muvaffaqiyatli toʻlovdan keyin mijoz qaytadigan manzil. Live rejimda faqat https. |
cancel_url |
yoʻq | Muvaffaqiyatsiz yoki bekor qilingan toʻlovdan keyingi manzil. Berilmasa — return_url. |
expires_in |
yoʻq | Toʻlov amal qilish muddati, soniyada. Live: 300–900 (standart 900). Test: 300–86 400 (standart 1 800). |
metadata |
yoʻq | Oʻz maʼlumotlaringiz: 20 tagacha kalit, kalit 40 belgigacha, qiymat 500 belgigacha. Ichma-ich obyekt qabul qilinmaydi. |
currency |
yoʻq | Faqat UZS. |
Javob — 201 va payment obyekti:
{
"id": "test_6f1c2d3e-0000-0000-0000-000000000000",
"object": "payment",
"livemode": false,
"status": "pending",
"amount": 250000,
"currency": "UZS",
"description": "Order #1001",
"order_id": "1001",
"metadata": {"customer_id": "42"},
"checkout_url": "https://mirpay.uz/sandbox/pay/test_6f1c2d3e-0000-0000-0000-000000000000",
"return_url": "https://example.com/pay/return",
"cancel_url": "https://example.com/pay/cancel",
"card": null,
"failure": null,
"receipt_url": null,
"created_at": "2026-11-11T10:15:00+05:00",
"expires_at": "2026-11-11T10:45:00+05:00",
"paid_at": null,
"canceled_at": null
}
Takroriy toʻlovdan himoya (Idempotency-Key)
Har bir yaratish soʻroviga Idempotency-Key sarlavhasini qoʻshing (255 belgigacha, masalan UUID yoki buyurtma raqami). Javob yoʻqolsa, soʻrovni aynan shu kalit bilan qayta yuboring — ikkinchi toʻlov yaratilmaydi, asl javob qaytadi (Idempotent-Replayed: true). Kalitlar 24 soatdan keyin oʻchiriladi.
Toʻlovni bekor qilish
POST /api/v3/payments/{id}/cancel — faqat pending holatidagi toʻlov uchun. Aks holda 400 payment_not_cancelable. API v3 da qaytarish (refund) yoʻq.
Roʻyxat
GET /api/v3/payments — eng yangilari birinchi. Parametrlar: limit (1–100, standart 10), starting_after, ending_before, filtrlar status, order_id, created[gte], created[lte] (Unix soniya).
Xatolar
Xato boʻlsa, javob har doim bir xil shaklda keladi:
{
"error": {
"type": "invalid_request_error",
"code": "amount_too_small",
"message": "...",
"param": "amount",
"doc_url": "https://mirpay.uz/api-docs#errors"
},
"request_id": "req_..."
}
Kodingizda type va code boʻyicha ishlang, message matniga tayanmang. Koʻp uchraydigan kodlar:
| Kod | Sabab |
|---|---|
parameter_missing |
Majburiy parametr yuborilmagan. |
amount_too_small / amount_too_large |
Summa ruxsat etilgan oraliqdan tashqarida. |
amount_limit_exceeded |
Kassaning tranzaksiya yoki kunlik limiti oshadi (live). |
url_invalid |
return_url / cancel_url notoʻgʻri (liveʼda faqat https). |
resource_missing |
Obyekt topilmadi yoki boshqa kassa / rejimga tegishli. |
idempotency_key_reused |
Shu kalit boshqa tanali soʻrovda ishlatilgan. |
Har bir javobda X-Request-Id (req_…) sarlavhasi bor. Uni saqlang — murojaat qilganda soʻrovingizni shu raqam boʻyicha tez topamiz.
Eski API (v1/v2)
v1 va v2 integratsiyalari oʻzgarishsiz ishlayveradi. Yangi integratsiyalar uchun v3 tavsiya etiladi.