Создание платежа

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

Запрос

Параметры запроса

ИмяТип параметраЗначение по умолчаниюОписание
amount*stringСумма, подлежащая выплате.Если в сумме есть пенни, то отправьте их с разделителем '.'
Пример: 10.28
currency*stringКод валюты
order_id*stringmin: 1max: 128alpha_dashИдентификатор заказа в Вашей системеПараметр должен представлять собой строку, состоящую из буквенных символов, цифр, подчеркиваний и тире. Он не должен содержать никаких пробелов или специальных символов. order_id должен быть уникальным в счетах продавца/статических кошельках/повторных платежахКогда мы находим существующий счет-фактуру с order_id, мы возвращаем его реквизиты, новый счет-фактура создан не будет.
networkstringnullСетевой код блокчейна
url_returnstringmin: 6max: 255urlnullПеред оплатой пользователь может нажать на кнопку в форме оплаты и вернуться на страницу магазина по этому URL.
url_successstringmin: 6max: 255urlnullПосле успешной оплаты пользователь может нажать на кнопку в форме оплаты и вернуться по этому URL.
url_callbackstringmin: 6max: 255urlnullURL, на который будут отправляться webhooks с состоянием платежа
is_payment_multiplebooleantrueРазрешено ли пользователю оплатить оставшуюся сумму. Это полезно, когда пользователь оплатил не всю сумму счета за одну транзакцию, и вы хотите разрешить ему оплатить полную сумму. Если вы отключите эту функцию, выставление счета завершится после получения первого платежа, и вы получите средства на свой баланс.
lifetimeintegermin: 300max: 432003600Срок действия выставленного счета-фактуры (в секундах)
to_currencystringПараметр используется для указания целевой валюты для пересчета суммы счета. При создании счета-фактуры вы указываете сумму и валюту, и API преобразует эту сумму в эквивалентное значение в to_currency.Например, чтобы создать счет на 20 USD в BTC:
amount: 20
currency: USD
to_currency: BTC
API конвертирует сумму в размере 20 USD в ее эквивалент в BTC на основе текущего обменного курса, и пользователь будет платить в BTC.to_currency всегда должен быть кодом криптовалюты, а не кодом фиатной валюты.
subtractintegermin: 0max: 1000Процент от комиссии за платеж, взимаемой с клиентаЕсли у вас ставка 1%, то если вы создадите счет на 100 USD с вычитанием = 100 (клиент платит 100% комиссии), клиенту придется заплатить 101 доллар США.
accuracy_payment_percentnumericmin: 0max: 50Допустимая неточность в оплате.Например, если вы передадите значение 5, счет будет помечен как оплаченный, даже если клиент оплатил только 95% суммы.Фактическая сумма платежа будет зачислена на баланс
additional_datastringmax: 255nullДополнительная информация для Вас (не показывается клиенту)
currenciesarrayИспользуется массив доступных валют из настроек вашего продавца (если параметр не задан, по умолчанию используются все поддерживаемые криптовалюты).Доступные валюты указаны в разделе настроек продавца.Список разрешенных валют для оплаты. Это полезно, если вы хотите ограничить список монет, которые ваши клиенты могут использовать для оплаты счетов. Структура
except_currenciesarraynullСписок исключенных валют для оплаты Структура
course_sourcestringmin: 4max: 20Доступные значенияBinanceBinanceP2PExmoKucoinЕсли не задано, используются обменные курсы Heleket.Сервис, из которого берутся обменные курсы для пересчета в счете-фактуре.
from_referral_codestringnullПродавец, который делает запрос, подключается к рефереру с помощью кода.Например, вы являетесь приложением, которое генерирует счета-фактуры через Heleket API, а вашими клиентами являются другие магазины.
Они вводят свой api-ключ и идентификатор продавца в ваше приложение, а вы отправляете запросы с их учетными данными и передаете свой реферальный код.
Таким образом, ваши клиенты становятся рефералами на вашем аккаунте Heleket, и вы будете получать доход от их оборота.
discount_percentintegermin: -99max: 100nullПоложительные числа:
Позволяет вам установить скидку.
Чтобы установить скидку в размере 5% при оплате, вы должны указать значение: 5
Отрицательные числа:
Позволяет вам установить пользовательскую дополнительную комиссию.
Чтобы установить дополнительную комиссию в размере 10% за платеж, вы должны указать значение: -10Процент скидки при создании счета-фактуры учитывается только в том случае, если в счете указана определенная криптовалюта.
is_refreshbooleanfalseИспользуя этот параметр, вы можете обновить срок действия и получить новый адрес для счета-фактуры, если срок действия истек.Чтобы сделать это, вам нужно передать все необходимые параметры, и счет-фактура с переданным order_id будет обновлен.Изменены только address, payment_status и expired_at. Никакие другие поля не изменяются, независимо от переданных параметров.
payer_emailstringnullnullEmail плательщика

