Asosiy

Host to host (white label) integratsiyasi

Savdogarlar uchun Heleket Host-to-Host (H2H) integratsiyasi

Ushbu yo‘riqnoma Heleket API bilan to‘g‘ridan-to‘g‘ri serverlararo aloqa orqali kriptoto‘lovlarni qabul qilishni tavsiflaydi. Tayyor to‘lov sahifasidan farqli ravishda, backendingiz invoyslarni yaratadi, to‘lov rekvizitlarini oladi va to‘lov holati haqidagi bildirishnomalarni qayta ishlaydi. To‘lov shaklini o‘z tomoningizda ko‘rsatishingiz yoki API javobida qaytarilgan URL manzilidan foydalanishingiz mumkin.

1. Boshlashdan oldin nimalar kerak

To‘lovlarni qabul qilish uchun shaxsiy kabinetingizdan ikkita qiymat kerak:

Qiymat	Qayerdan olish mumkin
Merchant ID	Savdogar UUID identifikatori. Biznes → Savdogarlar → Savdogar sozlamalari bo‘limi.
To‘lov API kaliti	Moderatsiyadan o‘tgandan keyin savdogar sozlamalarida yaratiladi.

Qayerdan olish mumkin Savdogar UUID identifikatori. Biznes → Savdogarlar → Savdogar sozlamalari bo‘limi.
Qayerdan olish mumkin Moderatsiyadan o‘tgandan keyin savdogar sozlamalarida yaratiladi.

To‘lov API kalitini qanday olish mumkin

Biznes → Savdogarlar → Savdogar yaratish bo‘limiga o‘ting va nom kiriting.
Ariza yuboring, sayt URL manzilini kiriting va domenni tasdiqlang.
Savdogar moderatsiyadan o‘tishini kuting.
Tasdiqlangandan so‘ng Sozlamalar bo‘limidan to‘lov API kaliti va Merchant ID’ni nusxalang.

Mablag‘ chiqarish API kaliti Sozlamalar → API bo‘limida alohida beriladi, ikki bosqichli autentifikatsiyani talab qiladi va to‘lovlarni qabul qilish uchun kerak emas.

Barcha so‘rovlar uchun asosiy endpoint:

https://api.heleket.com/

Nusxalash

Barcha API so‘rovlari JSON formatida POST usuli orqali yuboriladi va imzolanishi kerak.

2. So‘rov autentifikatsiyasi va imzosi

Har bir so‘rov ikkita HTTP sarlavhasi orqali autentifikatsiya qilinadi:

Sarlavha	Qiymat
merchant	Sizning Merchant ID (UUID) identifikatoringiz.
sign	So‘rov tanasining imzosi.
Content-Type	`application/json`

Qiymat Sizning Merchant ID (UUID) identifikatoringiz.
Qiymat So‘rov tanasining imzosi.
Qiymat application/json

Imzo — API kalitingiz bilan birlashtirilgan base64 formatida kodlangan JSON so‘rov tanasining MD5 xeshi.

$body = json_encode($data);
$sign = md5(base64_encode($body) . $API_KEY);

Nusxalash

Tana parametrlarisiz so‘rovlar uchun imzoni bo‘sh satrdan hisoblang:

$sign = md5(base64_encode('') . $API_KEY);

Nusxalash

Sleshlarni ekranlash haqida muhim eslatma. PHP birlamchi holatda JSON ichidagi / belgisini ekranlaydi (\/), boshqa ko‘plab tillar esa yo‘q. Imzo so‘rov tanasida yuboriladigan aynan o‘sha satrdan hisoblanadi, shuning uchun imzolash uchun satr va so‘rov tanasi baytma-bayt bir xil bo‘lishi kerak. PHP bo‘lmagan steklarda sleshlarni qo‘lda ekranlang, aks holda imzo mos kelmaydi (xuddi shu muammo vebhuklarni tekshirishda ham yuzaga keladi, 5-bo‘limga qarang).

Imzolangan so‘rov namunasi

curl https://api.heleket.com/v1/payment \
  -X POST \
  -H 'merchant: 8b03432e-385b-4670-8d06-064591096795' \
  -H 'sign: fe99035f86fa436181717b302b95bacff1' \
  -H 'Content-Type: application/json' \
  -d '{"amount":"15","currency":"USD","order_id":"1"}'

Nusxalash

3. H2H oqimi

Mijoz sizda buyurtma rasmiylashtiradi → siz order_id ni o‘z tomoningizda qayd etasiz
Serveringiz → POST /v1/payment → Heleket uuid, manzil, summa, url ni qaytaradi
Siz mijozga rekvizitlar / manzil / QR-kodni (yoki url havolasini) ko‘rsatasiz
Mijoz blokcheynda to‘lov qiladi
Heleket → holat har o‘zgarganda url_callback manzilingizga POST (webhook) yuboradi
Siz vebhuk imzosini tekshirasiz → buyurtmani yangilaysiz
(Zaxira) order_id bo‘yicha POST /v1/payment/info ni vaqti-vaqti bilan so‘raysiz

Faqat vebhukka tayanmang: callback yetib kelmagan holat uchun doimo /v1/payment/info orqali fallback saqlang (6-bo‘lim).

4. To‘lov yaratish

Endpoint:

POST

https://api.heleket.com/v1/payment

Nusxalash

So‘rovning asosiy parametrlari

