Payment API

Payment API позволяет создавать платёжные сессии, перенаправлять клиентов на хостед-чекаут и отслеживать статус платежа.

Создать платёж

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

Ошибки

Направление недоступно

Если выбранная комбинация to_currency + network (или currency как криптовалюта) временно отключена на платформе, API вернёт:

{
  "state": 1,
  "error_code": "direction_disabled",
  "errors": {
    "direction": "This direction is temporarily unavailable"
  }
}

HTTP статус: 503 Service Unavailable

Проверить актуальный статус всех направлений можно через GET /v1/directions. Скрывайте недоступные направления в UI заранее, чтобы не показывать пользователю ошибку.

Платёжная страница, 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. Не создавайте второй локальный заказ только из-за тайм-аута запроса к API.

Нестандартные ситуации при оплате

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"