Тип параметра

string

Описание

Сумма, подлежащая выплате.Если в сумме есть пенни, то отправьте их с разделителем '.'
Пример: 10.28

Тип параметра

string

Описание

Код валюты

Тип параметра

stringmin: 1max: 128alpha_dash

Описание

Идентификатор заказа в Вашей системеПараметр должен представлять собой строку, состоящую из буквенных символов, цифр, подчеркиваний и тире. Он не должен содержать никаких пробелов или специальных символов. order_id должен быть уникальным в счетах продавца/статических кошельках/повторных платежахКогда мы находим существующий счет-фактуру с order_id, мы возвращаем его реквизиты, новый счет-фактура создан не будет.

Тип параметра

string

Описание

Сетевой код блокчейна

Тип параметра

stringmin: 6max: 255url

Описание

Перед оплатой пользователь может нажать на кнопку в форме оплаты и вернуться на страницу магазина по этому URL.

Тип параметра

stringmin: 6max: 255url

Описание

После успешной оплаты пользователь может нажать на кнопку в форме оплаты и вернуться по этому URL.

Тип параметра

stringmin: 6max: 255url

Описание

URL, на который будут отправляться webhooks с состоянием платежа

Тип параметра

boolean

Описание

Разрешено ли пользователю оплатить оставшуюся сумму. Это полезно, когда пользователь оплатил не всю сумму счета за одну транзакцию, и вы хотите разрешить ему оплатить полную сумму. Если вы отключите эту функцию, выставление счета завершится после получения первого платежа, и вы получите средства на свой баланс.

Тип параметра

integermin: 300max: 43200

Описание

Срок действия выставленного счета-фактуры (в секундах)

Тип параметра

string

Описание

Параметр используется для указания целевой валюты для пересчета суммы счета. При создании счета-фактуры вы указываете сумму и валюту, и API преобразует эту сумму в эквивалентное значение в to_currency.Например, чтобы создать счет на 20 USD в BTC:
amount: 20
currency: USD
to_currency: BTC
API конвертирует сумму в размере 20 USD в ее эквивалент в BTC на основе текущего обменного курса, и пользователь будет платить в BTC.to_currency всегда должен быть кодом криптовалюты, а не кодом фиатной валюты.

Тип параметра

integermin: 0max: 100

Описание

Процент от комиссии за платеж, взимаемой с клиентаЕсли у вас ставка 1%, то если вы создадите счет на 100 USD с вычитанием = 100 (клиент платит 100% комиссии), клиенту придется заплатить 101 доллар США.

Тип параметра

numericmin: 0max: 5

Описание

Допустимая неточность в оплате.Например, если вы передадите значение 5, счет будет помечен как оплаченный, даже если клиент оплатил только 95% суммы.Фактическая сумма платежа будет зачислена на баланс

Тип параметра

stringmax: 255

Описание

Дополнительная информация для Вас (не показывается клиенту)

Тип параметра

array

Описание

Список разрешенных валют для оплаты. Это полезно, если вы хотите ограничить список монет, которые ваши клиенты могут использовать для оплаты счетов. Структура