Parametr	Tur	Majburiy	Tavsif
amount	string	ha	To‘lanadigan summa. Kasr qismi nuqta bilan yoziladi, mas. 10.28.
currency	string	ha	Invoys valyutasi kodi (fiat yoki kriptovalyuta), mas. USD, USDT, BTC.
order_id	string	ha	Buyurtmangiz identifikatori. Faqat harflar, raqamlar, _ va -. Noyob bo‘lishi kerak.
network	string	yo‘q	Blokcheyn tarmog‘i kodi, mas. tron, bsc, eth.
to_currency	string	yo‘q	Summani qayta hisoblash uchun maqsadli kriptovalyuta (har doim kriptovalyuta kodi, fiat emas).
url_callback	string	yo‘q	Heleket holat vebhuklarini yuboradigan URL. Amalda H2H uchun majburiy.
url_return	string	yo‘q	To‘lovdan oldin mijozni to‘lov shaklidan qaytarish manzili.
url_success	string	yo‘q	Muvaffaqiyatli to‘lovdan keyin mijozni qaytarish manzili.
lifetime	integer	yo‘q	Invoysning amal qilish muddati soniyalarda (300–43200, birlamchi qiymat 3600).
subtract	integer	yo‘q	Komissiyaning necha foizini mijoz zimmasiga yuklash kerak (0–100).
accuracy_payment_percent	numeric	yo‘q	Ruxsat etilgan kam to‘lov foizi (0–5): kam to‘lov shu chegarada bo‘lsa, invoys to‘langan deb yopiladi.
is_payment_multiple	boolean	yo‘q	Qoldiqni qo‘shimcha to‘lashga ruxsat berish. Birlamchi qiymat true.
additional_data	string	yo‘q	Siz uchun ixtiyoriy satr (mijozga ko‘rinmaydi), 255 belgigacha.
currencies	array	yo‘q	To‘lov uchun valyutalar/tarmoqlarning oq ro‘yxati.
except_currencies	array	yo‘q	Valyutalar/tarmoqlarning qora ro‘yxati.
discount_percent	integer	yo‘q	Chegirma (musbat) yoki ustama (manfiy), -99 dan 100 gacha.
is_refresh	boolean	yo‘q	Muddati o‘tgan invoysni o‘sha order_id bo‘yicha yangilash (yangi manzil va muddat).

Tur string Majburiy ha Tavsif To‘lanadigan summa. Kasr qismi nuqta bilan yoziladi, mas. 10.28.
Tur string Majburiy ha Tavsif Invoys valyutasi kodi (fiat yoki kriptovalyuta), mas. USD, USDT, BTC.
Tur string Majburiy ha Tavsif Buyurtmangiz identifikatori. Faqat harflar, raqamlar, _ va -. Noyob bo‘lishi kerak.
Tur string Majburiy yo‘q Tavsif Blokcheyn tarmog‘i kodi, mas. tron, bsc, eth.
Tur string Majburiy yo‘q Tavsif Summani qayta hisoblash uchun maqsadli kriptovalyuta (har doim kriptovalyuta kodi, fiat emas).
Tur string Majburiy yo‘q Tavsif Heleket holat vebhuklarini yuboradigan URL. Amalda H2H uchun majburiy.
Tur string Majburiy yo‘q Tavsif To‘lovdan oldin mijozni to‘lov shaklidan qaytarish manzili.
Tur string Majburiy yo‘q Tavsif Muvaffaqiyatli to‘lovdan keyin mijozni qaytarish manzili.
Tur integer Majburiy yo‘q Tavsif Invoysning amal qilish muddati soniyalarda (300–43200, birlamchi qiymat 3600).
Tur integer Majburiy yo‘q Tavsif Komissiyaning necha foizini mijoz zimmasiga yuklash kerak (0–100).
Tur numeric Majburiy yo‘q Tavsif Ruxsat etilgan kam to‘lov foizi (0–5): kam to‘lov shu chegarada bo‘lsa, invoys to‘langan deb yopiladi.
Tur boolean Majburiy yo‘q Tavsif Qoldiqni qo‘shimcha to‘lashga ruxsat berish. Birlamchi qiymat true.
Tur string Majburiy yo‘q Tavsif Siz uchun ixtiyoriy satr (mijozga ko‘rinmaydi), 255 belgigacha.
Tur array Majburiy yo‘q Tavsif To‘lov uchun valyutalar/tarmoqlarning oq ro‘yxati.
Tur array Majburiy yo‘q Tavsif Valyutalar/tarmoqlarning qora ro‘yxati.
Tur integer Majburiy yo‘q Tavsif Chegirma (musbat) yoki ustama (manfiy), -99 dan 100 gacha.
Tur boolean Majburiy yo‘q Tavsif Muddati o‘tgan invoysni o‘sha order_id bo‘yicha yangilash (yangi manzil va muddat).

order_id haqida: agar shu order_id bilan invoys mavjud bo‘lsa, yangisi yaratilmaydi — mavjud invoysning to‘lov rekvizitlari qaytariladi. Bu idempotentlik uchun qulay: ayni buyurtma bo‘yicha takroriy so‘rov xavfsiz.

Hamyon manzili qachon darhol keladi. address maydoni faqat to‘lov valyutasi aniq belgilanganida invoys yaratilishi paytida to‘ldiriladi: kriptovalyuta + tarmoq (to_currency + network) berilgan yoki kriptovalyutaning yagona tarmog‘i bor (mas. BTC). Aks holda mijoz to‘lov sahifasida valyuta/tarmoqni tanlaydi va address keyinroq paydo bo‘ladi.

So‘rov tanasi namunalari

15 USD uchun minimal invoys (mijoz kriptovalyuta va tarmoqni o‘zi tanlaydi):

{ "amount": "15", "currency": "USD", "order_id": "1" }

Nusxalash

TRON tarmog‘idagi 20 USDT invoysi — manzil darhol beriladi:

{ "amount": "20", "currency": "USDT", "order_id": "1", "network": "tron" }

Nusxalash

25 USD invoys, istalgan tarmoqda faqat USDT orqali to‘lash:

{ "amount": "25", "currency": "USD", "order_id": "1", "to_currency": "USDT" }

Nusxalash

Javob namunasi

{
1  "state": 0,
2  "result": {
3    "uuid": "1ec87133-b22d-4643-988f-cac29a6ac85d",
4    "order_id": "3",
5    "amount": "20000.00",
6    "payment_amount": null,
7    "payer_amount": "254.92",
8    "payer_currency": "USDT",
9    "currency": "RUB",
10    "merchant_amount": "249.82816502",
11    "network": "bsc",
12    "address": "0x2b...",
13    "txid": null,
14    "payment_status": "check",
15    "url": "https://pay.heleket.com/pay/1ec87133-b22d-4643-988f-cac29a6ac85d",
16    "expired_at": 1753202502,
17    "is_final": false,
18    "commission": "5.09853397",
19    "address_qr_code": "data:image/png;base64 ..."
20  }
21}

Nusxalash

Javobning asosiy maydonlari

