Dasturchilar uchun qo'llanma: Paynet bilan integratsiya (Developer Portal)

Paynet dasturchilar portaliga xush kelibsiz! Bizning platformamiz xizmat ko'rsatuvchilar va merchantlar agregatori bo'lib, to'lovlarni qabul qilishning qulay usullarini taqdim etadi.

Biz ulanishning 3 ta variantini taklif qilamiz. Mos keluvchi variantni aniqlash uchun quyidagi diagrammadan foydalaning.

1. Integratsiya turini tanlash

Qanday tanlash kerak? (Decision Tree)

Modellarni solishtirish

Har bir model uchun sizdan nima talab qilinadi

✅ Universal billing — hech qanday dasturlashsiz:

• ✅ To'lov shakli uchun maydonlar ro'yxati (masalan: telefon, F.I.Sh., hisob raqami)
• ✅ Xabarnomalarni olish uchun Telegram akkaunt yoki Foyda logini
• ❌ API talab qilinmaydi
• ❌ Server talab qilinmaydi
• ❌ Dasturchi talab qilinmaydi

⚙️ UWS Konnektori — API'ni amalga oshirish kerak:

• ✅ O'z serveringizda JSON-RPC 2.0 metodlarini amalga oshirish
• ✅ Web-xizmat URL manzili, login va parol (HTTP Basic Auth)
• ✅ Xizmatlar ro'yxati va ularning serviceId si ("Texnik hamkorlik tartibi" anketasida to'ldiriladi)
• ✅ Paynet serverlari uchun IP-ruxsatni ochish

[!NOTE] serviceId nima? serviceId — bu xizmatingizning statik ichki identifikatori bo'lib, uni o'zingiz o'ylab topasiz va "Texnik hamkorlik tartibi" hujjatida bizga taqdim etasiz. U mijozning telefon raqami yoki shaxsiy hisob raqami EMAS (bu ma'lumotlar fields massivida uzatiladi). Bitta hamkor bir nechta xizmatlarni taqdim etishi mumkin, va serviceId Paynet'ga mijoz aynan qaysi xizmat uchun to'lov qilayotganini tushunishga yordam beradi.

⚠️ Bu sizning variantingiz EMAS, agar...

2. Arxitektura va jarayonlar (Sequence Diagrams)

[!IMPORTANT] Arxitektura paradigmasi (Bir yo'nalishlilik) UWS integratsiyasi Push/Pull modeli bo'yicha ishlaydi, bu yerda Paynet har doim mijoz (client), sizning billingiz esa server sifatida ishtirok etadi. Siz Paynet API tomoniga hech qanday so'rov yubormaysiz. Barcha o'zaro harakatlar (tekshirish va bekor qilishlar ham) faqat Paynet serverlari tomonidan sizning Endpoint'ingizga yo'naltirilgan holda boshlanadi.

UWS bo'yicha integratsiya (Universal konnektor)

Muvaffaqiyatli to'lovning asosiy ssenariysi:

Ssenariy 1: Network Timeout (Tarmoq taymauti):

Ssenariy 2: Tranzaksiyani bekor qilish (CancelTransaction):

Universal billing

Paynet barcha mantiqni mustaqil ravishda qayta ishlaydi va faqat merchantni xabardor qiladi.

3. Ma'lumotlarga qo'yiladigan talablar, Xavfsizlik va Idempotentlik

3.1 Ma'lumotlar formatlari va Valyuta

[!WARNING] Ushbu bandlardagi xatolar — test bosqichidagi rad etishlarning eng keng tarqalgan sababidir.

• Protokol: HTTP 1.1, POST metodi, TLS v1.3 (HTTPS) himoyasi.
• Kodirovka va Sarlavhalar (Headers): Barcha so'rovlar UTF-8 kodirovkasida yuboriladi va qabul qilinadi. Content-Type: application/json va Accept: application/json dan foydalanish majburiydir.
• Valyuta (amount): Barcha moliyaviy operatsiyalar tiyinlarda uzatiladi (1 so'm = 100 tiyin, butun son). Masalan, 10 000 so'm = 1000000.
• Sana formati: Qat'iy YYYY-MM-dd HH:mm:ss. Vaqt mintaqasi — GMT+5 (O'zbekiston).

[!CAUTION] Sana formatidan yagona istisno: CheckTransaction so'rovidagi timestamp parametri EEE MMM dd HH:mm:ss z yyyy formatida keladi, masalan Mon Jun 16 06:12:41 UZT 2021. Bu format tarixan o'rnatilgan (ko'plab yetkazib beruvchilar allaqachon u bo'yicha ishlamoqda) va o'zgartirilmaydi — sizning parseringiz uni qo'llab-quvvatlashi shart. Boshqa barcha sanalar, jumladan CancelTransaction dagi timestamp va serveringizning barcha javoblari, standart YYYY-MM-dd HH:mm:ss formatidan foydalanadi.

3.2 Avtorizatsiya va himoya

• HTTP Basic Auth: Paynet'dan keladigan so'rovlar bazaviy autentifikatsiya bilan himoyalangan. Login/parol juftligi bo'lmaganda yoki mos kelmaganda, sizning serveringiz HTTP 401 Unauthorized (xato ko'rsatilgan 200 OK emas) qaytarishi shart.
• Parollar rotatsiyasi: Agar sizning tomoningizda majburiy bo'lmagan ChangePassword metodi amalga oshirilgan bo'lsa, Paynet billingingizga birinchi muvaffaqiyatli ulanishda parolni o'zgartirishi shart. Agar metod amalga oshirilmagan bo'lsa, parol alohida, har qanday xavfsiz kanallar orqali uzatiladi.
• Oq ro'yxatlar (IP Whitelists): Sizning API'ingizga kirish faqat quyidagilar uchun ochiq bo'lishi kerak: 213.230.106.112/28 va 213.230.65.80/28.

