Головний
/Виплати
/Створення рахунку -фактури
Копіювати сторінку
| Назва | Тип параметра | Значення за замовчуванням | Визначення |
|---|---|---|---|
| amount* | string | Сума, яку потрібно сплатити.Якщо в сумі є копійки, тоді надішліть їх із сепаратором '.' Приклад: 10.28 | |
| currency* | string | Валютний код | |
| order_id* | stringmin: 1max: 128alpha_dash | Ідентифікатор замовлення у вашій системіПараметр повинен бути рядок, що складається з алфавітних символів, цифр, підкреслення та тире. Він не повинен містити жодних пробілів чи спеціальних символів. order_id повинен бути унікальним у торгових рахунках/статичних гаманцях/рецидивахКоли ми знайдемо існуючу рахунок -фактуру з order_id , ми повертаємо його деталі, новий рахунок -фактура не буде створено. | |
| network | string | null | Мережевий код Blockchain |
| 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 в біткойні: amount: 20 currency: USD to_currency : btcAPI перетворить суму 20 USD в його еквівалент у BTC на основі поточного обмінного курсу, і користувач заплатить у BTC to_currency завжди має бути кодом криптовалюти, а не кодом фіатної валюти. | |
| subtract | integermin: 0max: 100 | 0 | Відсоток платіжної комісії, що стягується клієнтуЯкщо у вас є ставка 1%, то якщо ви створите рахунок -фактуру за 100 USDT з відніманням = 100 (клієнт платить 100% комісії), клієнту доведеться заплатити 101 USDT. |
| 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 | Торговець, який робить запит, підключається до реферату за кодом.Наприклад, ви - додаток, який генерує рахунки -фактури через API Heleket, а ваші клієнти - інші магазини. Вони вводять свій ключ 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 | Електронна адреса платника |
| theme | stringnullНаявні значення• dark• light | null | Тема |
* - обов'язковий параметр
| Назва | Визначення |
|---|---|
| currency* | Валютний код |
| network | Мережевий код Blockchain |
* - обов'язковий параметр
| Назва | Визначення |
|---|---|
| currency* | Валютний код |
| network | Мережевий код Blockchain |
* - обов'язковий параметр
Нижче наведено зразок прикладу з мінімальною необхідною кількістю параметрів. У цьому випадку рахунок -фактура буде створена з фіатною валютою доларів США. На сторінці оплати користувач зможе вибрати криптовалюту та мережу для оплати цього рахунку.
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 USDT, а знижка_percent --5, значення знижки --0,75тобто amount + discount = payer_amount |
| payer_currency | Валюта, в якій замовник повинен здійснити платіж. |
| currency | Код валюти рахунку -фактури |
| comments | Службові коментарі до платежу, null, якщо їх немає |
| merchant_amount | Сума в криптовалюті, яка буде зарахована на ваш баланс. Якщо рахунок -фактура сплачується_currency не буде вказана, значення буде нульовим. |
| network | Мережевий код Blockchain |
| address | Адреса гаманця для оплати |
| from | Адреса гаманця, з якого було здійснено платіж |
| txid | Хеш транзакцій у блокчейні.Поле txid не існуватиме, якщо1) Оплата була здійснена через p2p (Платник знімав кошти зі свого рахунку Heleket на адресу, зазначену в рахунку-фактурі, а платіж було здійснено без блокчейну, лише в нашій системі)2) Платіж не було здійснено3) Щось пішло не так з оплатою, або клієнт зробив помилку, і ми вручну позначили її як «оплачену». |
| 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 * ставці |
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 Network. Рахунок -фактура матиме адресу на момент створення.
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}Payments.If we don’t support the currency code you provided in currency parameter
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}