Басты

Host to host (white label) интеграциясы

Мерчанттарға арналған Heleket Host-to-Host (H2H) интеграциясы

Бұл нұсқаулық Heleket API-мен тікелей серверлік өзара әрекеттесу арқылы криптотөлемдерді қабылдауды сипаттайды. Дайын төлем бетін пайдаланудан айырмашылығы, сіздің backend инвойстарды жасайды, төлем деректемелерін алады және төлем мәртебесі туралы хабарландыруларды өңдейді. Төлем формасын өз тарапыңызда көрсете аласыз немесе API жауабында қайтарылған URL мекенжайын пайдалана аласыз.

1. Бастамас бұрын не қажет

Төлемдерді қабылдау үшін жеке кабинеттен екі мән қажет:

Мәні	Қайдан алуға болады
Merchant ID	Мерчант UUID идентификаторы. Бизнес → Мерчанттар → Мерчант баптаулары бөлімі.
Төлем API кілті	Мерчант модерациядан өткеннен кейін оның баптауларында жасалады.

Қайдан алуға болады Мерчант UUID идентификаторы. Бизнес → Мерчанттар → Мерчант баптаулары бөлімі.
Қайдан алуға болады Мерчант модерациядан өткеннен кейін оның баптауларында жасалады.

Төлем API кілтін қалай алуға болады

Бизнес → Мерчанттар → Мерчант жасау бөліміне өтіп, атауын енгізіңіз.
Өтінім жіберіп, сайттың URL мекенжайын көрсетіңіз және доменді растаңыз.
Мерчант модерациядан өткенше күтіңіз.
Мақұлданғаннан кейін Баптаулар бөлімінен төлем API кілті мен Merchant ID көшіріңіз.

Қаражат шығару API кілті Баптаулар → API бөлімінде бөлек шығарылады, екі факторлы аутентификацияны талап етеді және төлемдерді қабылдау үшін қажет емес.

Барлық сұраулардың базалық endpoint-і:

https://api.heleket.com/

Көшіру

Барлық API сұраулары JSON форматында POST әдісімен жіберіледі және қолтаңбалануы керек.

2. Сұрауды аутентификациялау және қолтаңбалау

Әр сұрау екі HTTP тақырыбымен аутентификацияланады:

Тақырып	Мәні
merchant	Сіздің Merchant ID (UUID) идентификаторыңыз.
sign	Сұрау денесінің қолтаңбасы.
Content-Type	`application/json`

Мәні Сіздің Merchant ID (UUID) идентификаторыңыз.
Мәні Сұрау денесінің қолтаңбасы.
Мәні application/json

Қолтаңба — API кілтіңізбен біріктірілген base64 форматында кодталған JSON сұрау денесінің MD5 хеші.

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

Көшіру

Дене параметрлері жоқ сұраулар үшін қолтаңбаны бос жолдан есептеңіз:

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

Көшіру

Слэштерді экрандау туралы маңызды ескерту. PHP әдепкі бойынша JSON ішіндегі / таңбасын экрандайды (\/), ал көптеген басқа тілдер экрандамайды. Қолтаңба денеде жіберілетін дәл сол жолдан есептеледі, сондықтан қолтаңбаға арналған жол мен сұрау денесі байт-байт бойынша бірдей болуы керек. PHP емес стектерде слэштерді қолмен экрандаңыз, әйтпесе қолтаңба сәйкес келмейді (осы мәселе вебхуктарды тексергенде де туындайды, 5-бөлімді қараңыз).

Қолтаңбаланған сұрау мысалы

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"}'

Көшіру

3. H2H ағыны

Клиент сізде тапсырыс рәсімдейді → сіз order_id мәнін өз тарапыңызда тіркейсіз
Сіздің серверіңіз → POST /v1/payment → Heleket uuid, мекенжай, сома, url қайтарады
Сіз клиентке төлем деректерін / мекенжайды / QR-кодты (немесе url сілтемесін) көрсетесіз
Клиент блокчейнде төлейді
Heleket → мәртебе әр өзгерген сайын сіздің url_callback мекенжайыңызға POST (webhook) жібереді
Сіз вебхук қолтаңбасын тексересіз → тапсырысты жаңартасыз
(Қосалқы сақтандыру) order_id бойынша POST /v1/payment/info сұрауын мерзімді түрде жібересіз

Тек вебхукқа сүйенбеңіз: callback жетпей қалған жағдайда әрдайым /v1/payment/info арқылы fallback қолданыңыз (6-бөлім).

4. Төлем жасау

Endpoint:

POST

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

Көшіру

Сұраудың негізгі параметрлері

