Payment API

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

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

{
  "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..."
  }
}

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"

Розміщена каса, H2H та точні крипто-суми

Той самий кінцевий пункт підтримує три різних форми рахунків. Оберіть одну свідомо; не змішуйте їх семантику сум.

Розміщена каса з вибором платника

Надішліть amount, currency, order_id та url_callback, але пропустіть to_currency та network. Відповідь містить result.url; address, qr та іноді поля платника залишаються null, поки платник не обере напрямок на розміщеній сторінці.

{
  "amount": "125.00",
  "currency": "EUR",
  "order_id": "ORDER-2026-1042",
  "url_callback": "https://merchant.example/webhooks/2328",
  "url_return": "https://merchant.example/orders/ORDER-2026-1042"
}

Прямий рахунок H2H

Надішліть обидва to_currency та network. 2328.io створює блокчейн-рахунок під час виклику API, тому успішну відповідь можна відобразити безпосередньо у вашому оформленні замовлення без перенаправлення клієнта.

{
  "amount": "100.00",
  "currency": "USD",
  "to_currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1043",
  "url_callback": "https://merchant.example/webhooks/2328"
}

Відображайте ці значення точно так, як вони повернуті:

• payer_amount та payer_currency — інструкція для оплати;
• network та address — єдина адреса для цього рахунку;
• qr — data URI для тієї ж адреси;
• expires_at — термін дії рахунку;
• url — корисний розміщений резервний варіант, коли кастомне оформлення замовлення не може бути завершене.

Рахунок-фактура на точну суму криптовалюти

Помістіть криптовалюту в currency, коли сам рахунок-фактура номінований у криптовалюті:

{
  "amount": "25.000000",
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1044",
  "url_callback": "https://merchant.example/webhooks/2328"
}

Запитувана вартість криптовалюти збережена в payer_currency / payer_amount. Сервіс також може підтримувати внутрішню оцінку в USD для обліку та полів курсу; не замінюйте точну інструкцію щодо криптовалюти на цю оцінку. Зберігайте повернені десяткові рядки, включаючи кінцеву точність.

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

Ідемпотентність та повторні спроби

order_id прив'язується до аутентифікованого проекту продавця та слугує ключем ідемпотентності створення. Якщо платіж вже існує, API повертає ту сесію з state: 0.

Рекомендований алгоритм створення:

1. Вставте вашу локальну спробу оплати та унікальний order_id в одну транзакцію бази даних.
2. Надішліть підписаний API-запит.
3. Збережіть повернутий uuid та повну відповідь.
4. Якщо HTTP-результат втрачено, повторіть ідентичний запит або виконайте запит /v1/payment/info за допомогою order_id.
5. Ніколи не створюйте друге локальне замовлення тільки через те, що запит до зворотного сервера вичерпав час очікування.

Крайні випадки оплати

URL-адреса повернення браузера використовується лише для навігації. Клієнт може відкрити її без оплати, закрити після оплати або переграти пізніше. Лише підтверджений стан API/webhook може завершити замовлення торговця.

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

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"

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

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"