Maydon	Maqsad
uuid	Heleket tizimidagi invoys UUID identifikatori. Uni buyurtma bilan birga saqlang.
address	To‘lov uchun hamyon manzili. Valyuta tanlanmaguncha null bo‘lishi mumkin.
payer_amount	Chegirma yoki ustamani hisobga olgan holda payer_currency valyutasida to‘lanadigan summa.
payer_currency	To‘lov valyutasi. null mijoz hali valyutani tanlamaganini bildiradi.
merchant_amount	Komissiyalar chegirilgandan keyin balansingizga tushadigan summa.
payment_status	Joriy holat (7-bo‘limga qarang).
url	To‘lov shaklini o‘zingiz ko‘rsatmasangiz, Heleket to‘lov sahifasiga havola.
address_qr_code	To‘lov manzilining base64 formatidagi QR-kodi.
expired_at	Invoysning amal qilish muddati tugaydigan Unix vaqt belgisi.
is_final	Invoys yopilganini va endi uni to‘lab bo‘lmasligini bildiradi.

Maqsad Heleket tizimidagi invoys UUID identifikatori. Uni buyurtma bilan birga saqlang.
Maqsad To‘lov uchun hamyon manzili. Valyuta tanlanmaguncha null bo‘lishi mumkin.
Maqsad Chegirma yoki ustamani hisobga olgan holda payer_currency valyutasida to‘lanadigan summa.
Maqsad To‘lov valyutasi. null mijoz hali valyutani tanlamaganini bildiradi.
Maqsad Komissiyalar chegirilgandan keyin balansingizga tushadigan summa.
Maqsad Joriy holat (7-bo‘limga qarang).
Maqsad To‘lov shaklini o‘zingiz ko‘rsatmasangiz, Heleket to‘lov sahifasiga havola.
Maqsad To‘lov manzilining base64 formatidagi QR-kodi.
Maqsad Invoysning amal qilish muddati tugaydigan Unix vaqt belgisi.
Maqsad Invoys yopilganini va endi uni to‘lab bo‘lmasligini bildiradi.

state: 0 muvaffaqiyatni anglatadi. Validatsiya xatolarida state: 1 (8-bo‘lim).

5. Webhook orqali to‘lov holati bildirishnomalari

Invoys holati o‘zgarganda Heleket POST webhook yuboradi.

Webhookning asosiy maydonlari

Maydon	Tavsif
type	Turi: payment yoki wallet.
uuid	To‘lov UUID-si.
order_id	Buyurtma identifikatoringiz — buyurtmani shu orqali topasiz.
amount	Invoys summasi.
payment_amount	Mijoz amalda qancha to‘ladi.
payment_amount_usd	USDda amalda to‘langan summa.
merchant_amount	Komissiya chegirilgandan so‘ng balansga o‘tkazilgan summa.
commission	Heleket komissiyasi.
is_final	Invoys yakuniy yopilganmi.
status	To‘lov holati (7-bo‘limga qarang).
from	To‘lovchi hamyonining manzili.
network	To‘lov tarmog‘i.
currency	Invoys valyutasi.
payer_currency	Amalda to‘langan valyuta.
txid	Blokcheyndagi tranzaksiya xeshi (p2p/qo‘lda yopishda bo‘lmasligi mumkin).
sign	Tekshirish uchun vebhuk imzosi.

Tavsif Turi: payment yoki wallet.
Tavsif To‘lov UUID-si.
Tavsif Buyurtma identifikatoringiz — buyurtmani shu orqali topasiz.
Tavsif Invoys summasi.
Tavsif Mijoz amalda qancha to‘ladi.
Tavsif USDda amalda to‘langan summa.
Tavsif Komissiya chegirilgandan so‘ng balansga o‘tkazilgan summa.
Tavsif Heleket komissiyasi.
Tavsif Invoys yakuniy yopilganmi.
Tavsif To‘lov holati (7-bo‘limga qarang).
Tavsif To‘lovchi hamyonining manzili.
Tavsif To‘lov tarmog‘i.
Tavsif Invoys valyutasi.
Tavsif Amalda to‘langan valyuta.
Tavsif Blokcheyndagi tranzaksiya xeshi (p2p/qo‘lda yopishda bo‘lmasligi mumkin).
Tavsif Tekshirish uchun vebhuk imzosi.

Webhook yuklamasi namunasi

{
1  "type": "payment",
2  "uuid": "62f88b36-a9d5-4fa6-aa26-e040c3dbf26d",
3  "order_id": "97a75bf8eda5cca41ba9d2e104840fcd",
4  "amount": "3.00000000",
5  "payment_amount": "3.00000000",
6  "merchant_amount": "2.94000000",
7  "commission": "0.06000000",
8  "is_final": true,
9  "status": "paid",
10  "from": "THgEWubVc8tPKXLJ4VZ5zbiiAK7AgqSeGH",
11  "network": "tron",
12  "currency": "TRX",
13  "payer_currency": "TRX",
14  "txid": "6f0d9c8374db57cac0d806251473de754f361c83a03cd805f74aa9da3193486b",
15  "sign": "a76c0d77f3e8e1a419b138af04ab600a"
16}

Nusxalash

Webhookni majburiy tekshirish

Vebhuk asosida mahsulot berishingiz yoki foydalanuvchi balansini to‘ldirishingiz sababli, so‘rov aynan Heleket tomonidan yuborilganiga ishonch hosil qilishingiz kerak. Ikkala usul bilan ham tekshiring:

Callback so‘rovlariga faqat Heleket IP manzilidan ruxsat bering: 31.133.220.8.
Imzoni tekshirish. Imzo so‘rovlar bilan bir xil algoritm bo‘yicha hisoblanadi, ammo quyidagicha tekshiriladi:

// 1. So‘rovning xom tanasini o‘qiymiz
1$data = json_decode(file_get_contents('php://input'), true);
2
3// 2. Imzoni massivdan olamiz va o‘chiramiz
4$sign = $data['sign'];
5unset($data['sign']);
6
7// 3. Tananing (sign-siz) xeshini + to‘lov API kalitingizni hisoblaymiz
8$hash = md5(base64_encode(json_encode($data, JSON_UNESCAPED_UNICODE)) . $apiPaymentKey);
9
10// 4. Solishtiramiz
11if (!hash_equals($hash, $sign)) {
12    // imzo noto‘g‘ri — rad etish
13    http_response_code(400);
14    exit;
15}

Nusxalash