Тип параметра

array

Описание

Список исключенных валют для оплаты Структура

Тип параметра

stringmin: 4max: 20
Доступные значения
- Binance- BinanceP2P- Exmo- Kucoin

Описание

Сервис, из которого берутся обменные курсы для пересчета в счете-фактуре.

Тип параметра

string

Описание

Продавец, который делает запрос, подключается к рефереру с помощью кода.Например, вы являетесь приложением, которое генерирует счета-фактуры через Heleket API, а вашими клиентами являются другие магазины.
Они вводят свой api-ключ и идентификатор продавца в ваше приложение, а вы отправляете запросы с их учетными данными и передаете свой реферальный код.
Таким образом, ваши клиенты становятся рефералами на вашем аккаунте Heleket, и вы будете получать доход от их оборота.

Тип параметра

integermin: -99max: 100

Описание

Положительные числа:
Позволяет вам установить скидку.
Чтобы установить скидку в размере 5% при оплате, вы должны указать значение: 5
Отрицательные числа:
Позволяет вам установить пользовательскую дополнительную комиссию.
Чтобы установить дополнительную комиссию в размере 10% за платеж, вы должны указать значение: -10Процент скидки при создании счета-фактуры учитывается только в том случае, если в счете указана определенная криптовалюта.

Тип параметра

boolean

Описание

Используя этот параметр, вы можете обновить срок действия и получить новый адрес для счета-фактуры, если срок действия истек.Чтобы сделать это, вам нужно передать все необходимые параметры, и счет-фактура с переданным order_id будет обновлен.Изменены только address, payment_status и expired_at. Никакие другие поля не изменяются, независимо от переданных параметров.

Тип параметра

stringnull

Описание

Email плательщика

* - обязательный параметр

Структура Валюты

ИмяОписание
currency*Код валюты
networkСетевой код блокчейна

Описание

Код валюты

Описание

Сетевой код блокчейна

* - обязательный параметр

Структура except_currencies

ИмяОписание
currency*Код валюты
networkСетевой код блокчейна

Описание

Код валюты

Описание

Сетевой код блокчейна

* - обязательный параметр

Счет-фактура будет содержать конкретную криптовалюту и адрес на момент создания только в том случае, если валюта или параметр to_currency является криптовалютой и передан параметр сети (или криптовалюта имеет только одну сеть, например BTC).

Пример запроса

Ниже приведен простой пример с минимально необходимым количеством параметров. В этом случае будет создан счет-фактура в фиатной валюте 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",
}'
Copy

Ответ

Параметры отклика

ИмяОписание
uuiduuid счета-фактуры
order_idИдентификатор заказа в Вашей системе
amountСумма счета-фактуры
payment_amountСумма, уплаченная клиентом
payer_amountСумма в payer_currency, которую клиент должен оплатить, включая скидку или дополнительную комиссию.
discount_percentПроцент скидки или дополнительной комиссии, который был передан в параметрах запроса
discountФактическая сумма скидки или дополнительной комиссии в криптовалюте.Например, если сумма счета составляет 15 USD, а discount_percent равен -5, значение скидки будет равно -0,75т.е. amount + discount = payer_amount
payer_currencyВалюта, в которой клиент должен произвести платеж. Если значение равно null, клиент может выбрать конкретную валюту на странице оплаты.
currencyКод валюты счета-фактуры
merchant_amountСумма в криптовалюте, которая будет зачислена на ваш баланс. Если не указан параметр invoice payer_currency, значение будет равно null.
networkСетевой код блокчейна
addressАдрес кошелька для оплаты
fromАдрес кошелька, с которого был произведен платеж
txidХэш транзакции в блокчейне.Поле txid не будет существовать, если1) Платеж был произведен посредством p2p (Плательщик снял средства со своего счета Heleket на адрес, указанный в счете-фактуре, и платеж был произведен без блокчейна, только в нашей системе)2) Платеж не был произведен3) Что-то было не так с платежом или клиент допустил ошибку, и мы пометили ее как 'paid' вручную
payment_statusСтатус платежа Все статусы платежей
urlURL платежной страницы
expired_atОтметка времени истечения срока действия счета-фактуры
is_finalЗавершена ли счет-фактура.Когда выставление счета завершено, оплатить счет невозможно (он либо оплачен, либо срок его действия истек)
additional_dataДополнительная информация
created_atДата создания счета-фактуры. Часовой пояс - UTC+3
updated_atДата последнего обновления счета-фактуры. Часовой пояс - UTC+3
address_qr_codeQR-код с адресом кошелька для оплаты
payment_amount_usdСумма, фактически уплаченная клиентом в долларах США
commissionСумма комиссии Heleket
address_qr_codeQR с адресом кошелька для пополнения.
convertИнформация о валюте, в которую будет автоматически конвертирован платеж. Конвертация производится из payer_currency в USDTПоле convert не будет существовать, если вы не включили функцию автоматической конвертации для payer_currency (например, автоматическое преобразование BTC в USDT) Структура

