Як підключити Binance Pay до чат-бота або сервісу: покрокова інструкція

Щоб підключити Binance Pay до чат-бота чи іншого сервісу, створіть у Binance Merchant Admin Portal пару ключів API Key і Secret Key та передайте їх розробнику захищеним каналом. Сервіс підписує ними запити на створення платежів.

Що означає «розшарити» Binance Pay?

Так зазвичай кажуть, коли потрібно дати чат-боту, інтернет-магазину чи CRM право створювати рахунки на оплату в криптовалюті від імені вашого акаунта. Технічно це доступ до Binance Pay Merchant API. Сервіс отримує ваші ключі, формує замовлення, покупець платить, а Binance Pay надсилає сервісу повідомлення про оплату.

Розрізняйте два типи ключів. Ключі біржового API (Профіль → Керування API) дають доступ до торгівлі й балансу на біржі, їх використовують торгові боти. Для приймання платежів потрібні ключі Binance Pay із мерчант-кабінету.

Що потрібно до початку?

• Акаунт Binance із пройденою верифікацією.
• Реєстрація мерчанта в Binance Merchant Admin Portal (merchant.binance.com). Вимоги до перевірки мерчанта Binance встановлює сам і може змінювати їх залежно від країни, тож актуальний перелік документів дивіться під час реєстрації.
• Сервіс, який працює з Binance Pay API: готова інтеграція бота чи платформи або власна розробка.
• Адреса на вашому сервері для повідомлень (webhook), доступна через HTTPS.

Як створити API-ключі Binance Pay: покроково

1. Відкрийте Merchant Admin Portal. Увійдіть на merchant.binance.com і перейдіть у розділ для розробників (Developers).
2. Створіть ключ. Натисніть «Generate API Key». Binance може попросити підтвердження через 2FA.
3. Назвіть ключ. Назва має підказувати, для якого сервісу його створено: «telegram-bot-shop», «site-checkout». Так ключ легше знайти й відкликати.
4. Збережіть пару ключів. Скопіюйте API Key і Secret Key у менеджер паролів одразу після створення: секретний ключ повторно може бути недоступний.
5. Передайте ключі сервісу. Внесіть їх у налаштування бота чи платформи або передайте розробнику через захищене сховище.
6. Вкажіть webhook. Пропишіть адресу для повідомлень про оплату в налаштуваннях мерчанта або в запиті на створення замовлення — як вимагає ваша інтеграція.
7. Проведіть тестову оплату. Створіть замовлення на мінімальну суму й перевірте весь ланцюжок: рахунок, оплату, повідомлення, зміну статусу замовлення в боті.

Як сервіс використовує ключі?

Запити йдуть на https://bpay.binanceapi.com лише через HTTPS, у форматі JSON. Кожен запит містить заголовки BinancePay-Timestamp (час у мілісекундах), BinancePay-Nonce (випадковий рядок із 32 символів), BinancePay-Certificate-SN (ваш API Key) і BinancePay-Signature. Підпис обчислюється алгоритмом HMAC-SHA512 із Secret Key від рядка з трьох частин: час, nonce і тіло запиту, після кожної частини стоїть символ нового рядка (\n). Результат у шістнадцятковому вигляді передається великими літерами.

Час на сервері має бути синхронізований: розбіжність із Binance понад допустиму призводить до помилки підпису. Повідомлення webhook теж підписані, і сервіс зобов’язаний перевіряти підпис, перш ніж позначити замовлення оплаченим. Інакше зловмисник зможе надіслати підроблене «оплачено».

Як зберігати ключі безпечно?

• Secret Key тримайте у змінних оточення або сховищі секретів на сервері. У коді сайту, у браузері й у репозиторії GitHub його бути не повинно — це пряма вимога документації Binance Pay.
• Для кожного сервісу — своя пара ключів. Вимкнули бота — видалили його ключ, інші інтеграції працюють далі.
• Під час зміни підрядника або витоку видаліть старий ключ у Merchant Admin Portal і випустіть новий.
• Обмежте доступ до мерчант-кабінету: хто має вхід, той може створити новий ключ.

Типові помилки підключення

• Вставлено ключі біржового API замість ключів Binance Pay.
• У Secret Key потрапив пробіл або перенесення рядка під час копіювання.
• Годинник сервера відстає — запити відхиляються через мітку часу.
• Webhook недоступний ззовні або повертає помилку, тож оплати не підтверджуються в боті.
• Тіло запиту під час підпису й під час надсилання різниться (зайві пробіли, інший порядок полів).

Податкові та правові питання приймання криптоплатежів уточнюйте в юриста й бухгалтера у своїй юрисдикції до запуску.

Кому доручити інтеграцію?

Якщо бот уже підтримує Binance Pay, вистачить ключів і адреси webhook. Якщо потрібна своя логіка — рахунки, підписки, видача доступу після оплати, облік у CRM, — це розробка. Ми робимо чат-боти для криптокомпаній із прийманням платежів і Telegram Mini Apps, де оплата вбудована в інтерфейс. Строки рахуємо після ТЗ: вони залежать від кількості сценаріїв оплати та інтеграцій.

Часті запитання

Де взяти API Key і Secret Key Binance Pay?

У Binance Merchant Admin Portal, у розділі для розробників. Для доступу потрібен зареєстрований мерчант-акаунт Binance Pay; ключі біржового API з профілю для приймання платежів не підходять.

Чи безпечно передавати Secret Key чат-боту?

Так, якщо сервісу ви довіряєте і ключ зберігається на його сервері в захищеному сховищі секретів. Для кожного сервісу випускайте окрему пару ключів, щоб за потреби відкликати лише її.

Чому Binance Pay повертає помилку підпису?

Найчастіше через неправильний Secret Key, відставання годинника сервера або розбіжності в тілі запиту між підписом і надсиланням. Підпис обчислюється за HMAC-SHA512 і передається великими літерами.

Навіщо потрібен webhook під час підключення Binance Pay?

На цю адресу Binance Pay надсилає повідомлення про успішну оплату. За ним бот або сайт змінює статус замовлення, тому адреса має працювати через HTTPS і перевіряти підпис повідомлення.

Як відключити сервіс від Binance Pay?

Видаліть його API-ключ у Merchant Admin Portal. Запити з цим ключем перестануть прийматися, а інші інтеграції з окремими ключами працюватимуть далі.