Bank kartalarini tokenlashtirish

Tokenlashtirish - bu Hamkor uchun foydalanuvchidan karta ma'lumotlarini bir marta so'rashga va keyin ushbu ma'lumotlarni OCTO-ning xavfsiz manbalarda saqlashga imkon beradigan mexanizmdir va bu ma'lumotlar noyob kalitga - tokenga almashtiriladi. Ushbu token Savdogar serverlarida saqlanishi mumkin va keyingi xaridlarni boshlash uchun xaridorning hisobiga ulanishi mumkin, bunda OCTO-ga faqat Token uzatiladi va foydalanuvchidan karta ma'lumotlari qayta so'ralmaydi, faqat kartaning orqa tomonidagi uch qiymatli CVV2/CVC2 xavfsizlik kodi so'raladi.

Muhim!

Karta tokenizatsiyasining yakuniy holati haqida bildirishnoma yuborish OCTO PS tomonidan (callback) hamkor tomonidan bind_notify_url parametrida ko'rsatilgan manzilga bind_card usuli yordamida POST so'rovi orqali amalga oshiriladi.

Karta tokenini bloklash.

Bank kartasi chiqarilgan tokenini bloklash uchun hamkor serveridan /block_card_token so'rov yuborilishi kerak.

Humo/Uzcard tokenlashtirish algoritmi:

1. Mijoz kartani tokenlashtirishni boshlaydi.
2. Hamkor kartalarni bog'lash usulini chaqiradi bind_card.
3. Bizning backend Humo/Uzcard-ga karta ma'lumotlarini tekshirish uchun so'rovnoma yuboradi.
4. Humo/Uzcard tasdiqlaydi.
5. Bizning backend Hamkor uchun buni tasdiqlaydi.
6. Hamkor OTP verificationInfo amal qilish muddatini olish usulini chaqiradi.
7. Bizning backend Hamkor uchun buni tasdiqlaydi.
8. Humo/Uzcard OTP kodini mijozga yuboradi.
9. Mijoz OTP kodini Hamkorga yuboradi.
10. Hamkor kodni tekshirish usulini chaqiradi /bind_card/check_sms.
11. Bizning backend kodni Humo/Uzcard-ga yuboradi.
12. Humo/Uzcard hisobdan chiqarishni tasdiqlaydi.
13. Bizning backend Hamkorga xabarnoma yuboradi.
14. Bizning backend Humo/Uzcard-ga mablag'ni qaytarish so'rovnomasini yuboradi.
15. Humo/Uzcard mablag' hisobga kiritilganini tasdiqlaydi.
16. Bizning BE hamkorni callback orqali holatdan xabardor qiladi.
17. Bizning backend Hamkorga token yuboradi.
18. Hamkor qabul qilinganligini tasdiqlaydi.

Eslatma

Agar Hamkor qabul qilinganligini tasdiqlamasa, bizning backend yana uchta takroriy so'rovnoma yuboradi. Agar barcha so'rovnomalardan keyin tasdiqlanmasa, token bekor qilinadi.

---

Tokenizatsiya Humo/Uzcard

Visa/MC Tokenizatsiya Algoritmi

1. Mijoz karta tokenizatsiyasini boshlaydi.
2. Hamkor kartani bog‘lash metodini chaqiradi bind_card.
3. Bizning backend (BE) Visa/MC’ga karta ma'lumotlarini tekshirish va test tranzaksiyasini amalga oshirish uchun so‘rov yuboradi.
4. Visa/MC ma'lumotlarni tasdiqlaydi va OTP kodini kiritish formasi havolasini taqdim etadi.
5. Visa/MC mijozga OTP kodini yuboradi.
6. Mijoz OTP kodini kiritadi.
7. Visa/MC tranzaksiyani tasdiqlaydi.
8. Bizning BE hamkorni xabardor qiladi.
9. Bizning BE Visa/MC’ga qaytarish so‘rovini yuboradi.
10. Visa/MC qaytarishni tasdiqlaydi.
11. Bizning BE hamkorga holat bo‘yicha callback yuboradi.
12. Bizning BE hamkorga token yuboradi.
13. Hamkor qabul qilinganligini tasdiqlaydi.

Eslatma

Agar hamkor qabul qilinganligini tasdiqlamasa, bizning BE so‘rovni uch marta qayta yuboradi. Agar javob bo‘lmasa, token bekor qilinadi.