Описание

uuid счета-фактуры

Описание

Идентификатор заказа в Вашей системе

Описание

Сумма счета-фактуры

Описание

Сумма, уплаченная клиентом

Описание

methods.The amount in payer_currency that the customer must pay, including a discount or additional commission

Описание

Процент скидки или дополнительной комиссии, который был передан в параметрах запроса

Описание

Фактическая сумма скидки или дополнительной комиссии в криптовалюте.Например, если сумма счета составляет 15 USD, а discount_percent равен -5, значение скидки будет равно -0,75т.е. amount + discount = payer_amount

Описание

Валюта, в которой клиент должен произвести платеж. Если значение равно null, клиент может выбрать конкретную валюту на странице оплаты.

Описание

Код валюты счета-фактуры

Описание

Сумма в криптовалюте, которая будет зачислена на ваш баланс. Если не указан параметр invoice payer_currency, значение будет равно null.

Описание

Сетевой код блокчейна

Описание

Адрес кошелька для оплаты

Описание

Адрес кошелька, с которого был произведен платеж

Описание

Хэш транзакции в блокчейне.Поле txid не будет существовать, если1) Платеж был произведен посредством p2p (Плательщик снял средства со своего счета Heleket на адрес, указанный в счете-фактуре, и платеж был произведен без блокчейна, только в нашей системе)2) Платеж не был произведен3) Что-то было не так с платежом или клиент допустил ошибку, и мы пометили ее как 'paid' вручную

Описание

Статус платежа Все статусы платежей

Описание

URL платежной страницы

Описание

Отметка времени истечения срока действия счета-фактуры

Описание

Завершена ли счет-фактура.Когда выставление счета завершено, оплатить счет невозможно (он либо оплачен, либо срок его действия истек)

Описание

Дополнительная информация

Описание

Дата создания счета-фактуры. Часовой пояс - UTC+3

Описание

Дата последнего обновления счета-фактуры. Часовой пояс - UTC+3

Описание

QR-код с адресом кошелька для оплаты

Описание

Сумма, фактически уплаченная клиентом в долларах США

Описание

Сумма комиссии Heleket

Описание

QR с адресом кошелька для пополнения.

Описание

Информация о валюте, в которую будет автоматически конвертирован платеж. Конвертация производится из payer_currency в USDTПоле convert не будет существовать, если вы не включили функцию автоматической конвертации для payer_currency (например, автоматическое преобразование BTC в USDT) Структура

Структура convert

ИмяОписание
to_currencyКод валюты, в которую будет конвертирован платеж
commissionКомиссия за конвертацию
rateКоэффициент конверсии
amountСумма конвертации в to_currency, которая была добавлена на баланс продавца, с вычетом всех комиссионных.сумма здесь равна merchant_amount * rate

Описание

Код валюты, в которую будет конвертирован платеж

Описание

Комиссия за конвертацию

Описание

Коэффициент конверсии

Описание

