Як почати приймати криптовалютні платежі за допомогою API «New Address» від Bcon

Прийняття криптовалюти на вашому веб-сайті може здаватися складним процесом. Але завдяки платіжному шлюзу, такому як Bcon, цей процес стає чітко організованим і передбачуваним. Перш ніж розпочати, важливо вибрати надійний гаманець для отримання коштів. Якщо ви не впевнені, який варіант найкраще відповідає вашим потребам, можете ознайомитися з нашим посібником щодо вибору найкращого криптогаманця.

У цій статті ви дізнаєтеся:

• Як працює шлюз
• Як визначаються платежі
• Що потрібно підготувати перед підключенням веб-сайту
• Як працює нова функція Address API
• Як правильно використовувати всі параметри
• Відмінність між блокчейн BTC та EVM
• Як працює термін дії інвойсу

Як працює криптовалютний платіжний шлюз Bcon

Перш ніж писати код, потрібно зрозуміти логіку.

Криптовалютний платіжний шлюз виконує 4 основні функції:

1. Створює унікальну платіжну адресу для інвойсу
2. Здійснює моніторинг блокчейну
3. Виявляє вхідні транзакції
4. Надсилає зворотний виклик (повідомлення) на ваш веб-сайт

Коли клієнт оформлює замовлення:

• Ваш веб-сайт формує інвойс через API
• Шлюз генерує криптовалютну адресу
• Клієнт надсилає криптовалюту на цю адресу
• Шлюз розпізнає платіж
• Шлюз надсилає сигнал зворотного виклику на ваш сервер
• Ви позначаєте замовлення як оплачене

Ось і все.

2. Що потрібно підготувати перед підключенням

Щоб підключити свій веб-сайт до Bcon, вам потрібно:

Гаманець для отримання коштів

Це ВАШ гаманець.
Саме сюди ви хочете отримати криптовалюту (Metamask, TrustWallet, Exodus або будь-який інший).

Налаштування залежить від типу блокчейну:

• Для Bitcoin → ви вказуєте xpub
• Для блокчейнів EVM (ethereum, BSC) та інших (SOL, TRX) — вкажіть звичайну адресу гаманця

Нижче ми пояснимо, у чому полягає різниця.

URL-адреса для зворотного виклику

Це URL-адреса на вашому сервері.

Приклад:

https://yourstore.com/callback.php

Коли статус платежу зміниться, Bcon надішле POST-запит на цю URL-адресу.

Без функції зворотного виклику ваш веб-сайт не дізнається про те, що оплата відбулася.

Ключ API

Для кожного блокчейн-магазину, створеного в панелі Bcon, ви отримуєте окремий ключ API.

Важливо:

• Bitcoin → власний ключ API
• ethereum → власний ключ API
• Binance → власний ключ API
• Tron → власний ключ API

Ви повинні вказати це в заголовку:

Авторизація: На ім’я власника YOUR_API_KEY

3. Bitcoin, блокчейн на базі EVM та Tron, solana — важлива відмінність

Це ДУЖЕ важливо для розуміння того, як ідентифікуються платежі.

Bitcoin (BTC)

Bitcoin використовує xpub (розширений відкритий ключ).

Важливо:

• xpub НЕ надає доступу до коштів
• Він може лише генерувати адреси
• Цю інформацію можна безпечно передати шлюзу

Як це працює:

Для кожного інвойсу:

• Bcon генерує НОВУ адресу BTC на основі вашого xpub
• Кожен інвойс має свою унікальну адресу

Приклад:

Інвойс 1 → Адреса А
Інвойс 2 → Адреса Б
Інвойс 3 → Адреса В

Це значно спрощує ідентифікацію.

Якщо на Адресу B надійде 0,005 BTC →
Система розпізнає → що це Інвойс № 2.

Ethereum, BSC (ланцюги EVM) та Tron, solana

Блокчейн EVM, а також Tron і solana НЕ використовують xpub.

Варіант 1 — Один гаманець для кількох інвойсів

Як це працює

Усі клієнти надсилають платежі на одну й ту саму адресу гаманця.

Якщо одночасно створюється кілька інвойсів на одну й ту саму суму, система не може визначити, до якого саме інвойсу відноситься цей платіж.

Приклад:

• Інвойс № 101 → 100 USDT
• Інвойс № 102 → 100 USDT

Обидва клієнти отримують одну й ту саму адресу гаманця.

Якщо надходить платіж у розмірі 100 USDT, система не може визначити, який інвойс слід закрити.

Як вирішується ця проблема

Система автоматично коригує суму додаткових інвойсів, додаючи невеликі десяткові значення.

Приклад:

• Інвойс № 101 → 100,00 USDT
• Інвойс № 102 → 100,01 USDT
• Інвойс № 103 → 100,02 USDT

Тепер система може ідентифікувати потрібний інвойс за точною сумою платежу.

Клієнт повинен перерахувати точну суму, вказану в інвойсі.