*BE - Back End

Visa/MC tokenizatsiyasi

Metodlar

bind_card

• URL: https://secure.octo.uz/bind_card
• Method: POST
• Content-type: application/json

So'rovnoma

{
    "octo_shop_id": "{{merchant_id}}",
    "octo_secret": "{{merchant_secret}}",
    "shop_transaction_id": "{{$randomUUID}}",
    "pan": "9860240101226506",
    "exp": "2805",
    "phone": "998901234567",
    "cardHolderName": "Card Holder Name",
    "cvc2": "",
    "method": "humo",
    "return_url": "https://notify-url.uz",
    "notify_url": "https://notify-url.uz",
    "bind_notify_url": "https://notify-url.uz"
}

Parametrlar tavsifi

Parametr	Turi	Majburiylik	Tavsif
octo_shop_id	Integer	Ha	Do'konning noyob identifikatori (do'konning Shaxsiy kabinetida mavjud).
octo_secret	String	Ha	Do'konning maxfiy kaliti. Himoyalangan hududda saqlanishi kerak.
shop_transaction_id	String	Ha	Operatsiyaning do'kon tarafidagi noyob identifikatori.
pan	String	Ha	Operatsiyani amalga oshirish uchun mijozning karta raqami.
exp	String	Ha	yyyy-MM formatidagi kartaning amal qilish muddati.
phone	String	Ha	Mijozning kartaga bog'langan telefon raqami.
cardHolderName	String	Ha	Karta egasining ismi (kartada ko'rsatilganidek).
cvc2	String	Yo'q	Karta xavfsizlik kodi.
method	String	Ha	Operatsiya uchun to'lov usuli: humo, uzcard, bank_card.
return_url	String	Ha	Foydalanuvchi yo'naltiriladigan URL.
notify_url	String	Yo'q	To'lov holati haqida xabarnomalar yuboriladigan URL.
bind_notify_url	String	Yo'q	Muvaffaqiyatli operatsiyalarda xabar yuboriladigan URL.

---

Muvaffaqiyatli javob

{
    "error": 0,
    "data": {
        "shop_transaction_id": "123431321323334132333",
        "octo_payment_UUID": "06000144-db56-47b6-9eba-021ad4ff246b",
        "status": "created",
        "octo_pay_url": "https://pay-dev.octo.uz/uzcard/sms/06000144-db56-47b6-9eba-021ad4ff246b",
        "refunded_sum": 0,
        "total_sum": 1000
    },
    "apiMessageForDevelopers": "errorMessage maydoni eskirgan, javoblarni unifikatsiya qilish uchun errMessage-ga o'tishni so'raymiz. Iltimos, shuni yodda tutingki, kelajakda error и errMessage-dan tashqari barcha maydonlar data-ga yuboriladi. Batafsil ma'lumot olish uchun xizmatning texnik yordamiga murojaat qiling",
    "shop_transaction_id": "123431321323334132333",
    "octo_payment_UUID": "06000144-db56-47b6-9eba-021ad4ff246b",
    "status": "created",
    "octo_pay_url": "https://pay-dev.octo.uz/uzcard/sms/06000144-db56-47b6-9eba-021ad4ff246b",
    "refunded_sum": 0,
    "total_sum": 1000
}

Javob parametrlarining tavsifi

Parametr	Turi	Majburiylik	Tavsif
error	Integer	Ha	Xato kodi. 0 qiymati muvaffaqiyatli operatsiyani anglatadi.
data	Object	Ha	Operatsiya haqida batafsil ma'lumotga ega ob'ekt.
shop_transaction_id	String	Ha	Operatsiyaning do'kon tarafidagi noyob identifikatori.
octo_payment_UUID	String	Ha	OCTO tizimi tomonidan yaratilgan noyob to'lov identifikatori.
status	String	Ha	To'lov holati: created, succeeded, failed va boshqalar.
octo_pay_url	String	Ha	To'lovni amalga oshirish uchun URL.
refunded_sum	Number	Ha	Qaytarma miqdori. Agar qaytarish amalga oshirilmagan bo'lsa, 0.
total_sum	Number	Ha	Operatsiyaning umumiy miqdori.
apiMessageForDevelopers	String	Yo'q	API-dagi mumkin bo'lgan o'zgarishlar haqida ishlab chiquvchilarga xabar.

---

Muvaffaqiyatsiz javob

{
    "error": 20,
    "errMessage": "Active or pending token already exists",
    "data": null,
    "errorMessage": "Active or pending token already exists",
    "apiMessageForDevelopers": "errorMessage maydoni eskirgan, javoblarni unifikatsiya qilish uchun errMessage-ga o'tishni so'raymiz. Iltimos, shuni yodda tutingki, kelajakda error и errMessage-dan tashqari barcha maydonlar data-ga yuboriladi. Batafsil ma'lumot olish uchun xizmatning texnik yordamiga murojaat qiling"
}

---

verificationInfo

• URL: https://secure.octo.uz/verificationInfo/{octo_payment_UUID}
• Method: GET
• Content-type: application/json

So'rovnoma

Muhim!

Faqat octo_payment_UUID jo'natiladi.

Muvaffaqiyatli javob

{
  "error": 0,             // Xato kodi: 0 xatolar yo'qligini anglatadi.
  "errMessage": "",      // Xato haqida xabar, agar xato bo'lmasa, bo'sh qoladi.
  "data": {
    "verifyId": 819,      // Verifikatsiya jarayonining noyob identifikatori.
    "phone": "+998** *****33",  // Verifikatsiya bog'langan telefon raqami (xavfsizlik uchun qisman yashiringan).
    "secondsLeft": 221     // Verifikatsiya amal qilish muddati tugashigacha qolgan vaqt (soniyalarda)
  }
}

Parametrlar tavsifi

Parametr	Turi	Majburiylik	Tavsif
error	int	Ha	Xato kodi: 0 xatolar yo'qligini anglatadi.
errMessage	string	Yo'q	Xato haqida xabar, agar xato bo'lmasa, bo'sh qoladi.
data	object	Ha	Verifikatsiya jarayonining tafsilotlariga ega ob'ekt.
verifyId	int	Ha	Verifikatsiya jarayonining noyob identifikatori.
phone	string	Ha	Verifikatsiya bog'langan telefon raqami.
secondsLeft	int	Ha	Verifikatsiya amal qilish muddati tugashigacha qolgan vaqt (soniyalarda).

Muvaffaqiyatsiz javob

{
  "error": 0,             // Xato kodi: 0 xatolar yo'qligini anglatadi.
  "errMessage": "",      // Xato haqida xabar, agar xato bo'lmasa, bo'sh qoladi.
  "data": {
    "verifyId": 819,      // Verifikatsiya jarayonining noyob identifikatori.
    "phone": "+998** *****33",  // Verifikatsiya bog'langan telefon raqami (xavfsizlik uchun qisman yashiringan).
    "secondsLeft": 0       // Verifikatsiya amal qilish muddati tugashigacha qolgan vaqt (soniyalarda). Muvaffaqiyatsiz javob bo'lsa, u 0 qiymati bilan qolaveradi.
  }
}

Muhim!

verificationInfo muvaffaqiyatsiz javobini bersa, siz muvaffaqiyatli javobdagidek javob olasiz, ammo secondsLeft parametrida 0 bo'ladi.

Parametrlar tavsifi

Parametr	Turi	Majburiylik	Tavsif
error	int	Ha	Xato kodi (0 xatolar mavjud emasligini bildiradi).
errMessage	string	Yo'q	Xato haqida xabar (xato sodir bo'lganda).
data	object	Ha	Verifikatsiya jarayonining tafsilotlariga ega ob'ekt.
verifyId	int	Ha	Verifikatsiya jarayonining noyob identifikatori.
phone	string	Ha	Verifikatsiya bog'langan telefon raqami.
secondsLeft	int	Ha	Verifikatsiya amal qilish muddati tugashigacha qolgan vaqt (soniyalarda).

