API maʼlumotnomasi: invoyslar va qaytarishlar

Invoys metodlari: createInvoice, getInvoices, deleteInvoice, refundInvoice. Umumiy qoidalar (autentifikatsiya, konvert, summalar, spend_id) — Merchant API maʼlumotnomasi sahifasida; bosqichma-bosqich yoʻriqnoma — Invoyslar orqali toʻlovlarni qabul qilish.

createInvoice

POST /pay/api/createInvoice — invoices huquqi, daqiqasiga 60 ta limit.

Parametr	Turi	Majburiy	Maʼnosi
currency_type	string	yoʻq	crypto (standart) yoki fiat
asset	string	kripto rejimida	undiriladigan aktiv, masalan USDT. fiat bilan birga ishlatilmaydi
fiat	string	fiat rejimida	narx koʻrsatilgan fiat valyuta (getCurrencies javobidagi is_fiat satrlari)
accepted_assets	string / array	yoʻq	faqat fiat rejimida: toʻlovchi toʻlashi mumkin boʻlgan aktivlar — vergul bilan ajratilgan satr ("USDT,GRAM") yoki JSON massiv. Koʻrsatilmasa — barcha qoʻllanadigan aktivlar
amount	string	ha, open_amount belgilanmagan boʻlsa	musbat oʻnlik satr: kripto rejimida aktiv birliklari, fiat rejimida fiat birliklari (koʻpi bilan 2 kasr xonasi)
open_amount	boolean	yoʻq	kengaytma, faqat kripto rejimida: belgilangan summa yoʻq — toʻlovchi uni toʻlov paytida oʻzi kiritadi (xayriya va choychaqa). amount bilan birga ishlatilmaydi
description	string	yoʻq	1024 belgigacha, toʻlovchiga koʻrsatiladi
hidden_message	string	yoʻq	2048 belgigacha, toʻlovchiga faqat toʻlovdan keyin ochiladi
payload	string	yoʻq	4096 belgigacha oʻz maʼlumotingiz; invoysda va webhookda oʻzgarishsiz qaytariladi
allow_comments	boolean	yoʻq	toʻlovchiga izoh qoldirishga ruxsat berish (standart true)
allow_anonymous	boolean	yoʻq	toʻlovchiga oʻzini yashirishga ruxsat berish (standart true)
paid_btn_name	string	yoʻq	toʻlovdan keyingi tugma: viewItem, openChannel, openBot yoki callback
paid_btn_url	string	yoʻq	tugmaning http(s) manzili — paid_btn_name belgilanganda majburiy
swap_to	string	yoʻq	qabul qilingan toʻlovlarni shu aktivga avtomatik almashtirish. Imkon qadar bajariladi: toʻlov paytida almashtirish oʻtmasa, toʻlov baribir muvaffaqiyatli boʻladi, faqat almashtirilmagan holda
expires_in	integer	yoʻq	invoys muddati tugagunga qadar soniyalar, 2678400 gacha (31 kun); koʻrsatilmasa yoki 0 — hech qachon
rate_lock_seconds	integer	yoʻq	kengaytma, faqat fiat rejimida: yaratish paytida konvertatsiya kurslarini shu oyna uchun muzlatadi (pastga qarang)

Natija — va invoice_paid webhookining maʼlumotlari — bu invoys obyekti. Uning asosiy maydonlari:

• Identifikator va holat: invoice_id, hash (pay_url ichidagi ochiq id), status (active / paid / expired), pay_url — toʻlovchiga yuboradigan t.me havolangiz (bot_invoice_url, mini_app_invoice_url, web_app_invoice_url — uning muqobil nomlari).
• Summalar: amount (nominal qiymat — fiat invoysda fiat birliklari, aks holda kripto; erkin summali invoys toʻlanmaguncha null), amount_minor, hamda toʻlangan fiat invoyslarda paid_asset / paid_amount / paid_fiat_rate — aslida undirilgan kripto va ishlatilgan kurs.
• Komissiya: fee_asset / fee_amount, toʻlov paytida qayd etiladi — buxgalteriyangiz uchun asosiy raqam (fee va usd_rate — eskirgan Crypto Bot muqobillari). Qarang: komissiyalar va limitlar.
• Toʻlovchi: paid_by_user_id (toʻlovchi anonimlikni tanlaganda null), paid_anonymously, comment.
• Qaytarishlar (kengaytma): refunded_amount / refunded_minor (jamlanma) va refunded_at — invoys toʻliq qaytarilgach qoʻyiladi.
• Kurs qulfi (kengaytma): rate_lock_until va rate_lock_rates — aktivlar boʻyicha qayd etilgan kurslar; qulf soʻralmagan boʻlsa null.
• Yaratilgandagi holat: description, hidden_message, payload, paid_btn_name / paid_btn_url, expiration_date (expires_at — muqobil nomi), almashtirish maydonlari (swap_to, is_swapped, swapped_to, swapped_rate, swapped_output, …).

