Invoyslar orqali toʻlovlarni qabul qilish

Invoys — bu Telegram foydalanuvchisiga toʻlov qoʻyish usuli. Uni API orqali yaratasiz, toʻlovchiga havolasini yuborasiz va u toʻlovni tasdiqlagan zahoti summa ilova balansingizga tushadi.

Qanday ishlaydi

1. Invoysni yarating — createInvoice metodi bilan, aktiv va summani koʻrsatib (yoki fiatdagi narxni — pastga qarang).
2. Toʻlovchiga javobdagi havolani yuboring. Uni ochgan foydalanuvchi ilovadagi «Invoysni toʻlash» ekraniga tushadi.
3. U tasdiqlaydi va oʻz balansidan toʻlaydi — bir zumda, tarmoq komissiyasisiz. Balansi yetmagan toʻlovchi invoysni tashqi hamyondan moliyalashtirishi mumkin: uning oʻtkazmasi kelgach, invoys avtomatik toʻlanadi, siz uchun esa bu xuddi shunday koʻrinadi.
4. Sizga xabar keladi. invoice_paid webhooki ishga tushadi va summa ilova balansingizga tushadi.
5. Buyurtmani bajaring. Boshqa hech narsani kutish shart emas — toʻlov shu daqiqada yakuniy.

Agar webhook olishdan koʻra API soʻrovlari bilan tekshirishni afzal koʻrsangiz, getInvoices invoyslaringizni joriy holati bilan qaytaradi. Webhook — tezroq yoʻl, davriy soʻrov — zaxira variant.

Fiatdagi narxlar

Invoysni kriptovalyutada yoki fiat valyutada — qabul qilinadigan aktivlar roʻyxati bilan — chiqarish mumkin. Shunda toʻlovchi oʻzida bor qaysi aktiv bilan hisoblashsa, toʻlov paytidagi kurs boʻyicha konvertatsiya qilinadi. Narxlari fiatda koʻrsatilgan doʻkon uchun tabiiy tanlov.

Qatʼiy narx kerak boʻlsa, rate_lock_seconds konvertatsiya kurslarini invoys yaratilgan paytda cheklangan oyna uchun muzlatadi — toʻlovchi aynan qulflangan summalarni koʻradi, oʻsha daqiqalardagi kurs xatarini esa siz olasiz. Tafsilotlar — invoyslar maʼlumotnomasida.

Bundan tashqari, swap_to parametrini belgilab, kelayotgan toʻlovlar tushishi bilanoq bitta aktivga konvertatsiya qilinishini soʻrash mumkin — almashtirishlarni oʻzingiz yuritmasdan balansni stablecoinda ushlab turish uchun qulay.

Foydali invoys parametrlari

• description — toʻlovchiga «Invoysni toʻlash» ekranida koʻrsatiladi.
• hidden_message — toʻlovchiga faqat toʻlovdan keyin ochiladi. Shu yoʻl bilan kod, kalit yoki havolani alohida yetkazish kanalisiz topshirasiz.
• payload — sizning oʻz maʼlumot satringiz; webhookda oʻzgarishsiz qaytariladi. Buyurtmangiz ID raqamini shu yerga qoʻying.
• expires_in — muddat; u oʻtgach, invoysni toʻlab boʻlmaydi.
• paid_btn_name / paid_btn_url — toʻlovdan keyin toʻlovchi koʻradigan tugma; uni botingizga, kanalingizga yoki mahsulot sahifasiga qaytaradi.
• open_amount — belgilangan summasiz; toʻlovchi uni toʻlov paytida oʻzi kiritadi. Xayriya va choychaqa uchun tabiiy shakl.

Toʻlanmagan invoysni deleteInvoice metodi bilan bekor qilish mumkin.

Qaytarishlar

refundInvoice toʻlangan invoysning nominal summasini — yoki uning istalgan qismini — ilova balansingizdan uni toʻlagan odamga qaytaradi, anonim toʻlovchilarni ham qoʻshib va ular kimligini oshkor qilmasdan. Qisman qaytarishlar nominalgacha jamlanadi; invoys ularni refunded_amount maydonida yuritadi. Taymaut boʻyicha uzilgan soʻrov pulni ikki marta qaytarmasligi, balki natijani takrorlashi uchun spend_id uzating. Platforma komissiyasi qaytarilmaydi.

⚠️ Buyurtmani bajarishdan oldin webhook imzosini tekshiring

Sizning webhook manzilingizga POST yuborish har kimning qoʻlidan keladi. Toʻlovni haqiqiy deb hisoblashdan oldin TgCryptoPay-API-Signature sarlavhasini tekshiring — bu xom soʻrov tanasidan olingan HMAC-SHA256, kaliti esa API tokeningizning SHA-256 xeshi — va qayta yetkazish buyurtmani ikki marta joʻnatmasligi uchun update_id boʻyicha dedublikatsiya qiling.