Главная
/Платежи
/Создание платежа
Копировать страницу
| Имя | Тип параметра | Значение по умолчанию | Описание |
|---|---|---|---|
| amount* | string | Сумма, подлежащая выплате.Если в сумме есть пенни, то отправьте их с разделителем '.' Пример: 10.28 | |
| currency* | string | Код валюты | |
| order_id* | stringmin: 1max: 128alpha_dash | Идентификатор заказа в Вашей системеПараметр должен представлять собой строку, состоящую из буквенных символов, цифр, подчеркиваний и тире. Он не должен содержать никаких пробелов или специальных символов. order_id должен быть уникальным в счетах продавца/статических кошельках/повторных платежахКогда мы находим существующий счет-фактуру с order_id, мы возвращаем его реквизиты, новый счет-фактура создан не будет. | |
| network | string | null | Сетевой код блокчейна |
| url_return | stringmin: 6max: 255url | null | Перед оплатой пользователь может нажать на кнопку в форме оплаты и вернуться на страницу магазина по этому URL. |
| url_success | stringmin: 6max: 255url | null | После успешной оплаты пользователь может нажать на кнопку в форме оплаты и вернуться по этому URL. |
| url_callback | stringmin: 6max: 255url | null | URL, на который будут отправляться webhooks с состоянием платежа |
| is_payment_multiple | boolean | true | Разрешено ли пользователю оплатить оставшуюся сумму. Это полезно, когда пользователь оплатил не всю сумму счета за одну транзакцию, и вы хотите разрешить ему оплатить полную сумму. Если вы отключите эту функцию, выставление счета завершится после получения первого платежа, и вы получите средства на свой баланс. |
| lifetime | integermin: 300max: 43200 | 3600 | Срок действия выставленного инвойса (в секундах) |
| to_currency | string | Параметр используется для указания целевой валюты для пересчета суммы счета. При создании инвойса вы указываете сумму и валюту, и API преобразует эту сумму в эквивалентное значение в to_currency.Например, чтобы создать счет на 20 USD в BTC: amount: 20 currency: USD to_currency: BTCAPI конвертирует сумму в размере 20 USD в ее эквивалент в BTC на основе текущего обменного курса, и пользователь будет платить в BTC.to_currency всегда должен быть кодом криптовалюты, а не кодом фиатной валюты. | |
| subtract | integermin: 0max: 100 | 0 | Процент от комиссии за платеж, взимаемой с клиентаЕсли у вас ставка 1%, то если вы создадите счет на 100 USD с вычитанием = 100 (клиент платит 100% комиссии), клиенту придется заплатить 101 доллар США. |
| accuracy_payment_percent | numericmin: 0max: 5 | 0 | Допустимая неточность в оплате.Например, если вы передадите значение 5, счет будет помечен как оплаченный, даже если клиент оплатил только 95% суммы.Фактическая сумма платежа будет зачислена на баланс |
| additional_data | stringmax: 255 | null | Дополнительная информация для Вас (не показывается клиенту) |
| currencies | array | Используется массив доступных валют из настроек вашего продавца (если параметр не задан, по умолчанию используются все поддерживаемые криптовалюты).Доступные валюты указаны в разделе настроек продавца. | Список разрешенных валют для оплаты. Это полезно, если вы хотите ограничить список монет, которые ваши клиенты могут использовать для оплаты счетов. Структура |
| except_currencies | array | null | Список исключенных валют для оплаты Структура |
| course_source | stringmin: 4max: 20Доступные значения• Binance• BinanceP2P• Exmo• Kucoin | Если не задано, используются обменные курсы Heleket. | Сервис, из которого берутся обменные курсы для пересчета в счете-фактуре. |
| from_referral_code | string | null | Продавец, который делает запрос, подключается к рефереру с помощью кода.Например, вы являетесь приложением, которое генерирует инвойса через Heleket API, а вашими клиентами являются другие магазины. Они вводят свой api-ключ и идентификатор продавца в ваше приложение, а вы отправляете запросы с их учетными данными и передаете свой реферальный код.Таким образом, ваши клиенты становятся рефералами на вашем аккаунте Heleket, и вы будете получать доход от их оборота. |
| discount_percent | integermin: -99max: 100 | null | Положительные числа: Позволяет вам установить скидку. Чтобы установить скидку в размере 5% при оплате, вы должны указать значение: 5Отрицательные числа: Позволяет вам установить пользовательскую дополнительную комиссию.Чтобы установить дополнительную комиссию в размере 10% за платеж, вы должны указать значение: -10Процент скидки при создании инвойса учитывается только в том случае, если в счете указана определенная криптовалюта. |
| is_refresh | boolean | false | Используя этот параметр, вы можете обновить срок действия и получить новый адрес для инвойса, если срок действия истек.Чтобы сделать это, вам нужно передать все необходимые параметры, и счет-фактура с переданным order_id будет обновлен.Изменены только address, payment_status и expired_at. Никакие другие поля не изменяются, независимо от переданных параметров. |
| payer_email | stringnull | null | Email плательщика |
| theme | stringnullДоступные значения• dark• light | null | Тема |
* - обязательный параметр
| Имя | Описание |
|---|---|
| currency* | Код валюты |
| network | Сетевой код блокчейна |
* - обязательный параметр
| Имя | Описание |
|---|---|
| currency* | Код валюты |
| network | Сетевой код блокчейна |
* - обязательный параметр
Ниже приведен простой пример с минимально необходимым количеством параметров. В этом случае будет создан счет-фактура в фиатной валюте USD. На странице оплаты пользователь сможет выбрать криптовалюту и сеть для оплаты этого счета.
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"
}'| Имя | Описание |
|---|---|
| uuid | uuid инвойса |
| order_id | Идентификатор заказа в Вашей системе |
| amount | Сумма инвойса |
| payment_amount | Сумма, уплаченная клиентом |
| payer_amount | Сумма в payer_currency, которую клиент должен оплатить, включая скидку или дополнительную комиссию. |
| payer_amount_exchange_rate | Курс payer_currency на момент создания инвойса |
| discount_percent | Процент скидки или дополнительной комиссии, который был передан в параметрах запроса |
| discount | Фактическая сумма скидки или дополнительной комиссии в криптовалюте.Например, если сумма счета составляет 15 USD, а discount_percent равен -5, значение скидки будет равно -0,75т.е. amount + discount = payer_amount |
| payer_currency | Валюта, в которой клиент должен произвести платеж. Если значение равно null, клиент может выбрать конкретную валюту на странице оплаты. |
| currency | Код валюты инвойса |
| comments | Служебные комментарии к платежу, null, если их нет |
| merchant_amount | Сумма в криптовалюте, которая будет зачислена на ваш баланс. Если не указан параметр invoice payer_currency, значение будет равно null. |
| network | Сетевой код блокчейна |
| address | Адрес кошелька для оплаты |
| from | Адрес кошелька, с которого был произведен платеж |
| txid | Хэш транзакции в блокчейне.Поле txid не будет существовать, если1) Платеж был произведен посредством p2p (Плательщик снял средства со своего счета Heleket на адрес, указанный в счете-фактуре, и платеж был произведен без блокчейна, только в нашей системе)2) Платеж не был произведен3) Что-то было не так с платежом или клиент допустил ошибку, и мы пометили ее как 'paid' вручную |
| payment_status | Статус платежа Все статусы платежей |
| status | Дублирует payment_status, сохранено для обратной совместимости |
| url | URL платежной страницы |
| expired_at | Отметка времени истечения срока действия инвойса |
| is_final | Завершена ли счет-фактура.Когда выставление счета завершено, оплатить счет невозможно (он либо оплачен, либо срок его действия истек) |
| additional_data | Дополнительная информация |
| created_at | Дата создания инвойса. Часовой пояс - UTC+3 |
| updated_at | Дата последнего обновления инвойса. Часовой пояс - UTC+3 |
| address_qr_code | QR-код с адресом кошелька для оплаты |
| payment_amount_usd | Сумма, фактически уплаченная клиентом в долларах США |
| commission | Сумма комиссии Heleket |
| convert | Информация о валюте, в которую будет автоматически конвертирован платеж. Конвертация производится из payer_currency в USDTПоле convert не будет существовать, если вы не включили функцию автоматической конвертации для payer_currency (например, автоматическое преобразование BTC в USDT) Структура |
| Имя | Описание |
|---|---|
| to_currency | Код валюты, в которую будет конвертирован платеж |
| commission | Комиссия за конвертацию |
| rate | Коэффициент конверсии |
| amount | Сумма конвертации в to_currency, которая была добавлена на баланс продавца, с вычетом всех комиссионных.сумма здесь равна merchant_amount * rate |
1{
2 "state": 0,
3 "result": {
4 "uuid": "1ec87133-b22d-4643-988f-cac29a6ac85d",
5 "order_id": "3",
6 "amount": "20000.00",
7 "payment_amount": null,
8 "payment_amount_usd": "0.00",
9 "payer_amount": "254.92",
10 "payer_amount_exchange_rate": "78.45392451",
11 "discount_percent": 0,
12 "discount": "0.00",
13 "payer_currency": "USDT",
14 "currency": "RUB",
15 "comments": null,
16 "merchant_amount": "249.82816502",
17 "network": "bsc",
18 "address": "0x2b...",
19 "from": null,
20 "txid": null,
21 "payment_status": "check",
22 "url": "https://new-pay.heleket.com/pay/1ec87133-b22d-4643-988f-cac29a6ac85d?theme=light",
23 "expired_at": 1753202502,
24 "status": "check",
25 "is_final": false,
26 "additional_data": null,
27 "created_at": "2025-07-22T18:41:42+03:00",
28 "updated_at": "2025-07-22T18:42:31+03:00",
29 "commission": "5.09853397",
30 "address_qr_code": "data:image/png;base64 ..."
31 }
32}Запросите данные для создания инвойса на 20 USDT в сети tron. Счет-фактура будет иметь адрес на момент создания.
1{
2 "amount": "20",
3 "currency": "USDT",
4 "order_id": "1",
5 "network": "tron"
6}Запросите данные, чтобы выставить счет на 25 USD и разрешить клиентам оплачивать только USDT в любой сети.
1{
2 "amount": "25",
3 "currency": "USD",
4 "order_id": "1",
5 "to_currency": "USDT"
6}Запросите данные, чтобы выставить счет на 25 USD и разрешить клиентам оплачивать только USDT в сети tron. Счет-фактура будет иметь адрес на момент создания.
1{
2 "amount": "25",
3 "currency": "USD",
4 "order_id": "1",
5 "to_currency": "USDT",
6 "network": "tron"
7}Запросите данные, чтобы выставить счет на 20 USDT и позволить клиентам оплачивать во всех доступных сетях
1{
2 "amount": "20",
3 "currency": "USDT",
4 "order_id": "1"
5}Запросите данные, чтобы выставить счет на 20 USD и разрешить клиентам оплачивать только биткоинами. Счет-фактура будет иметь адрес на момент создания.
1{
2 "amount": "20",
3 "currency": "USD",
4 "order_id": "1",
5 "to_currency": "BTC"
6}Запросите данные, чтобы выставить счет на 0,5 BTC и разрешить клиентам оплачивать только биткоинами. Счет-фактура будет иметь адрес на момент создания.
1{
2 "amount": "0.5",
3 "currency": "BTC",
4 "order_id": "1"
5}код : 422
примеры ответов:
Если какой-то параметр требуется и не передан:
1{
2 "state": 1,
3 "errors": {
4 "amount": ["validation.required"]
5 }
6}Если вы указали сетевой код, который не поддерживается
1{
2 "state": 1,
3 "message": "The network was not found"
4}Если мы не поддерживаем код валюты, который вы указали в параметре currency:
1{
2 "state": 1,
3 "message": "The currency was not found"
4}Если ваши платежи заблокированы. В этом случае вам необходимо обратиться в службу поддержки.
1{
2 "state": 1,
3 "message": "You are forbidden"
4}Если мы не найдем платежный сервис в валюте, которая была передана в параметре to_currency:
1{
2 "state": 1,
3 "message": "Not found service to_currency"
4}Если случайно что-то произойдет при преобразовании в to_currency:
1{
2 "state": 1,
3 "message": "Error convert to_currency"
4}Если сумма платежа меньше минимальной поддерживаемой суммы для криптовалюты, вы получите это сообщение об ошибке:
1{
2 "state": 1,
3 "message": "Minimum amount 0.5 USDT"
4}Если сумма платежа превышает максимальную поддерживаемую сумму для криптовалюты, вы получите это сообщение об ошибке:
1{
2 "state": 1,
3 "message": "Maximum amount 10000000 USDT"
4}Если у вас не будет активного торгового кошелька с криптовалютой платежа, вы получите эту ошибку:
1{
2 "state": 1,
3 "message": "Wallet not found"
4}Если происходят технические работы и платеж временно недоступен, вы можете получать следующие сообщения об ошибках:
1{
2 "state": 1,
3 "message": "Gateway error"
4}
1{
2 "state": 1,
3 "message": "The terminal was not found"
4}
1{
2 "state": 1,
3 "message": "Server error"
4}код : 500
примеры ответов:
1{
2 "message": "Server error, #1",
3 "code": 500,
4 "error": null
5}