Muhim!

Agar secondsLeft=0 bo‘lsa, demak, tekshirish vaqti tugagan yoki tekshirish jarayoni faol emas. Integratsiya bo‘yicha savollaringiz bo‘lsa, Octo xizmatining texnik qo‘llab-quvvatlashiga murojaat qiling.

---

bind_card/check_sms_key

• URL: https://secure.octo.uz/bind_card/check_sms_key
• Method: POST
• Content-type: application/json

So'rovnoma

{
    "octo_shop_id": "{{merchant_id}}",                 // Do'konning noyob identifikatori (Savdogarning Shaxsiy kabinetida mavjud).
    "octo_secret": "{{merchant_secret}}",         // Savdogarning Shaxsiy kabinetida yaratiladigan do'konning shaxsiy maxfiy kaliti. Do'kon veb-saytining xavfsiz, kirish mumkin bo'lmagan hududida saqlanishi kerak.  
    "smsKey": "61135",                            // Kartaga bog'langan telefon raqamiga yuboriladigan SMS-kod.
    "paymentUUID": "{{bind_octo_payment_UUID}}",  // Karta bog'lash operatsiyasinig noyob identifikatori.
    "verifyId": "{{bind_verifyId}}"                 // Karta bog'langanligini tasdiqlash uchun identifikator.
}