Параметр	Түрі	Міндетті	Сипаттама
amount	string	иә	Төленетін сома. Бөлшек бөлігі нүкте арқылы жазылады, мыс. 10.28.
currency	string	иә	Инвойс валютасының коды (фиат немесе криптовалюта), мыс. USD, USDT, BTC.
order_id	string	иә	Тапсырысыңыздың идентификаторы. Тек әріптер, сандар, _ және -. Бірегей болуы керек.
network	string	жоқ	Блокчейн желісінің коды, мыс. tron, bsc, eth.
to_currency	string	жоқ	Соманы қайта есептеуге арналған мақсатты криптовалюта (әрқашан криптовалюта коды, фиат емес).
url_callback	string	жоқ	Heleket мәртебе вебхуктарын жіберетін URL. Іс жүзінде H2H үшін міндетті.
url_return	string	жоқ	Төлемге дейін клиентті төлем формасынан қайтару мекенжайы.
url_success	string	жоқ	Сәтті төлемнен кейін клиентті қайтару мекенжайы.
lifetime	integer	жоқ	Инвойстың жарамдылық мерзімі секундпен (300–43200, әдепкі бойынша 3600).
subtract	integer	жоқ	Комиссияның қандай пайызын клиентке жүктеу керек (0–100).
accuracy_payment_percent	numeric	жоқ	Рұқсат етілген кем төлем пайызы (0–5): кем төлем осы шекте болса, инвойс төленген деп жабылады.
is_payment_multiple	boolean	жоқ	Қалдықты қосымша төлеуге рұқсат беру. Әдепкі бойынша true.
additional_data	string	жоқ	Сізге арналған еркін жол (клиентке көрінбейді), 255 таңбаға дейін.
currencies	array	жоқ	Төлемге арналған валюталар/желілердің ақ тізімі.
except_currencies	array	жоқ	Валюталар/желілердің қара тізімі.
discount_percent	integer	жоқ	Жеңілдік (оң) немесе үстеме (теріс), -99-дан 100-ге дейін.
is_refresh	boolean	жоқ	Мерзімі өткен инвойсты сол order_id бойынша жаңарту (жаңа мекенжай және мерзім).

Түрі string Міндетті иә Сипаттама Төленетін сома. Бөлшек бөлігі нүкте арқылы жазылады, мыс. 10.28.
Түрі string Міндетті иә Сипаттама Инвойс валютасының коды (фиат немесе криптовалюта), мыс. USD, USDT, BTC.
Түрі string Міндетті иә Сипаттама Тапсырысыңыздың идентификаторы. Тек әріптер, сандар, _ және -. Бірегей болуы керек.
Түрі string Міндетті жоқ Сипаттама Блокчейн желісінің коды, мыс. tron, bsc, eth.
Түрі string Міндетті жоқ Сипаттама Соманы қайта есептеуге арналған мақсатты криптовалюта (әрқашан криптовалюта коды, фиат емес).
Түрі string Міндетті жоқ Сипаттама Heleket мәртебе вебхуктарын жіберетін URL. Іс жүзінде H2H үшін міндетті.
Түрі string Міндетті жоқ Сипаттама Төлемге дейін клиентті төлем формасынан қайтару мекенжайы.
Түрі string Міндетті жоқ Сипаттама Сәтті төлемнен кейін клиентті қайтару мекенжайы.
Түрі integer Міндетті жоқ Сипаттама Инвойстың жарамдылық мерзімі секундпен (300–43200, әдепкі бойынша 3600).
Түрі integer Міндетті жоқ Сипаттама Комиссияның қандай пайызын клиентке жүктеу керек (0–100).
Түрі numeric Міндетті жоқ Сипаттама Рұқсат етілген кем төлем пайызы (0–5): кем төлем осы шекте болса, инвойс төленген деп жабылады.
Түрі boolean Міндетті жоқ Сипаттама Қалдықты қосымша төлеуге рұқсат беру. Әдепкі бойынша true.
Түрі string Міндетті жоқ Сипаттама Сізге арналған еркін жол (клиентке көрінбейді), 255 таңбаға дейін.
Түрі array Міндетті жоқ Сипаттама Төлемге арналған валюталар/желілердің ақ тізімі.
Түрі array Міндетті жоқ Сипаттама Валюталар/желілердің қара тізімі.
Түрі integer Міндетті жоқ Сипаттама Жеңілдік (оң) немесе үстеме (теріс), -99-дан 100-ге дейін.
Түрі boolean Міндетті жоқ Сипаттама Мерзімі өткен инвойсты сол order_id бойынша жаңарту (жаңа мекенжай және мерзім).

order_id туралы: егер осындай order_id бар инвойс бұрыннан болса, жаңасы жасалмайды — қолданыстағы инвойстың төлем деректері қайтарылады. Бұл идемпотенттілік үшін ыңғайлы: сол тапсырыс бойынша қайталама сұрау қауіпсіз.

Әмиян мекенжайы қашан бірден келеді. address өрісі төлем валютасы бірмәнді анықталған жағдайда ғана жасау кезінде толтырылады: криптовалюта + желі (to_currency + network) берілген немесе криптовалютаның жалғыз желісі бар (мыс. BTC). Әйтпесе клиент төлем бетінде валютаны/желіні таңдайды, ал address кейінірек пайда болады.

Сұрау денесінің мысалдары

15 USD сомасына ең аз инвойс (клиент криптовалюта мен желіні өзі таңдайды):

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

Көшіру

TRON желісіндегі 20 USDT инвойсы — мекенжай бірден беріледі:

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

Көшіру

25 USD инвойсы, кез келген желіде тек USDT арқылы төлеу:

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

Көшіру

Жауап мысалы

{
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}

Көшіру

Жауаптың негізгі өрістері