Сумма конвертации в 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://pay.heleket.com/pay/1ec87133-b22d-4643-988f-cac29a6ac85d",
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}
Copy

Еще примеры

Запросите данные для создания счета-фактуры на 20 USD в сети tron. Счет-фактура будет иметь адрес на момент создания.


1{
2	"amount": "20",
3	"currency": "USDT",
4	"order_id": "1",
5	"network": "tron"
6}
Copy

Запросите данные, чтобы выставить счет на 25 USD и разрешить клиентам оплачивать только USDT в любой сети.


1{
2	"amount": "25",
3	"currency": "USD",
4	"order_id": "1",
5	"to_currency": "USDT"
6}
Copy

Запросите данные, чтобы выставить счет на 25 USD и разрешить клиентам оплачивать только USDT в сети tron. Счет-фактура будет иметь адрес на момент создания.


1{
2	"amount": "25",
3	"currency": "USD",
4	"order_id": "1",
5	"to_currency": "USDT",
6	"network": "tron"
7}
Copy

Запросите данные, чтобы выставить счет на 20 USD и позволить клиентам оплачивать во всех доступных сетях


1{
2	"amount": "20",
3	"currency": "USDT",
4	"order_id": "1",
5}
Copy

Запросите данные, чтобы выставить счет на 20 USD и разрешить клиентам оплачивать только биткоинами. Счет-фактура будет иметь адрес на момент создания.


1{
2	"amount": "20",
3	"currency": "USD",
4	"order_id": "1",
5	"to_currency": "BTC"
6}
Copy

Запросите данные, чтобы выставить счет на 0,5 BTC и разрешить клиентам оплачивать только биткоинами. Счет-фактура будет иметь адрес на момент создания.


1{
2	"amount": "0.5",
3	"currency": "BTC",
4	"order_id": "1",
5}
Copy

Возможные ошибки

Ошибки проверки

код : 422

примеры ответов:

Если какой-то параметр требуется и не передан:


1{
2	"state": 1,
3	"errors": {
4		"amount": ["validation.required"]
5	}
6}
Copy

Если вы указали сетевой код, который не поддерживается


1{
2    "state": 1,
3    "message": "The network was not found"
4}
Copy

Если мы не поддерживаем код валюты, который вы указали в параметре currency:


1{
2    "state": 1,
3    "message": "The currency was not found"
4}
Copy

Если ваши платежи заблокированы. В этом случае вам необходимо обратиться в службу поддержки.


1{
2    "state": 1,
3    "message": "You are forbidden"
4}
Copy

Если мы не найдем платежный сервис в валюте, которая была передана в параметре to_currency:


1{
2    "state": 1,
3    "message": "Not found service to_currency"
4}
Copy

Если случайно что-то произойдет при преобразовании в to_currency:


1{
2    "state": 1,
3    "message": "Error convert to_currency"
4}
Copy

Если сумма платежа меньше минимальной поддерживаемой суммы для криптовалюты, вы получите это сообщение об ошибке:


1{
2    "state": 1,
3    "message": "Minimum amount 0.5 USDT"
4}
Copy

Если сумма платежа превышает максимальную поддерживаемую сумму для криптовалюты, вы получите это сообщение об ошибке:


1{
2    "state": 1,
3    "message": "Maximum amount 10000000 USDT"
4}
Copy

Если у вас не будет активного торгового кошелька с криптовалютой платежа, вы получите эту ошибку:


1{
2    "state": 1,
3    "message": "Wallet not found"
4}
Copy

Если происходят технические работы и платеж временно недоступен, вы можете получать следующие сообщения об ошибках:


1{
2    "state": 1,
3    "message": "Gateway error"
4}
Copy


1{
2    "state": 1,
3    "message": "The terminal was not found"
4}
Copy


1{
2    "state": 1,
3    "message": "Server error"
4}
Copy

Внутренняя ошибка сервера

код : 500

примеры ответов:


1{
2	"message": "Server error, #1",
3	"code": 500,
4	"error": null
5}
Copy