2-bo‘limdagi sleshlar muammosi bu yerda ham mavjud: JSON’ni PHP’dan tashqarida kodlashda / belgisini qo‘lda ekranlang (JS’da JSON.stringify(data).replace(/\//g, "\\/")), aks holda imzo mos kelmaydi.

Webhookni qayta ishlash bo‘yicha tavsiyalar

Idempotentlik. Bir xil holat takroran kelishi mumkin (jumladan, qo‘lda qayta yuborilganda). order_id + status ga bog‘lang va mahsulotni ikki marta bermang.
Oraliq holatlarga emas, yakuniy holatlarga (paid, paid_over) javob bering.
HTTP 200 javobini faqat webhook muvaffaqiyatli qayta ishlangandan keyin qaytaring.
payment_amount va merchant_amount qiymatlarini kutilgan buyurtma summasi bilan solishtiring.

6. Webhook uchun zaxira sifatida holatni so‘rab turish

Endpoint:

POST

https://api.heleket.com/v1/payment/info

Nusxalash

uuid yoki order_id ni yuboring (ikkalasi ham yuborilsa, order_id ustuvor bo‘ladi).

curl https://api.heleket.com/v1/payment/info \
  -X POST \
  -H 'merchant: 8b03432e-385b-4670-8d06-064591096795' \
  -H 'sign: <tana imzosi>' \
  -H 'Content-Type: application/json' \
  -d '{"order_id":"1"}'

Nusxalash

Javob joriy payment_status va is_final qiymatlariga ega o‘sha to‘lov obyektini qaytaradi. Bu usuldan «osilib qolgan» buyurtmalarni davriy solishtirish uchun foydalaning, asosiy mexanizm sifatida emas (vebhuklar tezroq va kamroq so‘rov talab qiladi).

7. To‘lov holatlari

Holat	Yakuniy	Maʼnosi
check	yo‘q	Blokcheynda tranzaksiya paydo bo‘lishini kutish.
process	yo‘q	To‘lov qayta ishlanmoqda.
confirm_check	yo‘q	Tranzaksiya ko‘rindi, tarmoqning kerakli tasdiqlari sonini kutyapmiz.
wrong_amount_waiting	yo‘q	Qoldiqni qo‘shimcha to‘lash imkoniyati bilan kam to‘lov.
paid	ha	Kerakli summa aniq to‘landi. Tovarni bering.
paid_over	ha	Kerakli summadan ko‘proq to‘landi. Tovarni bering.
wrong_amount	ha	Mijoz kerakli summadan kamroq to‘ladi.
fail	ha	To‘lov xatosi.
cancel	ha	To‘lov bekor qilindi, mijoz to‘lamadi.
system_fail	ha	Tizim xatosi.
locked	ha	Mablag‘lar AML dasturi bo‘yicha bloklandi.
refund_process	yo‘q	Qaytarish qayta ishlanmoqda.
refund_paid	ha	Qaytarish bajarildi.
refund_fail	ha	Qaytarish xatosi.

Yakuniy yo‘q Maʼnosi Blokcheynda tranzaksiya paydo bo‘lishini kutish.
Yakuniy yo‘q Maʼnosi To‘lov qayta ishlanmoqda.
Yakuniy yo‘q Maʼnosi Tranzaksiya ko‘rindi, tarmoqning kerakli tasdiqlari sonini kutyapmiz.
Yakuniy yo‘q Maʼnosi Qoldiqni qo‘shimcha to‘lash imkoniyati bilan kam to‘lov.
Yakuniy ha Maʼnosi Kerakli summa aniq to‘landi. Tovarni bering.
Yakuniy ha Maʼnosi Kerakli summadan ko‘proq to‘landi. Tovarni bering.
Yakuniy ha Maʼnosi Mijoz kerakli summadan kamroq to‘ladi.
Yakuniy ha Maʼnosi To‘lov xatosi.
Yakuniy ha Maʼnosi To‘lov bekor qilindi, mijoz to‘lamadi.
Yakuniy ha Maʼnosi Tizim xatosi.
Yakuniy ha Maʼnosi Mablag‘lar AML dasturi bo‘yicha bloklandi.
Yakuniy yo‘q Maʼnosi Qaytarish qayta ishlanmoqda.
Yakuniy ha Maʼnosi Qaytarish bajarildi.
Yakuniy ha Maʼnosi Qaytarish xatosi.

paid va paid_over holatlarini muvaffaqiyatli to‘lov deb hisoblang. confirm_check webhooklarda oraliq holat sifatida ham kelishi mumkin.

8. Xatolarni qayta ishlash

Validatsiya xatolari — HTTP 422, state: 1:

{ "state": 1, "errors": { "amount": ["validation.required"] } }

Nusxalash

Ko‘p uchraydigan xabarlar (state: 1, message maydoni):

Xabar	Sabab
The network was not found	Qo‘llab-quvvatlanmaydigan tarmoq kodi yuborildi.
The currency was not found	Qo‘llab-quvvatlanmaydigan valyuta kodi yuborildi.
Not found service to_currency	to_currency uchun to‘lov xizmati mavjud emas.
Minimum amount 0.5 USDT	Summa valyuta uchun minimal miqdordan kam.
Maximum amount 10000000 USDT	Summa valyuta uchun maksimal miqdordan oshib ketgan.
Wallet not found	To‘lov valyutasi uchun faol savdogar hamyoni mavjud emas.
You are forbidden	To‘lovlar bloklangan. Qo‘llab-quvvatlash xizmatiga murojaat qiling.
Gateway error / Server error	Vaqtinchalik texnik muammo yuz berdi va to‘lov mavjud emas.

Sabab Qo‘llab-quvvatlanmaydigan tarmoq kodi yuborildi.
Sabab Qo‘llab-quvvatlanmaydigan valyuta kodi yuborildi.
Sabab to_currency uchun to‘lov xizmati mavjud emas.
Sabab Summa valyuta uchun minimal miqdordan kam.
Sabab Summa valyuta uchun maksimal miqdordan oshib ketgan.
Sabab To‘lov valyutasi uchun faol savdogar hamyoni mavjud emas.
Sabab To‘lovlar bloklangan. Qo‘llab-quvvatlash xizmatiga murojaat qiling.
Sabab Vaqtinchalik texnik muammo yuz berdi va to‘lov mavjud emas.

Ichki xato — HTTP 500:

{ "message": "Server error, #1", "code": 500, "error": null }

Nusxalash

Gateway error, Server error va HTTP 500 xatolarini vaqtinchalik deb hisoblang va eksponensial kechikish bilan qayta urinib ko‘ring.

9. Integratsiya tekshiruv ro‘yxati

Savdogar tasdiqlangan, Merchant ID va to‘lov API kaliti olingan.
So‘rovlarni imzolash va qiya chiziqlarni ekranlash amalga oshirilgan.
Invoys POST /v1/payment orqali noyob order_id va belgilangan url_callback bilan yaratiladi.
Webhook endpointi HTTPS orqali mavjud va POST so‘rovlarini qabul qiladi.
Webhook so‘rovlari IP manzili va imzo orqali tekshiriladi.
Webhook idempotent tarzda qayta ishlanadi.
Mahsulot yoki xizmat summa tekshirilgandan keyin faqat paid va paid_over holatlarida taqdim etiladi.
POST /v1/payment/info orqali zaxira so‘rov mexanizmi amalga oshirilgan.
uuid, order_id, txid va holatlar jurnalga yoziladi.
API kalitlari kod yoki repozitoriyda emas, maxfiy saqlash joyida saqlanadi.

Valyuta va tarmoq kodlari, qaytarish usullari, statik hamyonlar va mablag‘ chiqarish haqida tegishli Heleket hujjatlari bo‘limlarida o‘qing.

Savdogarlar uchun Heleket Host-to-Host (H2H) integratsiyasi

1. Boshlashdan oldin nimalar kerak

To‘lovlarni qabul qilish uchun shaxsiy kabinetingizdan ikkita qiymat kerak:

Qiymat	Qayerdan olish mumkin
Merchant ID	Savdogar UUID identifikatori. Biznes → Savdogarlar → Savdogar sozlamalari bo‘limi.
To‘lov API kaliti	Moderatsiyadan o‘tgandan keyin savdogar sozlamalarida yaratiladi.

Qayerdan olish mumkin Savdogar UUID identifikatori. Biznes → Savdogarlar → Savdogar sozlamalari bo‘limi.
Qayerdan olish mumkin Moderatsiyadan o‘tgandan keyin savdogar sozlamalarida yaratiladi.

To‘lov API kalitini qanday olish mumkin

Biznes → Savdogarlar → Savdogar yaratish bo‘limiga o‘ting va nom kiriting.
Ariza yuboring, sayt URL manzilini kiriting va domenni tasdiqlang.
Savdogar moderatsiyadan o‘tishini kuting.
Tasdiqlangandan so‘ng Sozlamalar bo‘limidan to‘lov API kaliti va Merchant ID’ni nusxalang.

Mablag‘ chiqarish API kaliti Sozlamalar → API bo‘limida alohida beriladi, ikki bosqichli autentifikatsiyani talab qiladi va to‘lovlarni qabul qilish uchun kerak emas.

Barcha so‘rovlar uchun asosiy endpoint:

https://api.heleket.com/

Nusxalash

Barcha API so‘rovlari JSON formatida POST usuli orqali yuboriladi va imzolanishi kerak.

2. So‘rov autentifikatsiyasi va imzosi

Har bir so‘rov ikkita HTTP sarlavhasi orqali autentifikatsiya qilinadi:

Sarlavha	Qiymat
merchant	Sizning Merchant ID (UUID) identifikatoringiz.
sign	So‘rov tanasining imzosi.
Content-Type	`application/json`

Qiymat Sizning Merchant ID (UUID) identifikatoringiz.
Qiymat So‘rov tanasining imzosi.
Qiymat application/json

Imzo — API kalitingiz bilan birlashtirilgan base64 formatida kodlangan JSON so‘rov tanasining MD5 xeshi.

$body = json_encode($data);
$sign = md5(base64_encode($body) . $API_KEY);

Nusxalash

Tana parametrlarisiz so‘rovlar uchun imzoni bo‘sh satrdan hisoblang:

$sign = md5(base64_encode('') . $API_KEY);

Nusxalash

Imzolangan so‘rov namunasi

curl https://api.heleket.com/v1/payment \
  -X POST \
  -H 'merchant: 8b03432e-385b-4670-8d06-064591096795' \
  -H 'sign: fe99035f86fa436181717b302b95bacff1' \
  -H 'Content-Type: application/json' \
  -d '{"amount":"15","currency":"USD","order_id":"1"}'

Nusxalash

3. H2H oqimi

Mijoz sizda buyurtma rasmiylashtiradi → siz order_id ni o‘z tomoningizda qayd etasiz
Serveringiz → POST /v1/payment → Heleket uuid, manzil, summa, url ni qaytaradi
Siz mijozga rekvizitlar / manzil / QR-kodni (yoki url havolasini) ko‘rsatasiz
Mijoz blokcheynda to‘lov qiladi
Heleket → holat har o‘zgarganda url_callback manzilingizga POST (webhook) yuboradi
Siz vebhuk imzosini tekshirasiz → buyurtmani yangilaysiz
(Zaxira) order_id bo‘yicha POST /v1/payment/info ni vaqti-vaqti bilan so‘raysiz

Faqat vebhukka tayanmang: callback yetib kelmagan holat uchun doimo /v1/payment/info orqali fallback saqlang (6-bo‘lim).

4. To‘lov yaratish

Endpoint:

POST

https://api.heleket.com/v1/payment

Nusxalash

So‘rovning asosiy parametrlari

Parametr	Tur	Majburiy	Tavsif
amount	string	ha	To‘lanadigan summa. Kasr qismi nuqta bilan yoziladi, mas. 10.28.
currency	string	ha	Invoys valyutasi kodi (fiat yoki kriptovalyuta), mas. USD, USDT, BTC.
order_id	string	ha	Buyurtmangiz identifikatori. Faqat harflar, raqamlar, _ va -. Noyob bo‘lishi kerak.
network	string	yo‘q	Blokcheyn tarmog‘i kodi, mas. tron, bsc, eth.
to_currency	string	yo‘q	Summani qayta hisoblash uchun maqsadli kriptovalyuta (har doim kriptovalyuta kodi, fiat emas).
url_callback	string	yo‘q	Heleket holat vebhuklarini yuboradigan URL. Amalda H2H uchun majburiy.
url_return	string	yo‘q	To‘lovdan oldin mijozni to‘lov shaklidan qaytarish manzili.
url_success	string	yo‘q	Muvaffaqiyatli to‘lovdan keyin mijozni qaytarish manzili.
lifetime	integer	yo‘q	Invoysning amal qilish muddati soniyalarda (300–43200, birlamchi qiymat 3600).
subtract	integer	yo‘q	Komissiyaning necha foizini mijoz zimmasiga yuklash kerak (0–100).
accuracy_payment_percent	numeric	yo‘q	Ruxsat etilgan kam to‘lov foizi (0–5): kam to‘lov shu chegarada bo‘lsa, invoys to‘langan deb yopiladi.
is_payment_multiple	boolean	yo‘q	Qoldiqni qo‘shimcha to‘lashga ruxsat berish. Birlamchi qiymat true.
additional_data	string	yo‘q	Siz uchun ixtiyoriy satr (mijozga ko‘rinmaydi), 255 belgigacha.
currencies	array	yo‘q	To‘lov uchun valyutalar/tarmoqlarning oq ro‘yxati.
except_currencies	array	yo‘q	Valyutalar/tarmoqlarning qora ro‘yxati.
discount_percent	integer	yo‘q	Chegirma (musbat) yoki ustama (manfiy), -99 dan 100 gacha.
is_refresh	boolean	yo‘q	Muddati o‘tgan invoysni o‘sha order_id bo‘yicha yangilash (yangi manzil va muddat).

Tur string Majburiy ha Tavsif To‘lanadigan summa. Kasr qismi nuqta bilan yoziladi, mas. 10.28.
Tur string Majburiy ha Tavsif Invoys valyutasi kodi (fiat yoki kriptovalyuta), mas. USD, USDT, BTC.
Tur string Majburiy ha Tavsif Buyurtmangiz identifikatori. Faqat harflar, raqamlar, _ va -. Noyob bo‘lishi kerak.
Tur string Majburiy yo‘q Tavsif Blokcheyn tarmog‘i kodi, mas. tron, bsc, eth.
Tur string Majburiy yo‘q Tavsif Summani qayta hisoblash uchun maqsadli kriptovalyuta (har doim kriptovalyuta kodi, fiat emas).
Tur string Majburiy yo‘q Tavsif Heleket holat vebhuklarini yuboradigan URL. Amalda H2H uchun majburiy.
Tur string Majburiy yo‘q Tavsif To‘lovdan oldin mijozni to‘lov shaklidan qaytarish manzili.
Tur string Majburiy yo‘q Tavsif Muvaffaqiyatli to‘lovdan keyin mijozni qaytarish manzili.
Tur integer Majburiy yo‘q Tavsif Invoysning amal qilish muddati soniyalarda (300–43200, birlamchi qiymat 3600).
Tur integer Majburiy yo‘q Tavsif Komissiyaning necha foizini mijoz zimmasiga yuklash kerak (0–100).
Tur numeric Majburiy yo‘q Tavsif Ruxsat etilgan kam to‘lov foizi (0–5): kam to‘lov shu chegarada bo‘lsa, invoys to‘langan deb yopiladi.
Tur boolean Majburiy yo‘q Tavsif Qoldiqni qo‘shimcha to‘lashga ruxsat berish. Birlamchi qiymat true.
Tur string Majburiy yo‘q Tavsif Siz uchun ixtiyoriy satr (mijozga ko‘rinmaydi), 255 belgigacha.
Tur array Majburiy yo‘q Tavsif To‘lov uchun valyutalar/tarmoqlarning oq ro‘yxati.
Tur array Majburiy yo‘q Tavsif Valyutalar/tarmoqlarning qora ro‘yxati.
Tur integer Majburiy yo‘q Tavsif Chegirma (musbat) yoki ustama (manfiy), -99 dan 100 gacha.
Tur boolean Majburiy yo‘q Tavsif Muddati o‘tgan invoysni o‘sha order_id bo‘yicha yangilash (yangi manzil va muddat).

So‘rov tanasi namunalari

15 USD uchun minimal invoys (mijoz kriptovalyuta va tarmoqni o‘zi tanlaydi):

{ "amount": "15", "currency": "USD", "order_id": "1" }

Nusxalash

TRON tarmog‘idagi 20 USDT invoysi — manzil darhol beriladi:

{ "amount": "20", "currency": "USDT", "order_id": "1", "network": "tron" }

Nusxalash

25 USD invoys, istalgan tarmoqda faqat USDT orqali to‘lash:

{ "amount": "25", "currency": "USD", "order_id": "1", "to_currency": "USDT" }

Nusxalash

Javob namunasi

{
1  "state": 0,
2  "result": {
3    "uuid": "1ec87133-b22d-4643-988f-cac29a6ac85d",
4    "order_id": "3",
5    "amount": "20000.00",
6    "payment_amount": null,
7    "payer_amount": "254.92",
8    "payer_currency": "USDT",
9    "currency": "RUB",
10    "merchant_amount": "249.82816502",
11    "network": "bsc",
12    "address": "0x2b...",
13    "txid": null,
14    "payment_status": "check",
15    "url": "https://pay.heleket.com/pay/1ec87133-b22d-4643-988f-cac29a6ac85d",
16    "expired_at": 1753202502,
17    "is_final": false,
18    "commission": "5.09853397",
19    "address_qr_code": "data:image/png;base64 ..."
20  }
21}

Nusxalash

Javobning asosiy maydonlari

Maydon	Maqsad
uuid	Heleket tizimidagi invoys UUID identifikatori. Uni buyurtma bilan birga saqlang.
address	To‘lov uchun hamyon manzili. Valyuta tanlanmaguncha null bo‘lishi mumkin.
payer_amount	Chegirma yoki ustamani hisobga olgan holda payer_currency valyutasida to‘lanadigan summa.
payer_currency	To‘lov valyutasi. null mijoz hali valyutani tanlamaganini bildiradi.
merchant_amount	Komissiyalar chegirilgandan keyin balansingizga tushadigan summa.
payment_status	Joriy holat (7-bo‘limga qarang).
url	To‘lov shaklini o‘zingiz ko‘rsatmasangiz, Heleket to‘lov sahifasiga havola.
address_qr_code	To‘lov manzilining base64 formatidagi QR-kodi.
expired_at	Invoysning amal qilish muddati tugaydigan Unix vaqt belgisi.
is_final	Invoys yopilganini va endi uni to‘lab bo‘lmasligini bildiradi.

Maqsad Heleket tizimidagi invoys UUID identifikatori. Uni buyurtma bilan birga saqlang.
Maqsad To‘lov uchun hamyon manzili. Valyuta tanlanmaguncha null bo‘lishi mumkin.
Maqsad Chegirma yoki ustamani hisobga olgan holda payer_currency valyutasida to‘lanadigan summa.
Maqsad To‘lov valyutasi. null mijoz hali valyutani tanlamaganini bildiradi.
Maqsad Komissiyalar chegirilgandan keyin balansingizga tushadigan summa.
Maqsad Joriy holat (7-bo‘limga qarang).
Maqsad To‘lov shaklini o‘zingiz ko‘rsatmasangiz, Heleket to‘lov sahifasiga havola.
Maqsad To‘lov manzilining base64 formatidagi QR-kodi.
Maqsad Invoysning amal qilish muddati tugaydigan Unix vaqt belgisi.
Maqsad Invoys yopilganini va endi uni to‘lab bo‘lmasligini bildiradi.

state: 0 muvaffaqiyatni anglatadi. Validatsiya xatolarida state: 1 (8-bo‘lim).

5. Webhook orqali to‘lov holati bildirishnomalari

Invoys holati o‘zgarganda Heleket POST webhook yuboradi.

Webhookning asosiy maydonlari

Maydon	Tavsif
type	Turi: payment yoki wallet.
uuid	To‘lov UUID-si.
order_id	Buyurtma identifikatoringiz — buyurtmani shu orqali topasiz.
amount	Invoys summasi.
payment_amount	Mijoz amalda qancha to‘ladi.
payment_amount_usd	USDda amalda to‘langan summa.
merchant_amount	Komissiya chegirilgandan so‘ng balansga o‘tkazilgan summa.
commission	Heleket komissiyasi.
is_final	Invoys yakuniy yopilganmi.
status	To‘lov holati (7-bo‘limga qarang).
from	To‘lovchi hamyonining manzili.
network	To‘lov tarmog‘i.
currency	Invoys valyutasi.
payer_currency	Amalda to‘langan valyuta.
txid	Blokcheyndagi tranzaksiya xeshi (p2p/qo‘lda yopishda bo‘lmasligi mumkin).
sign	Tekshirish uchun vebhuk imzosi.

Tavsif Turi: payment yoki wallet.
Tavsif To‘lov UUID-si.
Tavsif Buyurtma identifikatoringiz — buyurtmani shu orqali topasiz.
Tavsif Invoys summasi.
Tavsif Mijoz amalda qancha to‘ladi.
Tavsif USDda amalda to‘langan summa.
Tavsif Komissiya chegirilgandan so‘ng balansga o‘tkazilgan summa.
Tavsif Heleket komissiyasi.
Tavsif Invoys yakuniy yopilganmi.
Tavsif To‘lov holati (7-bo‘limga qarang).
Tavsif To‘lovchi hamyonining manzili.
Tavsif To‘lov tarmog‘i.
Tavsif Invoys valyutasi.
Tavsif Amalda to‘langan valyuta.
Tavsif Blokcheyndagi tranzaksiya xeshi (p2p/qo‘lda yopishda bo‘lmasligi mumkin).
Tavsif Tekshirish uchun vebhuk imzosi.

Webhook yuklamasi namunasi

{
1  "type": "payment",
2  "uuid": "62f88b36-a9d5-4fa6-aa26-e040c3dbf26d",
3  "order_id": "97a75bf8eda5cca41ba9d2e104840fcd",
4  "amount": "3.00000000",
5  "payment_amount": "3.00000000",
6  "merchant_amount": "2.94000000",
7  "commission": "0.06000000",
8  "is_final": true,
9  "status": "paid",
10  "from": "THgEWubVc8tPKXLJ4VZ5zbiiAK7AgqSeGH",
11  "network": "tron",
12  "currency": "TRX",
13  "payer_currency": "TRX",
14  "txid": "6f0d9c8374db57cac0d806251473de754f361c83a03cd805f74aa9da3193486b",
15  "sign": "a76c0d77f3e8e1a419b138af04ab600a"
16}

Nusxalash

Webhookni majburiy tekshirish

Callback so‘rovlariga faqat Heleket IP manzilidan ruxsat bering: 31.133.220.8.
Imzoni tekshirish. Imzo so‘rovlar bilan bir xil algoritm bo‘yicha hisoblanadi, ammo quyidagicha tekshiriladi:

// 1. So‘rovning xom tanasini o‘qiymiz
1$data = json_decode(file_get_contents('php://input'), true);
2
3// 2. Imzoni massivdan olamiz va o‘chiramiz
4$sign = $data['sign'];
5unset($data['sign']);
6
7// 3. Tananing (sign-siz) xeshini + to‘lov API kalitingizni hisoblaymiz
8$hash = md5(base64_encode(json_encode($data, JSON_UNESCAPED_UNICODE)) . $apiPaymentKey);
9
10// 4. Solishtiramiz
11if (!hash_equals($hash, $sign)) {
12    // imzo noto‘g‘ri — rad etish
13    http_response_code(400);
14    exit;
15}

Nusxalash

Webhookni qayta ishlash bo‘yicha tavsiyalar

Idempotentlik. Bir xil holat takroran kelishi mumkin (jumladan, qo‘lda qayta yuborilganda). order_id + status ga bog‘lang va mahsulotni ikki marta bermang.
Oraliq holatlarga emas, yakuniy holatlarga (paid, paid_over) javob bering.
HTTP 200 javobini faqat webhook muvaffaqiyatli qayta ishlangandan keyin qaytaring.
payment_amount va merchant_amount qiymatlarini kutilgan buyurtma summasi bilan solishtiring.

6. Webhook uchun zaxira sifatida holatni so‘rab turish

Endpoint:

POST

https://api.heleket.com/v1/payment/info

Nusxalash

uuid yoki order_id ni yuboring (ikkalasi ham yuborilsa, order_id ustuvor bo‘ladi).

curl https://api.heleket.com/v1/payment/info \
  -X POST \
  -H 'merchant: 8b03432e-385b-4670-8d06-064591096795' \
  -H 'sign: <tana imzosi>' \
  -H 'Content-Type: application/json' \
  -d '{"order_id":"1"}'

Nusxalash

7. To‘lov holatlari

Holat	Yakuniy	Maʼnosi
check	yo‘q	Blokcheynda tranzaksiya paydo bo‘lishini kutish.
process	yo‘q	To‘lov qayta ishlanmoqda.
confirm_check	yo‘q	Tranzaksiya ko‘rindi, tarmoqning kerakli tasdiqlari sonini kutyapmiz.
wrong_amount_waiting	yo‘q	Qoldiqni qo‘shimcha to‘lash imkoniyati bilan kam to‘lov.
paid	ha	Kerakli summa aniq to‘landi. Tovarni bering.
paid_over	ha	Kerakli summadan ko‘proq to‘landi. Tovarni bering.
wrong_amount	ha	Mijoz kerakli summadan kamroq to‘ladi.
fail	ha	To‘lov xatosi.
cancel	ha	To‘lov bekor qilindi, mijoz to‘lamadi.
system_fail	ha	Tizim xatosi.
locked	ha	Mablag‘lar AML dasturi bo‘yicha bloklandi.
refund_process	yo‘q	Qaytarish qayta ishlanmoqda.
refund_paid	ha	Qaytarish bajarildi.
refund_fail	ha	Qaytarish xatosi.

Yakuniy yo‘q Maʼnosi Blokcheynda tranzaksiya paydo bo‘lishini kutish.
Yakuniy yo‘q Maʼnosi To‘lov qayta ishlanmoqda.
Yakuniy yo‘q Maʼnosi Tranzaksiya ko‘rindi, tarmoqning kerakli tasdiqlari sonini kutyapmiz.
Yakuniy yo‘q Maʼnosi Qoldiqni qo‘shimcha to‘lash imkoniyati bilan kam to‘lov.
Yakuniy ha Maʼnosi Kerakli summa aniq to‘landi. Tovarni bering.
Yakuniy ha Maʼnosi Kerakli summadan ko‘proq to‘landi. Tovarni bering.
Yakuniy ha Maʼnosi Mijoz kerakli summadan kamroq to‘ladi.
Yakuniy ha Maʼnosi To‘lov xatosi.
Yakuniy ha Maʼnosi To‘lov bekor qilindi, mijoz to‘lamadi.
Yakuniy ha Maʼnosi Tizim xatosi.
Yakuniy ha Maʼnosi Mablag‘lar AML dasturi bo‘yicha bloklandi.
Yakuniy yo‘q Maʼnosi Qaytarish qayta ishlanmoqda.
Yakuniy ha Maʼnosi Qaytarish bajarildi.
Yakuniy ha Maʼnosi Qaytarish xatosi.

paid va paid_over holatlarini muvaffaqiyatli to‘lov deb hisoblang. confirm_check webhooklarda oraliq holat sifatida ham kelishi mumkin.

8. Xatolarni qayta ishlash

Validatsiya xatolari — HTTP 422, state: 1:

{ "state": 1, "errors": { "amount": ["validation.required"] } }

Nusxalash

Ko‘p uchraydigan xabarlar (state: 1, message maydoni):

Xabar	Sabab
The network was not found	Qo‘llab-quvvatlanmaydigan tarmoq kodi yuborildi.
The currency was not found	Qo‘llab-quvvatlanmaydigan valyuta kodi yuborildi.
Not found service to_currency	to_currency uchun to‘lov xizmati mavjud emas.
Minimum amount 0.5 USDT	Summa valyuta uchun minimal miqdordan kam.
Maximum amount 10000000 USDT	Summa valyuta uchun maksimal miqdordan oshib ketgan.
Wallet not found	To‘lov valyutasi uchun faol savdogar hamyoni mavjud emas.
You are forbidden	To‘lovlar bloklangan. Qo‘llab-quvvatlash xizmatiga murojaat qiling.
Gateway error / Server error	Vaqtinchalik texnik muammo yuz berdi va to‘lov mavjud emas.

Sabab Qo‘llab-quvvatlanmaydigan tarmoq kodi yuborildi.
Sabab Qo‘llab-quvvatlanmaydigan valyuta kodi yuborildi.
Sabab to_currency uchun to‘lov xizmati mavjud emas.
Sabab Summa valyuta uchun minimal miqdordan kam.
Sabab Summa valyuta uchun maksimal miqdordan oshib ketgan.
Sabab To‘lov valyutasi uchun faol savdogar hamyoni mavjud emas.
Sabab To‘lovlar bloklangan. Qo‘llab-quvvatlash xizmatiga murojaat qiling.
Sabab Vaqtinchalik texnik muammo yuz berdi va to‘lov mavjud emas.

Ichki xato — HTTP 500:

{ "message": "Server error, #1", "code": 500, "error": null }

Nusxalash

Gateway error, Server error va HTTP 500 xatolarini vaqtinchalik deb hisoblang va eksponensial kechikish bilan qayta urinib ko‘ring.

9. Integratsiya tekshiruv ro‘yxati

Savdogar tasdiqlangan, Merchant ID va to‘lov API kaliti olingan.
So‘rovlarni imzolash va qiya chiziqlarni ekranlash amalga oshirilgan.
Invoys POST /v1/payment orqali noyob order_id va belgilangan url_callback bilan yaratiladi.
Webhook endpointi HTTPS orqali mavjud va POST so‘rovlarini qabul qiladi.
Webhook so‘rovlari IP manzili va imzo orqali tekshiriladi.
Webhook idempotent tarzda qayta ishlanadi.
Mahsulot yoki xizmat summa tekshirilgandan keyin faqat paid va paid_over holatlarida taqdim etiladi.
POST /v1/payment/info orqali zaxira so‘rov mexanizmi amalga oshirilgan.
uuid, order_id, txid va holatlar jurnalga yoziladi.
API kalitlari kod yoki repozitoriyda emas, maxfiy saqlash joyida saqlanadi.

Valyuta va tarmoq kodlari, qaytarish usullari, statik hamyonlar va mablag‘ chiqarish haqida tegishli Heleket hujjatlari bo‘limlarida o‘qing.