Өріс	Мақсаты
uuid	Heleket жүйесіндегі инвойс UUID идентификаторы. Оны тапсырыспен бірге сақтаңыз.
address	Төлемге арналған әмиян мекенжайы. Валюта таңдалғанға дейін null болуы мүмкін.
payer_amount	Жеңілдік немесе үстеме ақыны ескере отырып, payer_currency валютасында төленетін сома.
payer_currency	Төлем валютасы. null клиенттің валютаны әлі таңдамағанын білдіреді.
merchant_amount	Комиссиялар шегерілгеннен кейін балансыңызға түсетін сома.
payment_status	Ағымдағы мәртебе (7-бөлімді қараңыз).
url	Төлем формасын өзіңіз көрсетпесеңіз, Heleket төлем бетіне сілтеме.
address_qr_code	Төлем мекенжайының base64 форматындағы QR-коды.
expired_at	Инвойстың мерзімі аяқталатын Unix уақыт белгісі.
is_final	Инвойстың жабылғанын және енді оны төлеу мүмкін еместігін білдіреді.

Мақсаты Heleket жүйесіндегі инвойс UUID идентификаторы. Оны тапсырыспен бірге сақтаңыз.
Мақсаты Төлемге арналған әмиян мекенжайы. Валюта таңдалғанға дейін null болуы мүмкін.
Мақсаты Жеңілдік немесе үстеме ақыны ескере отырып, payer_currency валютасында төленетін сома.
Мақсаты Төлем валютасы. null клиенттің валютаны әлі таңдамағанын білдіреді.
Мақсаты Комиссиялар шегерілгеннен кейін балансыңызға түсетін сома.
Мақсаты Ағымдағы мәртебе (7-бөлімді қараңыз).
Мақсаты Төлем формасын өзіңіз көрсетпесеңіз, Heleket төлем бетіне сілтеме.
Мақсаты Төлем мекенжайының base64 форматындағы QR-коды.
Мақсаты Инвойстың мерзімі аяқталатын Unix уақыт белгісі.
Мақсаты Инвойстың жабылғанын және енді оны төлеу мүмкін еместігін білдіреді.

state: 0 сәттілікті білдіреді. Валидация қателерінде state: 1 (8-бөлім).

5. Webhook арқылы төлем мәртебесі туралы хабарландырулар

Инвойс мәртебесі өзгерген сайын Heleket POST webhook жібереді.

Webhook негізгі өрістері

Өріс	Сипаттама
type	Түрі: payment немесе wallet.
uuid	Төлем UUID-і.
order_id	Сіздің тапсырыс идентификаторыңыз — тапсырысты сол арқылы табасыз.
amount	Инвойс сомасы.
payment_amount	Клиенттің нақты төлеген сомасы.
payment_amount_usd	USD-мен нақты төленген сома.
merchant_amount	Комиссия шегерілгеннен кейін балансқа есептелген сома.
commission	Heleket комиссиясы.
is_final	Инвойстың түпкілікті жабылған-жабылмағаны.
status	Төлем мәртебесі (7-бөлімді қараңыз).
from	Төлеуші әмиянының мекенжайы.
network	Төлем желісі.
currency	Инвойс валютасы.
payer_currency	Нақты төленген валюта.
txid	Блокчейндегі транзакция хэші (p2p/қолмен жабу кезінде болмауы мүмкін).
sign	Тексеруге арналған вебхук қолтаңбасы.

Сипаттама Түрі: payment немесе wallet.
Сипаттама Төлем UUID-і.
Сипаттама Сіздің тапсырыс идентификаторыңыз — тапсырысты сол арқылы табасыз.
Сипаттама Инвойс сомасы.
Сипаттама Клиенттің нақты төлеген сомасы.
Сипаттама USD-мен нақты төленген сома.
Сипаттама Комиссия шегерілгеннен кейін балансқа есептелген сома.
Сипаттама Heleket комиссиясы.
Сипаттама Инвойстың түпкілікті жабылған-жабылмағаны.
Сипаттама Төлем мәртебесі (7-бөлімді қараңыз).
Сипаттама Төлеуші әмиянының мекенжайы.
Сипаттама Төлем желісі.
Сипаттама Инвойс валютасы.
Сипаттама Нақты төленген валюта.
Сипаттама Блокчейндегі транзакция хэші (p2p/қолмен жабу кезінде болмауы мүмкін).
Сипаттама Тексеруге арналған вебхук қолтаңбасы.

Webhook пайдалы жүктемесінің мысалы

{
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}

Көшіру

Webhook міндетті тексеру

Вебхук негізінде тауар беретіндіктен немесе пайдаланушы балансын толтыратындықтан, сұраудың дәл Heleket-тен келгеніне көз жеткізу қажет. Екі тәсілмен де тексеріңіз:

Callback сұрауларына тек Heleket IP мекенжайынан рұқсат беріңіз: 31.133.220.8.
Қолтаңбаны тексеру. Қолтаңба сұраулардағы алгоритммен есептеледі, бірақ былай тексеріледі:

// 1. Сұраудың өңделмеген денесін оқимыз
1$data = json_decode(file_get_contents('php://input'), true);
2
3// 2. Қолтаңбаны массивтен алып, жоямыз
4$sign = $data['sign'];
5unset($data['sign']);
6
7// 3. Денеден (sign-сыз) хэшті + төлем API кілтіңізді есептейміз
8$hash = md5(base64_encode(json_encode($data, JSON_UNESCAPED_UNICODE)) . $apiPaymentKey);
9
10// 4. Салыстырамыз
11if (!hash_equals($hash, $sign)) {
12    // қолтаңба қате — қабылдамау
13    http_response_code(400);
14    exit;
15}

Көшіру