Xatolar: 400 invalid_currency (aktiv va fiat aralashtirib yuborilgan), 400 invalid_amount, 404 unknown_asset, 400 unsupported_fiat, 400 paid_btn_url_required, kurs qulfi soʻralganda esa 400 rate_lock_fiat_only, 409 ratelock_disabled, 409 rate_unavailable (qabul qilinadigan aktiv uchun yangi kurs yoʻq — qayta urinib koʻring).

Invoyslar qanday toʻlanadi

Toʻlovchi Mini App ichida hamyon balansidan toʻlaydi — bir zumda, tarmoq komissiyasisiz. Toʻlovchi invoysni tashqi hamyondan ham moliyalashtirishi mumkin: ilova unga toʻldirish manzilini koʻrsatadi, uning oʻtkazmasi oʻz hamyoniga tushadi va kelib tushishi bilan invoys avtomatik toʻlanadi. Ikkala holda ham siz bir xil narsani koʻrasiz: oddiy paid invoys va invoice_paid webhooki — qayta ishlash uchun qoʻshimcha parametr yoki maydon yoʻq.

Fiat invoysda kripto summasi toʻlov paytida hisoblanadi va sizning foydangizga yaxlitlanadi, shuning uchun siz hech qachon fiatdagi nominaldan kam olmaysiz. Yangi kurs boʻlmasa, toʻlov eskirgan kurs boʻyicha oʻtib ketmaydi, balki toʻlovchi tomonida uziladi.

Fiat invoysda kursni qulflash

rate_lock_seconds uzatilsa, yaratish paytida har bir qabul qilinadigan aktivning joriy kursi qayd etiladi. Qulf amal qilar ekan, toʻlovchi aynan qayd etilgan summalarni koʻradi va toʻlov qayd etilgan kurs boʻyicha konvertatsiya qilinadi — oyna davomidagi kurs xatarini siz olasiz. Server oynani 60 soniya bilan platforma maksimumi (hozircha 15 daqiqa) orasida cheklaydi.

Qulf tugagach, invoys toʻlanadigan boʻlib qolaveradi va sokingina toʻlov paytidagi konvertatsiyaga qaytadi. Invoys kotirovka bilan birga tugashini istasangiz, expires_in qiymatini xuddi shunday qilib qoʻying.

getInvoices

GET /pay/api/getInvoices — read huquqi. Filtrlar: asset, fiat, invoice_ids (vergul bilan ajratilgan), status (active / paid / expired — expired kengaytma; active muddati allaqachon oʻtgan invoyslarni qamrab olmaydi), hamda offset / count. {"items": [invoice, …]} qaytaradi, yangilari birinchi.

deleteInvoice

POST /pay/api/deleteInvoice — invoices huquqi. Bitta parametr: invoice_id. Toʻlanmagan invoysni bekor qiladi va true qaytaradi. Xatolar: 404 invoice_not_found, 409 invoice_already_paid — toʻlangan invoysni oʻchirib boʻlmaydi, pul allaqachon koʻchgan.

refundInvoice

POST /pay/api/refundInvoice — refunds huquqi, daqiqasiga 30 ta limit. Crypto Bot ustidagi kengaytma: toʻlangan invoysning nominal summasini — yoki uning bir qismini — ilova balansingizdan uni toʻlagan odamga qaytaradi, anonim toʻlovchilarni ham qoʻshib va ular kimligini oshkor qilmasdan.

Parametr	Turi	Majburiy	Maʼnosi
invoice_id	integer	ha	toʻlangan invoys
amount	string	yoʻq	qaytariladigan summa, invoysning aktivida. Koʻrsatilmasa — qaytarilmagan butun qoldiq. Qisman qaytarishlar nominalgacha jamlanadi
spend_id	string	yoʻq	idempotentlik kaliti — uni ishlating, shunda taymaut boʻyicha qayta urinish ikki marta qaytarish oʻrniga natijani takrorlaydi

Natija — jamlangan refunded_amount / refunded_minor bilan yangilangan invoys obyekti; refunded_at invoys toʻliq qaytarilgach qoʻyiladi. Holat paid boʻlib qoladi. Platforma komissiyasi qaytarilmaydi. Har bir qaytarish ixtiyoriy ravishda yoqiladigan refund_completed webhookini ishga tushiradi.

Xatolar: 404 invoice_not_found, 409 invoice_not_paid, 409 already_refunded (qaytarishga hech narsa qolmagan), 409 amount_too_big (qaytarilmagan qoldiqdan koʻp), 409 insufficient_funds, 400 invalid_amount, hamda spend_id juftligi — 409 idempotency_conflict / 409 idempotency_in_progress.