Asosiy qismga oʻtish

2-bob · API integratsiya

API v3 orqali toʻlov yaratish

POST /payments soʻrovi, maydonlar, javob, idempotentlik va xatolar.

3 daqiqada oʻqiladi

Shu sahifada
  1. Asosiy qoidalar
  2. Endpointlar
  3. Toʻlov yaratish
  4. Takroriy toʻlovdan himoya (Idempotency-Key)
  5. Toʻlovni bekor qilish
  6. Roʻyxat
  7. Xatolar
  8. Eski API (v1/v2)

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_… (yoki sk_live_…).
  • Summalar butun son, soʻmda: 250000 = 250 000 soʻm. Valyuta faqat UZS.
  • 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 — 429 va Retry-After sarlavhasi.

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

  1. Serveringizdan POST /api/v3/payments yuboring.
  2. Javobdagi checkout_url ga mijozni yoʻnaltiring.
  3. Natijani webhook (payment.succeeded) yoki GET /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.

Maqola foydali boʻldimi?

Javob topmadingizmi?

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