Якщо клієнт надішле:

• менше,
• крім того,
• або округлена сума,

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

Варіант 2 — Кілька гаманців (рекомендовано)

Як це працює

Ви налаштовуєте кілька адрес гаманців.

Приклад:

• Гаманець 1
• Гаманець 2
• Гаманець 3
• Гаманець 4
• Гаманець 5

Кожен новий інвойс по черзі прив’язується до наступного вільного гаманця.

Якщо одночасно створюється 5 інвойсів:

Інвойс	Гаманець
№ 101	Гаманець 1
№ 102	Гаманець 2
№ 103	Гаманець 3
№ 104	Гаманець 4
#105	Гаманець 5

Тепер, навіть якщо сума платежу дещо відрізняється від суми інвойсу, система все одно знає, який інвойс належить до якого гаманця.

Після здійснення оплати

Коли:

• інвойс оплачено,
• або закінчиться термін оплати,

система скасовує моніторинг цього гаманця, і адреса стає доступною для повторного використання.

Що станеться, якщо інвойсів буде більше, ніж гаманців?

Приклад:

• 5 гаманців
• 20 інвойсів одночасно

Як тільки всі гаманці будуть заповнені, система почне повторно використовувати адреси.

У цей момент автоматично вмикається унікальний механізм розрахунку десяткових сум із Варіанту 1 для інвойсів, пов’язаних з одним і тим самим гаманцем.

Гаманець	Інвойс	Сума
Гаманець 1	№ 101	100,00
Гаманець 1	№ 106	100,01

Простими словами

• Один гаманець → простіше налаштування, але більша ймовірність конфліктів при ідентифікації платежів.
• Кілька гаманців → більш надійне виявлення платежів і менше випадків, коли потрібно коригувати суми.
• Чим більше гаманців — тим більше інвойсів можна обробляти одночасно без використання унікальних десяткових сум.

Який варіант краще вибрати?

Один гаманець підійде, якщо:

• у вас невелика кількість одночасних платежів;
• суми в інвойсах зазвичай відрізняються;
• вам потрібна якомога простіша конфігурація.

Рекомендується використовувати кілька гаманців, якщо:

• ви обробляєте багато інвойсів одночасно;
• часто трапляються інвойси з однаковими сумами;
• важливе значення має надійне автоматичне виявлення платежів;
• Ви хочете звести до мінімуму кількість неідентифікованих платежів.

4. Використання API «Нова адреса»

Кінцева точка:

POST https://external-api.bcon.global/api/v2/address

Приклад на PHP:

define("BCON_APIKEY", "YOUR_API_KEY");

$curl = curl_init();
curl_setopt_array($curl, array(
 CURLOPT_URL => 'https://external-api.bcon.global/api/v2/address',
 CURLOPT_RETURNTRANSFER => true,
 CURLOPT_CUSTOMREQUEST => 'POST',
 CURLOPT_HTTPHEADER => array(
   'Accept: application/json',
   'Content-Type: application/json',
   'Authorization: Bearer '.BCON_APIKEY
 ),
 CURLOPT_POSTFIELDS => json_encode([
   "payment_currency" => "USDC",
   "origin_amount" => "15",
   "origin_currency" => "USD",
   "external_id" => "A1001",
   "chain" => "ethereum"
 ]),
));

$response = curl_exec($curl);
curl_close($curl);
echo $response;

5. Розуміння всіх параметрів

Давайте все чітко пояснимо.

Необхідні параметри

1. валюта_розрахунку

Тікер токена.

Приклади:

BTC

USDT

USDC

Це визначає, яку суму клієнт має сплатити.

2. сума_на_початку

Сума у фіатній валюті.

Приклад: 15

3. валюта_походження

Код фіатної валюти.

Приклади:

• долар США
• EUR
• UAH

Якщо ціна вашого товару становить 15 доларів:

origin_currency = USD

origin_amount = 15

Система автоматично перераховує суму в токени.

Приклад результату:

0,00032 BTC

Логіка автоматичного перетворення

Якщо ви використовуєте:

• валюта_платежу
• сума_походження
• валюта_походження

Система розраховує суму в криптовалюті виходячи з ринкового курсу.

Необов’язкові параметри

сума_платежу

Це замінює перетворення.

Використовуйте це, коли:

• Вам потрібна точна сума в криптовалюті
• Ви не хочете, щоб відбувалося автоматичне перетворення

Приклад:

“payment_currency” => “BTC”,

“payment_amount” => “0,01”

Тепер значення origin_amount ігнорується. Сума інвойсу становитиме ТОЧНО 0,01 BTC.

external_id

Це дуже важливо. Це номер вашого інвойсу.

Приклад:

“external_id” => “A1001”

Правила:

• Повинен бути унікальним для кожного магазину
• Максимальна довжина — 8 символів
• Повернуто у функції зворотного виклику

Коли надходить виклик зворотної функції:

Замість пошуку за сумою ви здійснюєте пошук за external_id.