2-бөлімдегі слэш мәселесі мұнда да бар: PHP-ден тыс JSON кодтағанда / таңбасын қолмен экрандаңыз (JS тілінде JSON.stringify(data).replace(/\//g, "\\/")), әйтпесе қолтаңба сәйкес келмейді.

Webhook өңдеу бойынша ұсыныстар

Идемпотенттілік. Бір мәртебе қайталап келуі мүмкін (соның ішінде қолмен қайта жіберілгенде). order_id + status мәндеріне байланыстырыңыз және тауарды екі рет бермеңіз.
Аралық емес, финалдық мәртебелерге (paid, paid_over) әрекет етіңіз.
HTTP 200 жауабын webhook сәтті өңделгеннен кейін ғана қайтарыңыз.
payment_amount және merchant_amount мәндерін күтілетін тапсырыс сомасымен салыстырыңыз.

6. Webhook үшін резервтік механизм ретінде мәртебені сұрау

Endpoint:

POST

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

Көшіру

uuid немесе order_id жіберіңіз (екеуі де жіберілсе, order_id басымдыққа ие).

curl https://api.heleket.com/v1/payment/info \
  -X POST \
  -H 'merchant: 8b03432e-385b-4670-8d06-064591096795' \
  -H 'sign: <дене қолтаңбасы>' \
  -H 'Content-Type: application/json' \
  -d '{"order_id":"1"}'

Көшіру

Жауап ағымдағы payment_status және is_final мәндері бар сол төлем объектісін қайтарады. Бұл әдісті «тұрып қалған» тапсырыстарды мерзімді салыстырып тексеру үшін пайдаланыңыз, негізгі механизм ретінде емес (вебхуктар жылдамырақ және азырақ сұрау қажет етеді).

7. Төлем мәртебелері

Мәртебе	Соңғы	Мағынасы
check	жоқ	Блокчейнде транзакцияның пайда болуын күту.
process	жоқ	Төлем өңделуде.
confirm_check	жоқ	Транзакция көрінеді, желінің қажетті растаулар санын күтеміз.
wrong_amount_waiting	жоқ	Қалдықты қосымша төлеу мүмкіндігі бар кем төлем.
paid	иә	Қажетті сома дәл төленді. Тауарды беріңіз.
paid_over	иә	Қажетті сомадан артық төленді. Тауарды беріңіз.
wrong_amount	иә	Клиент қажетті сомадан аз төледі.
fail	иә	Төлем қатесі.
cancel	иә	Төлемнен бас тартылды, клиент төлем жасамады.
system_fail	иә	Жүйелік қате.
locked	иә	Қаражат AML бағдарламасы бойынша бұғатталды.
refund_process	жоқ	Қайтару өңделуде.
refund_paid	иә	Қайтару орындалды.
refund_fail	иә	Қайтару қатесі.

Соңғы жоқ Мағынасы Блокчейнде транзакцияның пайда болуын күту.
Соңғы жоқ Мағынасы Төлем өңделуде.
Соңғы жоқ Мағынасы Транзакция көрінеді, желінің қажетті растаулар санын күтеміз.
Соңғы жоқ Мағынасы Қалдықты қосымша төлеу мүмкіндігі бар кем төлем.
Соңғы иә Мағынасы Қажетті сома дәл төленді. Тауарды беріңіз.
Соңғы иә Мағынасы Қажетті сомадан артық төленді. Тауарды беріңіз.
Соңғы иә Мағынасы Клиент қажетті сомадан аз төледі.
Соңғы иә Мағынасы Төлем қатесі.
Соңғы иә Мағынасы Төлемнен бас тартылды, клиент төлем жасамады.
Соңғы иә Мағынасы Жүйелік қате.
Соңғы иә Мағынасы Қаражат AML бағдарламасы бойынша бұғатталды.
Соңғы жоқ Мағынасы Қайтару өңделуде.
Соңғы иә Мағынасы Қайтару орындалды.
Соңғы иә Мағынасы Қайтару қатесі.

paid және paid_over мәртебелерін сәтті төлемдер деп есептеңіз. confirm_check webhook хабарландыруларында аралық мәртебе ретінде де кездесуі мүмкін.

8. Қателерді өңдеу

Валидация қателері — HTTP 422, state: 1:

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

Көшіру

Жиі кездесетін хабарламалар (state: 1, message өрісі):

Хабарлама	Себебі
The network was not found	Қолдау көрсетілмейтін желі коды жіберілді.
The currency was not found	Қолдау көрсетілмейтін валюта коды жіберілді.
Not found service to_currency	to_currency үшін төлем сервисі қолжетімді емес.
Minimum amount 0.5 USDT	Сома валюта үшін ең төменгі мөлшерден аз.
Maximum amount 10000000 USDT	Сома валюта үшін ең жоғарғы мөлшерден асады.
Wallet not found	Төлем валютасы үшін белсенді мерчант әмияны жоқ.
You are forbidden	Төлемдер бұғатталған. Қолдау қызметіне хабарласыңыз.
Gateway error / Server error	Уақытша техникалық ақау орын алды және төлем қолжетімсіз.

Себебі Қолдау көрсетілмейтін желі коды жіберілді.
Себебі Қолдау көрсетілмейтін валюта коды жіберілді.
Себебі to_currency үшін төлем сервисі қолжетімді емес.
Себебі Сома валюта үшін ең төменгі мөлшерден аз.
Себебі Сома валюта үшін ең жоғарғы мөлшерден асады.
Себебі Төлем валютасы үшін белсенді мерчант әмияны жоқ.
Себебі Төлемдер бұғатталған. Қолдау қызметіне хабарласыңыз.
Себебі Уақытша техникалық ақау орын алды және төлем қолжетімсіз.

Ішкі қате — HTTP 500:

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

Көшіру

Gateway error, Server error және HTTP 500 қателерін уақытша деп есептеп, экспоненциалды кідіріспен қайта сұрау жіберіңіз.

9. Интеграцияны тексеру тізімі

Мерчант мақұлданған, Merchant ID және төлем API кілті алынған.
Сұрауларды қолтаңбалау және қиғаш сызықтарды экрандау жүзеге асырылған.
Инвойс POST /v1/payment арқылы бірегей order_id және көрсетілген url_callback мәнімен жасалады.
Webhook endpoint HTTPS арқылы қолжетімді және POST сұрауларын қабылдайды.
Webhook сұраулары IP мекенжайы және қолтаңба арқылы тексеріледі.
Webhook өңдеу идемпотентті.
Тауар немесе қызмет сома тексерілгеннен кейін тек paid және paid_over мәртебелерінде беріледі.
POST /v1/payment/info арқылы резервтік сұрау механизмі іске асырылған.
uuid, order_id, txid және мәртебелер журналға жазылады.
API кілттері кодта немесе репозиторийде емес, құпия сақтау орнында сақталады.

Валюта және желі кодтары, қайтару әдістері, статикалық әмияндар мен қаражат шығару туралы Heleket құжаттамасының тиісті бөлімдерінен қараңыз.

Мерчанттарға арналған Heleket Host-to-Host (H2H) интеграциясы

1. Бастамас бұрын не қажет

Төлемдерді қабылдау үшін жеке кабинеттен екі мән қажет:

Мәні	Қайдан алуға болады
Merchant ID	Мерчант UUID идентификаторы. Бизнес → Мерчанттар → Мерчант баптаулары бөлімі.
Төлем API кілті	Мерчант модерациядан өткеннен кейін оның баптауларында жасалады.

Қайдан алуға болады Мерчант UUID идентификаторы. Бизнес → Мерчанттар → Мерчант баптаулары бөлімі.
Қайдан алуға болады Мерчант модерациядан өткеннен кейін оның баптауларында жасалады.

Төлем API кілтін қалай алуға болады

Бизнес → Мерчанттар → Мерчант жасау бөліміне өтіп, атауын енгізіңіз.
Өтінім жіберіп, сайттың URL мекенжайын көрсетіңіз және доменді растаңыз.
Мерчант модерациядан өткенше күтіңіз.
Мақұлданғаннан кейін Баптаулар бөлімінен төлем API кілті мен Merchant ID көшіріңіз.

Барлық сұраулардың базалық endpoint-і:

https://api.heleket.com/

Көшіру

Барлық API сұраулары JSON форматында POST әдісімен жіберіледі және қолтаңбалануы керек.

2. Сұрауды аутентификациялау және қолтаңбалау

Әр сұрау екі HTTP тақырыбымен аутентификацияланады:

Тақырып	Мәні
merchant	Сіздің Merchant ID (UUID) идентификаторыңыз.
sign	Сұрау денесінің қолтаңбасы.
Content-Type	`application/json`

Мәні Сіздің Merchant ID (UUID) идентификаторыңыз.
Мәні Сұрау денесінің қолтаңбасы.
Мәні application/json

Қолтаңба — API кілтіңізбен біріктірілген base64 форматында кодталған JSON сұрау денесінің MD5 хеші.

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

Көшіру

Дене параметрлері жоқ сұраулар үшін қолтаңбаны бос жолдан есептеңіз:

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

Көшіру

Қолтаңбаланған сұрау мысалы

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"}'

Көшіру

3. H2H ағыны

Клиент сізде тапсырыс рәсімдейді → сіз order_id мәнін өз тарапыңызда тіркейсіз
Сіздің серверіңіз → POST /v1/payment → Heleket uuid, мекенжай, сома, url қайтарады
Сіз клиентке төлем деректерін / мекенжайды / QR-кодты (немесе url сілтемесін) көрсетесіз
Клиент блокчейнде төлейді
Heleket → мәртебе әр өзгерген сайын сіздің url_callback мекенжайыңызға POST (webhook) жібереді
Сіз вебхук қолтаңбасын тексересіз → тапсырысты жаңартасыз
(Қосалқы сақтандыру) order_id бойынша POST /v1/payment/info сұрауын мерзімді түрде жібересіз

Тек вебхукқа сүйенбеңіз: callback жетпей қалған жағдайда әрдайым /v1/payment/info арқылы fallback қолданыңыз (6-бөлім).

4. Төлем жасау

Endpoint:

POST

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

Көшіру

Сұраудың негізгі параметрлері

Параметр	Түрі	Міндетті	Сипаттама
amount	string	иә	Төленетін сома. Бөлшек бөлігі нүкте арқылы жазылады, мыс. 10.28.
currency	string	иә	Инвойс валютасының коды (фиат немесе криптовалюта), мыс. USD, USDT, BTC.
order_id	string	иә	Тапсырысыңыздың идентификаторы. Тек әріптер, сандар, _ және -. Бірегей болуы керек.
network	string	жоқ	Блокчейн желісінің коды, мыс. tron, bsc, eth.
to_currency	string	жоқ	Соманы қайта есептеуге арналған мақсатты криптовалюта (әрқашан криптовалюта коды, фиат емес).
url_callback	string	жоқ	Heleket мәртебе вебхуктарын жіберетін URL. Іс жүзінде H2H үшін міндетті.
url_return	string	жоқ	Төлемге дейін клиентті төлем формасынан қайтару мекенжайы.
url_success	string	жоқ	Сәтті төлемнен кейін клиентті қайтару мекенжайы.
lifetime	integer	жоқ	Инвойстың жарамдылық мерзімі секундпен (300–43200, әдепкі бойынша 3600).
subtract	integer	жоқ	Комиссияның қандай пайызын клиентке жүктеу керек (0–100).
accuracy_payment_percent	numeric	жоқ	Рұқсат етілген кем төлем пайызы (0–5): кем төлем осы шекте болса, инвойс төленген деп жабылады.
is_payment_multiple	boolean	жоқ	Қалдықты қосымша төлеуге рұқсат беру. Әдепкі бойынша true.
additional_data	string	жоқ	Сізге арналған еркін жол (клиентке көрінбейді), 255 таңбаға дейін.
currencies	array	жоқ	Төлемге арналған валюталар/желілердің ақ тізімі.
except_currencies	array	жоқ	Валюталар/желілердің қара тізімі.
discount_percent	integer	жоқ	Жеңілдік (оң) немесе үстеме (теріс), -99-дан 100-ге дейін.
is_refresh	boolean	жоқ	Мерзімі өткен инвойсты сол order_id бойынша жаңарту (жаңа мекенжай және мерзім).

Түрі string Міндетті иә Сипаттама Төленетін сома. Бөлшек бөлігі нүкте арқылы жазылады, мыс. 10.28.
Түрі string Міндетті иә Сипаттама Инвойс валютасының коды (фиат немесе криптовалюта), мыс. USD, USDT, BTC.
Түрі string Міндетті иә Сипаттама Тапсырысыңыздың идентификаторы. Тек әріптер, сандар, _ және -. Бірегей болуы керек.
Түрі string Міндетті жоқ Сипаттама Блокчейн желісінің коды, мыс. tron, bsc, eth.
Түрі string Міндетті жоқ Сипаттама Соманы қайта есептеуге арналған мақсатты криптовалюта (әрқашан криптовалюта коды, фиат емес).
Түрі string Міндетті жоқ Сипаттама Heleket мәртебе вебхуктарын жіберетін URL. Іс жүзінде H2H үшін міндетті.
Түрі string Міндетті жоқ Сипаттама Төлемге дейін клиентті төлем формасынан қайтару мекенжайы.
Түрі string Міндетті жоқ Сипаттама Сәтті төлемнен кейін клиентті қайтару мекенжайы.
Түрі integer Міндетті жоқ Сипаттама Инвойстың жарамдылық мерзімі секундпен (300–43200, әдепкі бойынша 3600).
Түрі integer Міндетті жоқ Сипаттама Комиссияның қандай пайызын клиентке жүктеу керек (0–100).
Түрі numeric Міндетті жоқ Сипаттама Рұқсат етілген кем төлем пайызы (0–5): кем төлем осы шекте болса, инвойс төленген деп жабылады.
Түрі boolean Міндетті жоқ Сипаттама Қалдықты қосымша төлеуге рұқсат беру. Әдепкі бойынша true.
Түрі string Міндетті жоқ Сипаттама Сізге арналған еркін жол (клиентке көрінбейді), 255 таңбаға дейін.
Түрі array Міндетті жоқ Сипаттама Төлемге арналған валюталар/желілердің ақ тізімі.
Түрі array Міндетті жоқ Сипаттама Валюталар/желілердің қара тізімі.
Түрі integer Міндетті жоқ Сипаттама Жеңілдік (оң) немесе үстеме (теріс), -99-дан 100-ге дейін.
Түрі boolean Міндетті жоқ Сипаттама Мерзімі өткен инвойсты сол order_id бойынша жаңарту (жаңа мекенжай және мерзім).

Сұрау денесінің мысалдары

15 USD сомасына ең аз инвойс (клиент криптовалюта мен желіні өзі таңдайды):

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

Көшіру

TRON желісіндегі 20 USDT инвойсы — мекенжай бірден беріледі:

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

Көшіру

25 USD инвойсы, кез келген желіде тек USDT арқылы төлеу:

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

Көшіру

Жауап мысалы

{
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}

Көшіру

Жауаптың негізгі өрістері

Өріс	Мақсаты
uuid	Heleket жүйесіндегі инвойс UUID идентификаторы. Оны тапсырыспен бірге сақтаңыз.
address	Төлемге арналған әмиян мекенжайы. Валюта таңдалғанға дейін null болуы мүмкін.
payer_amount	Жеңілдік немесе үстеме ақыны ескере отырып, payer_currency валютасында төленетін сома.
payer_currency	Төлем валютасы. null клиенттің валютаны әлі таңдамағанын білдіреді.
merchant_amount	Комиссиялар шегерілгеннен кейін балансыңызға түсетін сома.
payment_status	Ағымдағы мәртебе (7-бөлімді қараңыз).
url	Төлем формасын өзіңіз көрсетпесеңіз, Heleket төлем бетіне сілтеме.
address_qr_code	Төлем мекенжайының base64 форматындағы QR-коды.
expired_at	Инвойстың мерзімі аяқталатын Unix уақыт белгісі.
is_final	Инвойстың жабылғанын және енді оны төлеу мүмкін еместігін білдіреді.

Мақсаты Heleket жүйесіндегі инвойс UUID идентификаторы. Оны тапсырыспен бірге сақтаңыз.
Мақсаты Төлемге арналған әмиян мекенжайы. Валюта таңдалғанға дейін null болуы мүмкін.
Мақсаты Жеңілдік немесе үстеме ақыны ескере отырып, payer_currency валютасында төленетін сома.
Мақсаты Төлем валютасы. null клиенттің валютаны әлі таңдамағанын білдіреді.
Мақсаты Комиссиялар шегерілгеннен кейін балансыңызға түсетін сома.
Мақсаты Ағымдағы мәртебе (7-бөлімді қараңыз).
Мақсаты Төлем формасын өзіңіз көрсетпесеңіз, Heleket төлем бетіне сілтеме.
Мақсаты Төлем мекенжайының base64 форматындағы QR-коды.
Мақсаты Инвойстың мерзімі аяқталатын Unix уақыт белгісі.
Мақсаты Инвойстың жабылғанын және енді оны төлеу мүмкін еместігін білдіреді.

state: 0 сәттілікті білдіреді. Валидация қателерінде state: 1 (8-бөлім).

5. Webhook арқылы төлем мәртебесі туралы хабарландырулар

Инвойс мәртебесі өзгерген сайын Heleket POST webhook жібереді.

Webhook негізгі өрістері

Өріс	Сипаттама
type	Түрі: payment немесе wallet.
uuid	Төлем UUID-і.
order_id	Сіздің тапсырыс идентификаторыңыз — тапсырысты сол арқылы табасыз.
amount	Инвойс сомасы.
payment_amount	Клиенттің нақты төлеген сомасы.
payment_amount_usd	USD-мен нақты төленген сома.
merchant_amount	Комиссия шегерілгеннен кейін балансқа есептелген сома.
commission	Heleket комиссиясы.
is_final	Инвойстың түпкілікті жабылған-жабылмағаны.
status	Төлем мәртебесі (7-бөлімді қараңыз).
from	Төлеуші әмиянының мекенжайы.
network	Төлем желісі.
currency	Инвойс валютасы.
payer_currency	Нақты төленген валюта.
txid	Блокчейндегі транзакция хэші (p2p/қолмен жабу кезінде болмауы мүмкін).
sign	Тексеруге арналған вебхук қолтаңбасы.

Сипаттама Түрі: payment немесе wallet.
Сипаттама Төлем UUID-і.
Сипаттама Сіздің тапсырыс идентификаторыңыз — тапсырысты сол арқылы табасыз.
Сипаттама Инвойс сомасы.
Сипаттама Клиенттің нақты төлеген сомасы.
Сипаттама USD-мен нақты төленген сома.
Сипаттама Комиссия шегерілгеннен кейін балансқа есептелген сома.
Сипаттама Heleket комиссиясы.
Сипаттама Инвойстың түпкілікті жабылған-жабылмағаны.
Сипаттама Төлем мәртебесі (7-бөлімді қараңыз).
Сипаттама Төлеуші әмиянының мекенжайы.
Сипаттама Төлем желісі.
Сипаттама Инвойс валютасы.
Сипаттама Нақты төленген валюта.
Сипаттама Блокчейндегі транзакция хэші (p2p/қолмен жабу кезінде болмауы мүмкін).
Сипаттама Тексеруге арналған вебхук қолтаңбасы.

Webhook пайдалы жүктемесінің мысалы

{
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}

Көшіру

Webhook міндетті тексеру

Callback сұрауларына тек Heleket IP мекенжайынан рұқсат беріңіз: 31.133.220.8.
Қолтаңбаны тексеру. Қолтаңба сұраулардағы алгоритммен есептеледі, бірақ былай тексеріледі:

// 1. Сұраудың өңделмеген денесін оқимыз
1$data = json_decode(file_get_contents('php://input'), true);
2
3// 2. Қолтаңбаны массивтен алып, жоямыз
4$sign = $data['sign'];
5unset($data['sign']);
6
7// 3. Денеден (sign-сыз) хэшті + төлем API кілтіңізді есептейміз
8$hash = md5(base64_encode(json_encode($data, JSON_UNESCAPED_UNICODE)) . $apiPaymentKey);
9
10// 4. Салыстырамыз
11if (!hash_equals($hash, $sign)) {
12    // қолтаңба қате — қабылдамау
13    http_response_code(400);
14    exit;
15}

Көшіру

Webhook өңдеу бойынша ұсыныстар

Идемпотенттілік. Бір мәртебе қайталап келуі мүмкін (соның ішінде қолмен қайта жіберілгенде). order_id + status мәндеріне байланыстырыңыз және тауарды екі рет бермеңіз.
Аралық емес, финалдық мәртебелерге (paid, paid_over) әрекет етіңіз.
HTTP 200 жауабын webhook сәтті өңделгеннен кейін ғана қайтарыңыз.
payment_amount және merchant_amount мәндерін күтілетін тапсырыс сомасымен салыстырыңыз.

6. Webhook үшін резервтік механизм ретінде мәртебені сұрау

Endpoint:

POST

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

Көшіру

uuid немесе order_id жіберіңіз (екеуі де жіберілсе, order_id басымдыққа ие).

curl https://api.heleket.com/v1/payment/info \
  -X POST \
  -H 'merchant: 8b03432e-385b-4670-8d06-064591096795' \
  -H 'sign: <дене қолтаңбасы>' \
  -H 'Content-Type: application/json' \
  -d '{"order_id":"1"}'

Көшіру

7. Төлем мәртебелері

Мәртебе	Соңғы	Мағынасы
check	жоқ	Блокчейнде транзакцияның пайда болуын күту.
process	жоқ	Төлем өңделуде.
confirm_check	жоқ	Транзакция көрінеді, желінің қажетті растаулар санын күтеміз.
wrong_amount_waiting	жоқ	Қалдықты қосымша төлеу мүмкіндігі бар кем төлем.
paid	иә	Қажетті сома дәл төленді. Тауарды беріңіз.
paid_over	иә	Қажетті сомадан артық төленді. Тауарды беріңіз.
wrong_amount	иә	Клиент қажетті сомадан аз төледі.
fail	иә	Төлем қатесі.
cancel	иә	Төлемнен бас тартылды, клиент төлем жасамады.
system_fail	иә	Жүйелік қате.
locked	иә	Қаражат AML бағдарламасы бойынша бұғатталды.
refund_process	жоқ	Қайтару өңделуде.
refund_paid	иә	Қайтару орындалды.
refund_fail	иә	Қайтару қатесі.

Соңғы жоқ Мағынасы Блокчейнде транзакцияның пайда болуын күту.
Соңғы жоқ Мағынасы Төлем өңделуде.
Соңғы жоқ Мағынасы Транзакция көрінеді, желінің қажетті растаулар санын күтеміз.
Соңғы жоқ Мағынасы Қалдықты қосымша төлеу мүмкіндігі бар кем төлем.
Соңғы иә Мағынасы Қажетті сома дәл төленді. Тауарды беріңіз.
Соңғы иә Мағынасы Қажетті сомадан артық төленді. Тауарды беріңіз.
Соңғы иә Мағынасы Клиент қажетті сомадан аз төледі.
Соңғы иә Мағынасы Төлем қатесі.
Соңғы иә Мағынасы Төлемнен бас тартылды, клиент төлем жасамады.
Соңғы иә Мағынасы Жүйелік қате.
Соңғы иә Мағынасы Қаражат AML бағдарламасы бойынша бұғатталды.
Соңғы жоқ Мағынасы Қайтару өңделуде.
Соңғы иә Мағынасы Қайтару орындалды.
Соңғы иә Мағынасы Қайтару қатесі.

8. Қателерді өңдеу

Валидация қателері — HTTP 422, state: 1:

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

Көшіру

Жиі кездесетін хабарламалар (state: 1, message өрісі):

Хабарлама	Себебі
The network was not found	Қолдау көрсетілмейтін желі коды жіберілді.
The currency was not found	Қолдау көрсетілмейтін валюта коды жіберілді.
Not found service to_currency	to_currency үшін төлем сервисі қолжетімді емес.
Minimum amount 0.5 USDT	Сома валюта үшін ең төменгі мөлшерден аз.
Maximum amount 10000000 USDT	Сома валюта үшін ең жоғарғы мөлшерден асады.
Wallet not found	Төлем валютасы үшін белсенді мерчант әмияны жоқ.
You are forbidden	Төлемдер бұғатталған. Қолдау қызметіне хабарласыңыз.
Gateway error / Server error	Уақытша техникалық ақау орын алды және төлем қолжетімсіз.

Себебі Қолдау көрсетілмейтін желі коды жіберілді.
Себебі Қолдау көрсетілмейтін валюта коды жіберілді.
Себебі to_currency үшін төлем сервисі қолжетімді емес.
Себебі Сома валюта үшін ең төменгі мөлшерден аз.
Себебі Сома валюта үшін ең жоғарғы мөлшерден асады.
Себебі Төлем валютасы үшін белсенді мерчант әмияны жоқ.
Себебі Төлемдер бұғатталған. Қолдау қызметіне хабарласыңыз.
Себебі Уақытша техникалық ақау орын алды және төлем қолжетімсіз.

Ішкі қате — HTTP 500:

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

Көшіру

Gateway error, Server error және HTTP 500 қателерін уақытша деп есептеп, экспоненциалды кідіріспен қайта сұрау жіберіңіз.

9. Интеграцияны тексеру тізімі

Мерчант мақұлданған, Merchant ID және төлем API кілті алынған.
Сұрауларды қолтаңбалау және қиғаш сызықтарды экрандау жүзеге асырылған.
Инвойс POST /v1/payment арқылы бірегей order_id және көрсетілген url_callback мәнімен жасалады.
Webhook endpoint HTTPS арқылы қолжетімді және POST сұрауларын қабылдайды.
Webhook сұраулары IP мекенжайы және қолтаңба арқылы тексеріледі.
Webhook өңдеу идемпотентті.
Тауар немесе қызмет сома тексерілгеннен кейін тек paid және paid_over мәртебелерінде беріледі.
POST /v1/payment/info арқылы резервтік сұрау механизмі іске асырылған.
uuid, order_id, txid және мәртебелер журналға жазылады.
API кілттері кодта немесе репозиторийде емес, құпия сақтау орнында сақталады.