---

Parametrlar tavsifi

Parametr	Turi	Majburiylik	Tavsif
octo_shop_id	Integer	Ha	Do'konning noyob identifikatori (Savdogarning Shaxsiy kabinetida mavjud).
octo_secret	String	Ha	Savdogarning Shaxsiy kabinetida yaratiladigan do'konning shaxsiy maxfiy kaliti. Himoyalangan bo'lishi kerak.
smsKey	String	Ha	Operatsiyani tasdiqlash uchun karta bilan bog'langan telefonga yuborilgan SMS-kod.
paymentUUID	String	Ha	Karta bog'lash operatsiyasining noyob identifikatori.
verifyId	Integer	Ha	Karta bog'langanligini tasdiqlash uchun identifikator.

---

Muvaffaqiyatli javob

{
    "error": 0,
    "data": {
        "shop_transaction_id": "123431321323334132333",
        "octo_payment_UUID": "06000144-db56-47b6-9eba-021ad4ff246b",
        "status": "succeeded",
        "octo_pay_url": "https://pay-dev.octo.uz/status/06000144-db56-47b6-9eba-021ad4ff246b",
        "processor_key": "023205044087",
        "processing_reference": "1735210612392_71229",
        "transfer_sum": 980.0000,
        "refunded_sum": 1000.00,
        "total_sum": 1000.00,
        "payed_time": "2024-12-26 15:56:52",
        "first6": "860050",
        "last4": "2744"
    },
    "apiMessageForDevelopers": "errorMessage maydoni eskirgan, javoblarni unifikatsiya qilish uchun errMessage-ga o'tishni so'raymiz. Iltimos, shuni yodda tutingki, kelajakda error и errMessage-dan tashqari barcha maydonlar data-ga yuboriladi. Batafsil ma'lumot olish uchun xizmatning texnik yordamiga murojaat qiling",
    "shop_transaction_id": "123431321323334132333",
    "octo_payment_UUID": "06000144-db56-47b6-9eba-021ad4ff246b",
    "status": "succeeded",
    "octo_pay_url": "https://pay-dev.octo.uz/status/06000144-db56-47b6-9eba-021ad4ff246b",
    "processor_key": "023205044087",
    "processing_reference": "1735210612392_71229",
    "transfer_sum": 980.0000,
    "refunded_sum": 1000.00,
    "total_sum": 1000.00,
    "payed_time": "2024-12-26 15:56:52"
}

---

Javob parametrlari tavsifi

Parametr	Turi	Majburiylik	Tavsif
error	Integer	Ha	Xato kodi. 0 qiymati operatsiyaning muvaffaqiyatli bajarilganligini anglatadi.
data	Object	Ha	To'lov tafsilotlarini o'z ichiga olgan javob ma'lumotlari.
shop_transaction_id	String	Ha	Do'kon tarafidagi tranzaksiyaning noyob identifikatori.
octo_payment_UUID	String	Ha	OCTO tizimi tomonidan yaratilgan noyob to'lov identifikatori.
status	String	Ha	To'lovning joriy holati (succeeded, failed, created va hokazo).
octo_pay_url	String	Ha	To'lov holatini tekshirish yoki olish uchun URL.
processor_key	String	Yo'q	Operatsiyani identifikatsiya qilish uchun noyob protsessor kaliti.
processing_reference	String	Yo'q	To'lovlarga qayta ishlash tizimidagi operatsiyaga havola.
transfer_sum	Decimal	Yo'q	Komissiyalar chegirib tashlanganidan keyin oluvchiga o'tkazilgan qiymat.
refunded_sum	Decimal	Yo'q	Qaytarish natijasida foydalanuvchiga qaytarilgan qiymat.
total_sum	Decimal	Ha	Operatsiyaning to'liq qiymati.
payed_time	String	Yo'q	YYYY-MM-DD HH:MM:SS formatida to'lovni yakunlash sanasi va vaqti.
first6	String	Yo'q	To'lov uchun ishlatilgan karta raqamining dastlabki 6 raqami.
last4	String	Yo'q	To'lov uchun ishlatilgan karta raqamining oxirgi 4 raqami.
apiMessageForDevelopers	String	Yo'q	O'z ichiga kelajakda API o'zgarishi haqida qo'shimcha tafsilotlar yoki bildirishlarni olgan ishlab chiquvchilar uchun xabar.