блокчейн

Наводить визначення поняття «блокчейн».

Доступно:

• Bitcoin
• ethereum
• Binance
• solana
• трон

Приклад:

“блокчейн” => “Bitcoin”

Повинно відповідати параметру payment_currency.

6. Практичні приклади

Приклад 1 — Автоматичне перетворення (USD → BTC)

Ви продаєте товар за 100 доларів.

"payment_currency" => "BTC",
"origin_amount" => "100",
"origin_currency" => "USD",
"external_id" => "B2001",
"chain" => "bitcoin"

Система обчислює:

0,0021 BTC

Клієнт здійснює оплату в BTC.

Приклад 2 — Фіксована сума в криптовалюті

Ви хочете фіксовану суму в розмірі 50 USDT.

"payment_currency" => "USDT",
"payment_amount" => "50",
"external_id" => "C3001",
"chain" => "tron"

Перетворення не застосовувалося.

Приклад 3 — Дві інвойси EVM на одну й ту саму суму

Дві інвойси:

50 доларів США

50 доларів США

Система може генерувати:

Інвойс 1 → 50,00 USDT
Інвойс 2 → 50,01 USDT

Клієнт повинен вказати точну суму.

7. Як працює функція зворотного виклику

Коли статус платежу змінюється, система Bcon надсилає запит POST на вашу URL-адресу зворотного виклику.

Цей запит містить важливу інформацію про транзакцію. Ваш сервер повинен прочитати ці дані та оновити статус замовлення у вашій базі даних.

Функція зворотного виклику поверне такі поля:

• Статус — статус
  транзакції
  • підтверджено = 2
    
  • частково_підтверджено = 1
    
  • непідтверджено = 0
    
• Addr — адреса одержувача, на яку було надіслано
  платіж
• Сума — сума
  отриманого платежу
• Txid — ідентифікатор транзакції в блокчейні
  

External_id — значення, яке ви вказали під час створення інвойсу (використовується для відстеження)

Приклад JSON-даних для зворотного виклику

{
 "status": 2,
 "addr": "0x1234abcd...",
 "value": "15000000",
 "txid": "0x98fa76bc54...",
 "external_id": "A1001"
}

Що означає цей статус

• 0 (непідтверджено) → Транзакція виявлена, але ще
  не підтверджена
• 1 (частково_підтверджено) → Транзакція має кілька підтверджень
  
• 2 (підтверджено) → Транзакція повністю підтверджена, і платіж є остаточним
  

У більшості випадків слід позначати замовлення як оплачене лише тоді, коли статус = 2.

Важливі технічні зауваження

1️⃣ Правило успішного зворотного виклику

Зворотний виклик вважається успішним лише тоді, коли ваш сервер повертає:

Статус HTTP 200

Якщо ваш сервер не повертає код HTTP 200, система може повторити спробу відправлення зворотного виклику.

2️⃣ Одиниці обліку залишку в BTC

Для оплати в Bitcoin:

• Поле «Value» повертається у сатоші, а не в BTC.
  

Нагадування:

1 BTC = 100 000 000 сатоші

Приклад:

Якщо значення дорівнює 50000000
, це означає:

0,5 BTC

Для блокчейнів EVM (ethereum, BSC, Tron) значення визначається відповідно до правил, що стосуються найменшої власної одиниці блокчейну.

Простий приклад на PHP для обробки зворотного виклику

$data = json_decode(file_get_contents("php://input"), true);
$status = $data['status'];
$external_id = $data['external_id'];
if ($status == 2) {
   // Mark order as paid in database
}

8. Передові практики

✔ Завжди використовуйте external_id
✔ Завжди перевіряйте callback
✔ Завжди вимагайте точної суми
платежу ✔ Завжди використовуйте окремий ключ API для кожного блокчейн-ланцюга
✔ Не розголошуйте приватні ключі
✔ Для BTC — використовуйте xpub лише під час налаштування криптовалютних платежів надзвичайно важливо розуміти, які існують платіжні системи та які тарифи вони стягують. Крім того, переконайтеся, що ваша платформа відповідає місцевим нормам щодо операцій з криптовалютою. Це допоможе завоювати довіру клієнтів і водночас захистить ваш бізнес.

9. Підсумок

Використання функції «Нова адреса» від Bcon дає змогу:

• Автоматичне створення адрес для оплати
• Автоматично розраховувати суми в криптовалюті
• Автоматичне відстеження платежів
• Автоматично отримувати зворотні дзвінки

Основні відмінності:

Bitcoin:

• Використовує xpub
• Генерує унікальну адресу для кожного інвойсу
• Ідеальна ідентифікація

EVM:

• Одна адреса гаманця
• Застосована диференціація сум
• Необхідна точна сума оплати

Якщо ви розумієте:

• сума_походження
• валюта_походження
• валюта_платежу
• сума_платежу
• external_id
• блокчейн

У такому разі ви повністю контролюєте логіку формування інвойсів.