Sign in
Вступ/Загальна інформація

Загальна інформація

Технічна специфікація для інтеграції обробки криптовалютних платежів та виплат із 2328.io.

Відкрити як Markdown·llms.txt

Ласкаво просимо до документації API 2328.io. Цей довідник описує, як інтегрувати обробку криптовалютних платежів та виплат у вашу програму.

Початок роботи

Щоб розпочати інтеграцію:

  1. Створіть мерчант-акаунт та проєкт на 2328.io
  2. Отримайте project UUID та API key у налаштуваннях проєкту
  3. Згенеруйте окремий Payout API key, якщо плануєте використовувати виплати
  4. Прочитайте розділ Автентифікація, щоб дізнатися, як підписувати запити
  5. Виконайте свій перший виклик Створити платіж

Базовий URL

Усі продакшн-запити до API використовують такий базовий URL:

Text
https://api.2328.io/api

Усі запити мають здійснюватися через HTTPS. Запити без HTTPS блокуються.

Що ви можете робити

За допомогою API 2328.io ви можете:

  • Приймати криптоплатежі — створювати платіжні сесії та перенаправляти клієнтів на хостинговий checkout або Telegram MiniApp
  • Виводити кошти — програмно надсилати виплати з мерчант-балансу на будь-яку блокчейн-адресу
  • Перевірка балансів — баланс рахунків мерчанта за кожною валютою, еквівалент у USD та суми, заблоковані AML
  • Використовувати статичні гаманці — генерувати постійні депозитні адреси, прив'язані до користувача або замовлення
  • Отримувати курси обміну — отримувати курси у режимі реального часу для пар фіат/крипто
  • Отримувати webhooks — отримувати миттєві сповіщення про зміну статусу платежу

Обмеження частоти запитів

API дозволяє до 10 запитів на секунду на проєкт. Запити, що перевищують ліміт, отримують HTTP-відповідь 429 Too Many Requests — зачекайте та повторіть запит.

Виберіть правильний інтеграційний шаблон

ВимогаРекомендований шаблонЧому
Дозвольте клієнту обрати спосіб оплатиХостингове оформлення замовленняСтворіть платіж та перенаправте на result.url; 2328.io показує наявні напрямки.
Тримайте клієнта всередині власного оформлення замовленняПряма адреса на H2H рахунок-фактуруНадішліть to_currency та network під час створення платежу; відобразіть повернуті address, payer_amount, та qr.
Списувати точно 25 USDT або 0.001 BTCРахунок-фактура в криптовалютіПомістіть криптовалюту в currency і точну десяткову суму в amount.
Надайте кожному користувачу повторно використовувану депозитну адресуСтатичний гаманецьАдреса постійна і може приймати багато незалежних депозитів.
Нормалізуйте вхідні активи в одну валюту балансуАвтоматичне конвертуванняНалаштуйте правила проєкту на панелі управління та використовуйте результат convert після завершення конвертації.
Обміняйте існуючий баланс продавцяРучне конвертуванняПопередній перегляд з /v1/convert/price, потім виконайте з /v1/convert.
Надішліть кошти на адресу блокчейнуВиплатаВикористовуйте окремий API-ключ для виплат, спочатку розрахуйте суму і погодьте статус виплати.

Хостингова каса та H2H — це два представлення одного й того самого Payment API. H2H не створює слабший або непідписаний платіж: на бекенді все одно створюється рахунок, 2328.io досі володіє адресою та статусом, а підписані вебхуки залишаються авторитетними для розрахунків.

Інваріанти інтеграції

Ці правила застосовуються до кожної інтеграції у виробництві:

  • Backend only — тримайте API-ключі поза браузерами, мобільними додатками, журналами, аналітикою та скріншотами підтримки.
  • Decimal strings — відправляйте та зберігайте гроші як рядки. Ніколи не округлюйте криптовалюту або обмінні курси за допомогою бінарної чисельної арифметики з плаваючою комою.
  • Immutable idempotency keys — генеруйте order_id перед першим запитом і зберігайте повний запит разом із ним. Повторна спроба з тим самим order_id може повернути оригінальний об'єкт замість застосування змінених полів.
  • Webhook-first settlement — перенаправлення, опитування клієнтом, хеші транзакцій, надані користувачами, та тайм-аути HTTP не є доказом оплати.
  • Verify, deduplicate, then mutate — перевіряйте HMAC, атомарно отримуйте запис ідемпотентності, оновлюйте замовлення/баланс один раз і швидко повертайте HTTP 200.
  • Reconciliation — періодично перевіряйте статус оплати, статичного гаманця та виплат, щоб загублений вебхук не залишав постійної невідповідності.
  • Dynamic availability — перевіряйте пари валюта/мережа за допомогою /v1/directions; підтримуваний актив все ще може мати тимчасово відключений один напрямок депозиту або зняття коштів.
  • Explicit status policy — вирішіть, як ваш продукт обробляє часткові платежі, переплату, термін дії, блокування AML, резервне перетворення та неоднозначні тайм-аути вищого рівня перед запуском.

Для платежів зберігайте принаймні uuid, order_id, оригінальне тіло запиту, amount, currency, payer_currency, payer_amount, network, address, expires_at, останні payment_status, txid, payment_amount, merchant_amount, необов'язковий блок convert та необроблений перевірений вебхук.

Для статичних гаманців зберігайте гаманець uuid, адресу, валюту, мережу, посилання на клієнта/рахунок, статус та URL для зворотного виклику окремо від записів депозитів. Кожен депозит потребує власної транзакції uuid, txid, статусу, отриманої суми, суми торговця та результату конверсії.