API криптовалютного платіжного шлюзу: інвойси, вебхуки, виплати та white label

Що робить API криптовалютного платіжного шлюзу?

API ховає блокчейн від вашого коду. Замість того щоб запускати ноди, виводити адреси й рахувати підтвердження, ви викликаєте ендпоінт створення інвойсу, зберігаєте ідентифікатор шлюзу й чекаєте на сповіщення. Шлюз надає курс обміну, стежить за мережами, застосовує AML-скринінг і розраховується на ваш баланс.

Більшість шлюзів пропонує однакові будівельні блоки під різними назвами: інвойси або замовлення для вхідних платежів, IPN чи колбеки для сповіщень, ендпоінти конвертації та балансу, виплати або виведення для вихідних переказів. Пісочниці є в більшості провайдерів, наприклад окремий sandbox-хост у CoinGate і sandbox-акаунт у NOWPayments, і ними слід користуватися перед будь-яким тестом у основній мережі.

• API інвойсів: створення, читання й скасування запитів на оплату з фіатною ціною, прийнятними монетами, номером замовлення та URL колбека
• Сповіщення: вебхуки або IPN при кожній зміні статусу, зазвичай підписані
• API виплат: надсилання крипти або фіату клієнтам, партнерам чи на власний гаманець
• Курси й валюти: список підтримуваних монет, мереж, мінімальних сум і поточні котирування
• Плагіни та SDK: готові модулі для e-commerce-платформ на основі того самого API

Що таке крипто шлюз і чим він відрізняється від API?

Крипто шлюз (криптошлюз) — це сервіс, який приймає платежі в криптовалюті для вашого сайту: стежить за блокчейном, підтверджує оплату, за потреби конвертує монети у фіат і робить виплати вам. API — це спосіб, у який ваша платформа спілкується з цим сервісом. Деякі постачальники продають лише API, інші додають хостовану сторінку оплати, плагіни для CMS і кабінет.

Головна різниця між шлюзами — зберігання коштів. Кастодіальний шлюз сам отримує монети й розраховується з вами в криптовалюті або фіаті. У некастодіальній моделі оплата надходить на гаманці, які контролюєте ви, а шлюз лише створює адреси й повідомляє статус. Від цього залежить, кому потрібна ліцензія і хто відповідає за безпеку ключів.

Як підключити криптопроцесинг до сайту?

Почніть із вибору моделі: кастодіальний чи некастодіальний шлюз, розрахунок у криптовалюті чи фіаті. Для бізнесу в ЄС перевірте, чи має постачальник авторизацію постачальника послуг із криптоактивами за регламентом MiCA (Regulation (EU) 2023/1114), і які країни та монети він обслуговує. Технічна частина зазвичай складається з кроків нижче; покрокову інтеграцію API описано в інструкції на цій сторінці.

• Створіть акаунт у постачальника, пройдіть перевірку бізнесу й отримайте ключі API для sandbox
• Оберіть монети й мережі, які показуватимете покупцям
• Підключіть хостовану сторінку оплати, плагін CMS або власний checkout через API
• Налаштуйте й перевірте підписані вебхуки, а замовлення позначайте оплаченим лише після фінального статусу
• Опишіть правила для недоплат, прострочених інвойсів і повернень
• Перейдіть на робочі ключі після тестових оплат у sandbox

Як працює життєвий цикл інвойсу?

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

Таблиця зіставляє дві опубліковані моделі статусів зі станами, які потрібні більшості платформ. CoinGate, наприклад, закриває несплачений інвойс через 20 хвилин після вибору монети покупцем і позначає платежі, відмічені AML-перевірками, як недійсні.

Як перевіряти криптовалютні вебхуки та IPN?

Вважайте кожне сповіщення недовіреним, доки його не перевірено. Шлюзи застосовують різні схеми: NOWPayments підписує відсортоване JSON-тіло алгоритмом HMAC-SHA512 і передає підпис у заголовку x-nowpayments-sig, CoinGate надсилає токен, який ви задаєте для замовлення, а BitPay радить після кожного сповіщення отримувати інвойс з API замість того, щоб довіряти його тілу.

Найнадійніший підхід поєднує обидва: перевірте підпис, а потім прочитайте інвойс з API та діяйте за цією відповіддю. Це коштує один запит на зміну статусу й захищає від підроблених чи повторно надісланих колбеків.

• Перевіряйте підписи порівнянням за сталий час і відхиляйте непідписані запити
• Перед зміною стану замовлення повторно отримуйте інвойс за ідентифікатором шлюзу
• Швидко повертайте HTTP 200 і обробляйте асинхронно; шлюзи повторюють запити при помилках
• Зберігайте кожне сповіщення з подією чи статусом, щоб ігнорувати дублікати
• Ніколи не довіряйте сумам і валютам, що приходять у редиректі браузера

Як обробляти недоплати, переплати та запізнілі платежі?

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

Як працюють ідемпотентність і звірка?

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

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

Що потрібно API виплат за Travel Rule?

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

У ЄС Регламент (ЄС) 2023/1113 вимагає, щоб шлюз передавав дані відправника й отримувача з кожним переказом і перевіряв власність на самостійно керовані гаманці понад 1000 EUR. Очікуйте, що запити на виплату міститимуть ім'я отримувача й тип адреси, та плануйте перекази, які очікують на ці дані.

Які є варіанти white label для криптовалютного шлюзу?

Платформи, що перепродають платежі власним мерчантам, часто хочуть мати сторінку оплати під своїм брендом. Є три рівні, і ціна зростає разом із контролем. Plisio, наприклад, указує 0,5% за API та 1,5% за white label, а NOWPayments продає окремий white-label-продукт.

Повний white label переносить не лише бренд, а й відповідальність. Якщо ви онбордите мерчантів і тримаєте їхні баланси, вам може знадобитися власний дозвіл MiCA; модель sub-merchant у шлюзі з дозволом залишає цей обов'язок за шлюзом.

Як підключити API криптошлюзів через OrsunPay?

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

Як інтегрувати API криптовалютного платіжного шлюзу

1. Відкрийте sandbox-акаунти Створіть sandbox- і робочі акаунти в шлюзі, згенеруйте окремі API-ключі для інвойсів і виплат та задайте секрет IPN.
2. Зіставте статуси Перекладіть статуси шлюзу у ваші внутрішні стани й визначте, який із них відправляє товар.
3. Створюйте інвойси ідемпотентно Надсилайте фіатну суму, валюту, номер замовлення й URL колбека; перед повтором виклику після тайм-ауту шукайте інвойс за номером.
4. Перевіряйте сповіщення Перевірте підпис, отримайте інвойс з API та обробіть подію рівно один раз.
5. Обробіть крайні випадки Реалізуйте допуск, доплату, повернення та завершення строку й протестуйте кожен сценарій у sandbox.
6. Звіряйте розрахунки Зберігайте хеш транзакції, курс і комісію для кожного інвойсу та щодня зіставляйте пакети виплат із замовленнями.