Платежі та виплати/Payment API

Payment API

Створюйте та керуйте сесіями криптовалютних платежів за допомогою Payment API від 2328.io.

Payment API дозволяє створювати платіжні сесії, перенаправляти клієнтів на хостинговий checkout та відстежувати статус платежу.

Створити платіж

Створює платіжну сесію та повертає URL, за яким клієнт здійснює оплату.

Параметри запиту

Поле	Тип	Обов'язкове	Опис
`amount`	decimal	так	Сума платежу у валюті, наприклад, `100.00`
`currency`	string	так	Фіатна валюта (USD, EUR, RUB, …) або криптовалюта (USDT, TRX, BTC, …)
`order_id`	string	так	Ваш ID замовлення, наприклад, `ORDER-12345` (до 128 символів)
`to_currency`	string	ні	Попередньо обрана криптовалюта
`network`	string	ні*	Код мережі (обов'язковий, якщо встановлено `to_currency` або `currency` є криптовалютою)
`url_return`	string	ні	URL перенаправлення після оплати, наприклад, `https://your-site.com/return`
`url_success`	string	ні	Альтернатива `url_return`
`url_callback`	string	ні	URL для webhook-сповіщень, наприклад, `https://your-site.com/webhook`
`invite_code`	string	ні	Код реферера
`fee_split`	decimal	ні	Частка мерчант-комісії, що передається платнику, 0–100 (%). 0 = мерчант сплачує повністю, 100 = платник сплачує повністю. Перевизначає налаштування рівня проєкту. Приклад: `30` (платник покриває 30% комісії).
`price_markup`	decimal	ні	Націнка або знижка на суму рахунку, від −99 до 100 (%). Перевизначає налаштування рівня проєкту. Приклад: `5` (+5%) або `-10` (знижка 10%).
`description`	string	ні	Необов'язковий опис рахунку (макс. 200 символів). Відображається платнику на сторінці оплати. Приклад: `Premium plan — Order #12345`.
`ttl_seconds`	int	ні	Час життя рахунку в секундах, від `300` (5 хвилин) до `86400` (24 годин). Після цього часу рахунок завершується й сплатити його більше не можна. За замовчуванням: `3600` (1 година). Приклад: `3600`.

Відповідь

JSON

{
  "state": 0,
  "result": {
    "uuid": "abc123-def456-...",
    "order_id": "ORDER-12345",
    "amount": "100.00",
    "currency": "USD",
    "amount_usd": "100.00",
    "exchange_rate": null,
    "url": "https://2328.io/pay/abc123-def456-...",
    "tg_deeplink": "https://t.me/my2328bot?start=pay_abc123-def456-...",
    "expires_at": "2026-01-11T21:00:00Z",
    "created_at": "2026-01-11T20:00:00Z",
    "payer_currency": "USDT",
    "payer_amount": "100.50",
    "network": "TRX-TRC20",
    "address": "TXYZabc123...",
    "payment_status": "check",
    "txid": null,
    "payment_amount": null,
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

Перенаправте клієнта на result.url для завершення оплати.
tg_deeplink — deeplink Telegram-бота для оплати через Telegram MiniApp.
qr — QR-код депозитної адреси, закодований у base64 (data URI). Присутній, коли адресу вже призначено (коли network встановлено разом із to_currency або коли currency є криптовалютою); інакше null.
txid, payment_amount — null, доки клієнт не оплатить. Заповнюються після виявлення транзакції у блокчейні. Слухайте webhook payment_status: paid, щоб дізнатися момент.
exchange_rate — null, якщо конвертація ще не застосовна (наприклад, курс фіат → крипто ще не зафіксовано). Заповнюється після вибору валюти платника.

Credentials

Project UUIDAPI key

RequestPOST/v1/payment

curl -X POST https://api.2328.io/api/v1/payment \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Response

Click Try it to see the response here.

Інформація про платіж

Отримати поточний статус платежу за uuid або order_id.

Параметри запиту

Поле	Тип	Обов'язкове	Опис	Значення
`uuid`	string	так*	UUID платежу (з `result.uuid` під час створення)
`order_id`	string	так*	Ваш ID замовлення

Принаймні одне з полів uuid або order_id є обов'язковим.

RequestPOST/v1/payment/info

curl -X POST https://api.2328.io/api/v1/payment/info \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Response

Click Try it to see the response here.

Список платежів

Отримати список усіх платежів із фільтрацією та пагінацією.

Параметри запиту

Поле	Тип	Обов'язкове	Опис
`status`	string	ні	Фільтрувати за статусом платежу (див. References)
`date_from`	date	ні	Початкова дата (YYYY-MM-DD), наприклад, `2026-01-01`
`date_to`	date	ні	Кінцева дата (YYYY-MM-DD), наприклад, `2026-01-31`
`page`	int	ні	Номер сторінки, за замовчуванням `1`
`per_page`	int	ні	Елементів на сторінці, за замовчуванням `15`, максимум `5000`

RequestPOST/v1/payment/list

curl -X POST https://api.2328.io/api/v1/payment/list \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Response

Click Try it to see the response here.