---

Muvaffaqiyatsiz javob

{
    "title": "Serverning ichki xatosi",
    "status": 500,
    "detail": "Cannot invoke \"com.octo.uzcard.dto.CardInfo.getCardtype()\" because the return value of \"com.octo.uzcard.dto.CardNewVerifyResponse.getResult()\" is null"
}

callback

So'rovnoma

{
    "shop_transaction_id": "d87f4hd8d76f4h58d",
    "pan": "4276380012341025",
    "exp": "2006",
    "cardHolderName": "BOB MARLEY",
    "card_token": "sdf9g87sd6f9g876sdf9g876sdf98g",
    "status": "active"
}

So'rov Parametrlari

Parametr	Tur	Majburiylik	Tavsif
shop_transaction_id	String	Ha	Do'kondagi tranzaksiyaning noyob identifikatori.
pan	String	Ha	Asl PAN (karta raqami).
exp	String	Ha	Kartaning amal qilish muddati YYMM formatida.
cardHolderName	String	Ha	Karta egasining ismi.
card_token	String	Ha	Karta bog'langandan so'ng olingan token.
status	String	Ha	Kartaning holati: active (muvaffaqiyatli bog'langan) yoki failed (bog'lanish muvaffaqiyatsiz).

Kutilgan Javob - HTTP Status: 200

Muhim!

• Agar javob muvaffaqiyatli bo'lsa, OCTO tizimi so'rovni qayta ishlangan deb hisoblaydi.
• Agar javob muvaffaqiyatsiz bo'lsa, OCTO tizimi so'rovni uch marta takrorlaydi.
• Uch marta urinishdan keyin muvaffaqiyatli javob olinmasa, OCTO so'rov yuborishni to'xtatadi va tokenni bekor qiladi.

Muvaffaqiyatli javob - HTTP Status: 200

{
    "status": "success",
    "message": "Callback processed successfully"
}

Muvaffaqiyatsiz javob - HTTP Status: 400 va yuqori

{
    "status": "error",
    "message": "Invalid shop_transaction_id"
}

block_card_token

• URL: https://secure.octo.uz/block_card_token
• Method: POST
• Content-type: application/json

So'rovnoma

{
    "octo_shop_id": 242,
    "octo_secret": "1d45df74-bb95-47cf-a616-8d6dcee2e10d",
    "card_token": "sdf9g87sd6f9g876sdf9g876sdf98g"
}

So'rovning parametrlari tavsifi

Parametr	Tur	Majburiylik	Tavsif
octo_shop_id	Integer	Ha	Octo tizimidagi do'konning noyob identifikatori.
octo_secret	String	Ha	So'rovlarni autentifikatsiya qilish uchun maxfiy kalit.
card_token	String	Ha	To'lovni amalga oshirish uchun ishlatiladigan karta tokeni.

Muvaffaqiyatli javob

{
    "error": 0,
    "errMessage": null,
    "status": "blocked"
}

Javob parametrlari

Parametr	Tur	Majburiylik	Tavsif
error	Integer	Ha	Xato kodi. 0 xatolik yo'qligini bildiradi.
errMessage	String	Yo'q	Xato haqida xabar, agar mavjud bo'lsa.
status	String	Ha	Operatsiya holati. Masalan, blocked.

Xato Kodlari

Kod	Tavsif
0	Xatolik yo'q.
1	Ma'lumotlar formati xatosi.
2	Autentifikatsiya xatosi.
4	Xizmatning ichki xatosi.
5	Token topilmadi.
6	Token active holatda emas edi.

Token Holatlari

Holat	Tavsif
active	To'lov uchun tayyor.
blocked	Bloklangan.
init	Karta autentifikatsiya jarayonida.
failed	Autentifikatsiya muvaffaqiyatsiz tugadi.