3.3 Idempotentlik va Taymautlar

Moliyaviy tranzaksiyalar qat'iy izchillikni talab qiladi:

• Taymautlar: Sizning tizimingiz tranzaksiyani 500 ms dan ko'p bo'lmagan vaqtda qayta ishlashi kerak. 1 sek gacha qayta ishlashga ruxsat beriladi, lekin sutkasiga 30 daqiqadan oshmasligi kerak. Agar 30 soniya ichida javob olinmasa, Paynet taymaut bo'yicha ulanishni uzadi. Ushbu limitlar muntazam buzilganda Paynet sababni to'liq bartaraf etilgunga qadar yetkazib beruvchini to'lovlarni qabul qilish tizimidan uzib qo'yishi mumkin.
• Idempotentlik (transactionId): Paynet'dan kelgan har bir tranzaksiya noyob transactionId ga ega. Hamkor billingi bitta transactionId bo'yicha ikki marta mablag' yechib olinishiga yo'l qo'ymasligi kerak: dublikatga 201 xatosini qaytaring — undan keyin Paynet asl natijani bilish uchun CheckTransaction ni chaqiradi. Tarmoq uzilishlari holatida Paynet so'rovni takrorlashi yoki CheckTransaction metodini chaqirishi mumkin. Muvaffaqiyatli operatsiyaga javoban hamkor o'zining ichki raqami providerTrnId ni qaytaradi.

4. Operatsion faoliyat: Solishtirish va SLA

• Kundalik solishtirish (Sverka): Hisob-kitoblar har kuni tekshiriladi. Paynet sizning tomoningizdagi muvaffaqiyatli to'lovlar ro'yxatini olish uchun avtomatik ravishda GetStatement metodini chaqiradi va ularni o'z bazasi bilan solishtiradi. Shuningdek, hamkorning elektron pochtasiga qabul qilingan to'lovlar reyestri yuboriladi.
• Texnik ishlar (SLA): Rejalashtirilgan profilaktika ishlari yoki uskunalarni yangilash holatlarida, hamkor ish boshlanishidan kamida 2 hafta oldin Paynet texnik yordam xizmatini xabardor qilishi shart. Kutilmagan nosozliklar haqida zudlik bilan xabar berish kerak; agar nosozlik bir ish kuni ichida bartaraf etilmasa, hamkor uni bartaraf etish muddatini ma'lum qilishi shart.

5. UWS uchun OpenAPI spetsifikatsiyasi

Spetsifikatsiya OpenAPI (UWS) in Uzbek (Latin).yaml faylida mavjud. U o'z ichiga barcha JSON-RPC 2.0 metodlarining tavsifini oladi: GetInformation, PerformTransaction, CheckTransaction, CancelTransaction, GetStatement, ChangePassword (majburiy emas), shuningdek qat'iy JSON-sxemalar, xato kodlari va formatlarni o'z ichiga oladi.

6. Onbording va testlash bo'yicha qo'llanma (UWS)

Universal konnektor (UWS) orqali to'lovlarni qabul qilishni boshlash uchun quyidagi qadamlarni bajaring:

1-qadam: Infratuzilmani tayyorlash

