API maʼlumotnomasi: oʻtkazmalar va cheklar

Toʻlov chiqarish metodlari. Oʻtkazma ilova balansingizdan toʻgʻridan-toʻgʻri Telegram foydalanuvchisining hamyoniga mablagʻ yuboradi; chek — bu siz oldindan moliyalashtiradigan, faollashtiriladigan havola. Umumiy qoidalar (autentifikatsiya, konvert, summalar, spend_id) — Merchant API maʼlumotnomasi sahifasida.

transfer

POST /pay/api/transfer — payouts huquqi, daqiqasiga 30 ta limit. Bir zumda va atomar ijro etiladi; «Kutilmoqda» holati yoʻq.

Parametr	Turi	Majburiy	Maʼnosi
user_id	integer	ha	qabul qiluvchining Telegram foydalanuvchi id raqami. Qabul qiluvchi allaqachon ilova foydalanuvchisi boʻlishi kerak — notanish id raqamiga toʻlov mablagʻni osiltirib qoʻyish oʻrniga xato qaytaradi
asset	string	ha	aktiv kodi
amount	string	ha	musbat oʻnlik satr; shuningdek platformaning har bir oʻtkazma uchun minimumi va maksimumi bilan chegaralangan (joriy kurslar boʻyicha AQSh dollaridagi taxminiy ekvivalent)
spend_id	string	ha	idempotentlik kaliti, 1–64 belgi, har bir toʻlov uchun noyob
comment	string	yoʻq	1024 belgigacha, qabul qiluvchiga koʻrsatiladi
disable_send_notification	boolean	yoʻq	true — qabul qiluvchiga Telegramda xabar bermaslik

Natija — oʻtkazma obyekti: transfer_id, hash, user_id, asset, amount, amount_minor, spend_id, comment, status (har doim completed), created_at, completed_at.

Xatolar: 404 user_not_found (qabul qiluvchi ilovadan hech qachon foydalanmagan), 409 recipient_blocked, 400 amount_too_small / 400 amount_too_big (har bir oʻtkazma uchun belgilangan chegaralardan tashqarida), 409 insufficient_funds, 404 unknown_asset, 400 invalid_amount, hamda spend_id juftligi — 409 idempotency_conflict / 409 idempotency_in_progress.

transferBatch

POST /pay/api/transferBatch — payouts huquqi, daqiqasiga 10 ta limit. Ommaviy toʻlovlar uchun kengaytma: bitta chaqiruvda 100 tagacha oʻtkazma.

Bitta parametr: items — massiv; uning har bir elementi toʻliq transfer parametrlari toʻplami (user_id, asset, amount, spend_id, ixtiyoriy comment va disable_send_notification). spend_id qiymatlari paket ichida noyob boʻlishi shart, aks holda butun chaqiruv hech narsa bajarilmasdan turib 400 duplicate_spend_id bilan uziladi.

Elementlar mustaqil ravishda, navbat boʻyicha ijro etiladi — bitta element xato boʻlsa, qolganlari orqaga qaytarilmaydi. Baʼzi elementlar xato boʻlganda ham chaqiruv ok: true bilan HTTP 200 qaytaradi, shuning uchun har bir elementni doim tekshiring:

• muvaffaqiyat: {"ok": true, "spend_id": "…", "result": <transfer object>}
• xato: {"ok": false, "spend_id": "…", "error": {"code": …, "name": "…"}} — yakka transfer metodidagi kabi xato nomlari bilan.

Paket elementlari idempotentlik makonini yakka oʻtkazmalar bilan boʻlishadi: butun paketni qayta yuborish — yoki bitta elementni xuddi shu spend_id bilan yakka transfer sifatida qayta joʻnatish — ikki marta toʻlash oʻrniga natijani takrorlaydi.

getTransfers

GET /pay/api/getTransfers — read huquqi. Filtrlar: asset, transfer_ids (vergul bilan ajratilgan), spend_id (aniq moslik — toʻlovni oʻz kalitingiz boʻyicha topish), hamda offset / count. {"items": [transfer, …]} qaytaradi, yangilari birinchi.

createCheck

POST /pay/api/createCheck — checks huquqi, daqiqasiga 60 ta limit. Ilova balansingizdan moliyalashtiriladigan bir martalik chek yaratadi; havolasi bor har kim — yoki faqat biriktirilgan foydalanuvchi — uni oʻz hamyoniga faollashtira oladi. Summa chek yaratilgan zahoti bloklanadi (getBalance javobida available qiymatidan onhold qiymatiga oʻtadi).

Parametr	Turi	Majburiy	Maʼnosi
asset	string	ha	aktiv kodi
amount	string	ha	musbat oʻnlik satr
pin_to_user_id	integer	yoʻq	faqat shu Telegram foydalanuvchi id raqami faollashtira oladi
pin_to_username	string	yoʻq	faqat shu @username faollashtira oladi (@ ixtiyoriy; pin_to_user_id ham berilgan boʻlsa, eʼtiborga olinmaydi). Bu nom ilovaning mavjud foydalanuvchisiga tegishli boʻlishi kerak
spend_id	string	yoʻq	idempotentlik kaliti (kengaytma) — uni ishlating

Natija — chek obyekti: check_id, hash, asset, amount, amount_minor, bot_check_url (faollashtirish uchun t.me havolasi), status (active / activated), pin_to_user_id, created_at, activated_at. Faollashtirish ixtiyoriy ravishda yoqiladigan check_activated webhookini ishga tushiradi.

Xatolar: 404 unknown_asset, 400 invalid_amount, 404 user_not_found (biriktirilgan username hech kimga mos kelmadi), 409 insufficient_funds, hamda spend_id juftligi.

deleteCheck

POST /pay/api/deleteCheck — checks huquqi. Bitta parametr: check_id. Faollashtirilmagan chekni bekor qiladi va bloklangan summani ilova balansingizga qaytaradi; true qaytaradi. Xatolar: 404 check_not_found, 409 check_not_active (allaqachon faollashtirilgan yoki oʻchirilgan).

getChecks

GET /pay/api/getChecks — read huquqi. Filtrlar: asset, check_ids (vergul bilan ajratilgan), status (active / activated), hamda offset / count. {"items": [check, …]} qaytaradi, yangilari birinchi; oʻchirilgan cheklar hech qachon qaytarilmaydi.