• API'ni amalga oshirish: Majburiy metodlarni (GetInformation, PerformTransaction, CheckTransaction, CancelTransaction, GetStatement) spetsifikatsiyaga muvofiq amalga oshiring.
• Protokollarni qo'llab-quvvatlash: HTTPS (TLS v1.3) va JSON-RPC 2.0 ma'lumotlar almashish formatini (HTTP POST metodi) qo'llab-quvvatlashni ta'minlang.
• Tarmoq ruxsatlari (IP Whitelisting): Billingingizga kirishni faqat Paynet'ning ruxsat etilgan IP-manzillari uchun oching.
• TAS-IX: Paynet serverlari bilan ulanishingiz TAS-IX tarmog'i orqali amalga oshirilishiga ishonch hosil qiling.

2-qadam: Arizani to'ldirish (Anketa)

Paynet menejeriga quyidagi ma'lumotlarni taqdim eting:

• Web-xizmat URL manzili: (masalan, https://api.yourdomain.uz/uws)
• Username va Password: HTTP Basic Authentication uchun
• Xizmatlar ro'yxati: serviceId va ularning nomlari ro'yxati
• Email: Kundalik reyestrlar uchun manzil

3-qadam: Testlash va Test-keyslar

Ishga tushirishdan oldin standart test-keyslarni bajarish kerak:

1. Abonentni tekshirish (GetInformation): Abonentni muvaffaqiyatli izlashni emulyatsiya qilish va 302 (Mijoz topilmadi) xatosini emulyatsiya qilish.
2. To'lovni amalga oshirish (PerformTransaction): Abonent balansini muvaffaqiyatli to'ldirish.
3. Cheklovlar (PerformTransaction): 413 (Noto'g'ri summa) yoki 101 (Kvota tugagan) xatolarini emulyatsiya qilish.
4. Bekor qilish (CancelTransaction): Test to'lovini amalga oshirish va uni to'liq bekor qilish. Mablag'larni qaytarish (qisman qaytarishlar texnik jihatdan qo'llab-quvvatlanmaydi). 77 (mijoz mablag'ni allaqachon sarflagan), 306 (hisobot davri yopilgan) va 203 (tranzaksiya topilmadi) xatolarini emulyatsiya qilish.
5. Statusni tekshirish (CheckTransaction): Mavjud tranzaksiya (state 1) va mavjud bo'lmagan (state 3, muvaffaqiyatli javob — xato emas) statusini tekshirish. EEE MMM dd HH:mm:ss z yyyy formatidagi timestamp parsingini albatta tekshiring.

4-qadam: Production'ga tushirish (Go-Live)

Barcha testlardan muvaffaqiyatli o'tgandan so'ng, texnik tayyorgarlik dalolatnomasi imzolanadi va sizning xizmatlaringiz millionlab Paynet foydalanuvchilari uchun to'lashga ochiq bo'ladi!

7. Paynet xato kodlari ma'lumotnomasi (Paynet Error Codes)

Biznes-xatolik yuzaga kelganda, hamkor billingi o'zida code va message bo'lgan error obyekti bilan JSON-RPC javobini qaytaradi.

[!IMPORTANT] Ushbu bo'limdagi barcha kodlar (201, 412, 413 va h.k.) — bu JSON-RPC darajasidagi Paynet xato kodlari, HTTP statuslari emas. Ularni ko'pincha HTTP kodlari bilan adashtirishadi: aslida ular javob tanasidagi error obyekti ichida qaytariladi, javobning HTTP statusi esa 200 OK bo'lib qoladi. Yagona istisno — autentifikatsiya: noto'g'ri login/parolda HTTP 401 Unauthorized qaytariladi (quyidagi 412 xatosi haqidagi eslatmaga qarang).

Biznes xatolar xaritasi (Business Error Mapping) jadvali

Sizning biznes-keysingizga qarab qanday xato qaytarish kerakligini tushunish uchun ushbu jadvaldan foydalaning:

[!NOTE] 412 xatosi haqida (Noto'g'ri login yoki parol): autentifikatsiya faqat HTTP darajasida bajariladi — noto'g'ri hisob ma'lumotlarida JSON-RPC xatosi emas, HTTP 401 Unauthorized qaytaring. 412 kodi — protokolning dastlabki versiyalaridan qolgan legacy, yangi integratsiyalarda ishlatilmaydi.

Paynet xato kodlarining to'liq ma'lumotnomasi

JSON-RPC protokoli xatoliklari:

[!NOTE] 0 kodi («Muvaffaqiyatli o'tkazildi») — status qiymati, u hech qachon error obyekti ichida qaytarilmaydi.

8. Versiyalar tarixi

Portal va OpenAPI spetsifikatsiyasi 2025-yil 07-maydagi UWS v3.4 ga Paynet core-jamoasining aniqlashtirishlari bilan mos keladi: 306 xato kodi qo'shildi (bekor qilish uchun ruxsat etilgan vaqt tugagan), TLS v1.3 talabi belgilandi, GetInformation javobidagi status maydoni majburiy deb tasdiqlandi.