Справочник API

Вызывайте все методы со своего сервера. Запросы и ответы в формате JSON. Адреса вебхуков и API-ключи управляются в кабинете мерчанта.

Основные правила

Ошибки

При сбое возвращается 4xx или 5xx. Ориентируйтесь на code; message нужен только для отладки.

{
  "error": {
    "code": "amount_below_minimum",
    "message": "options[0].amount is below the minimum",
    "details": { "min_amount": "5.00" }
  }
}

Платежи

Платёж — это заказ, который должен оплатить пользователь. Пользователь платит на странице оплаты, а результат приходит вебхуком.

Сети, где сумма ниже минимума, исключаются; если не осталось ни одной, запрос завершается ошибкой. Минимум по умолчанию — 5 USD; ваши комиссии указаны в разделе «Комиссии» проекта в кабинете.

Токен и сумма для каждой сети

Чтобы принимать несколько валют или разные суммы в разных сетях, передавайте options вместо currency, amount и chains. До 16 элементов; token — символ или адрес контракта.

"options": [
  { "chain": "bsc", "token": "USDT", "amount": "25.00" },
  { "chain": "bsc", "token": "USDC", "amount": "25.00" }
]

Ответ

Возвращает 201 и платёж. Откройте checkout_url для пользователя.

{
  "id": "pi_7Gm4Rk2Wp9Ls1Qv8Bd3Zt6",
  "object": "payment_intent",
  "status": "pending",
  "livemode": true,
  "customer": "user_42",
  "checkout_url": "https://pay.kokiwa.com/p/pi_7Gm4Rk2Wp9Ls1Qv8Bd3Zt6",
  "metadata": { "order_id": "10086" },
  "success_url": "https://your-shop.com/orders/10086",
  "cancel_url": null,
  "created_at": "2026-11-02T08:30:00Z",
  "expires_at": "2026-11-02T09:00:00Z",
  "paid_at": null,
  "paid_option": null,
  "options": [
    {
      "id": "pio_5Hq2Tz8rLw0aVb3Kc9XyN1",
      "chain": "bsc",
      "token": { "symbol": "USDT", "address": "0x55d3…7955", "decimals": 18 },
      "amount": "25.00",
      "received": "0.00",
      "deposit_address": "0x8b1F…c04E"
    },
    {
      "id": "pio_2Mn7Xc4bQe6uJs1Ga8RvK3",
      "chain": "base",
      "token": { "symbol": "USDT", "address": "0xfde4…9bb2", "decimals": 6 },
      "amount": "25.00",
      "received": "0.00",
      "deposit_address": null
    }
  ],
  "deposits": []
}

Возвращает платёж. Используйте для сверки или проверки статуса, если вебхук не пришёл.

Статус платежа

Адреса пополнения

{
  "object": "deposit_address",
  "customer": "user_42",
  "chain": "bsc",
  "address": "0x3c9A…71d2",
  "tokens": [
    { "symbol": "USDT", "address": "0x55d3…7955", "decimals": 18, "min_settle_amount": "5.00" }
  ]
}

Один пользователь всегда получает один и тот же адрес, поэтому его можно показывать долго. Зачисляются только токены из tokens.

Каждый перевод отправляет deposit.confirmed. Переводы меньше min_settle_amount тоже зачисляются, со статусом held; когда на адресе накопится минимум, они вместе собираются на ваш адрес получения за одну фиксированную комиссию.

Поступления

Поступление (deposit) — это один зачисленный платёж в блокчейне по платежу или на адрес пополнения. У одного платежа их может быть несколько.

{
  "id": "dep_9Kx2Pa6Wn3Ty8Lq5Rb1Ms4",
  "object": "deposit",
  "status": "settled",
  "method": "wallet",
  "chain": "bsc",
  "customer": "user_42",
  "payment_intent": "pi_7Gm4Rk2Wp9Ls1Qv8Bd3Zt6",
  "token": { "symbol": "USDT", "address": "0x55d3…7955", "decimals": 18 },
  "amount": "25.00",
  "fee": "0.0875",
  "net": "24.9125",
  "usd_value": "25.00",
  "confirmed_at": "2026-11-02T08:41:07Z",
  "transaction": {
    "hash": "0x4e7a…91c3",
    "log_index": 212,
    "block_number": 44718235,
    "block_time": "2026-11-02T08:40:58Z",
    "from": "0x1f9C…a2B0",
    "to": "0x7d3E…09f1",
    "raw_amount": "25000000000000000000"
  },
  "settlement": {
    "tx_hash": "0x4e7a…91c3",
    "by": "payment",
    "settled_at": "2026-11-02T08:40:58Z"
  }
}

Сначала самые новые.

curl "https://api.kokiwa.com/v1/deposits?tx_hash=0x4e7a…91c3" \
  -H "Authorization: Bearer $KOKIWA_KEY"

{ "object": "list", "data": [ { "id": "dep_9Kx2…", "object": "deposit", ... } ], "has_more": false }

Сети и токены

kokiwa поддерживает перечисленные ниже сети и валюты. В chains и options[].chain указывайте значение из столбца chain, а в currency — из столбца валют.

В тестовой сети доступен только USDT. Токен называется tUSDT, но в currency по-прежнему указывается USDT.

Это полный диапазон значений, а не то, что доступно конкретному проекту. Настройки у продавцов разные, поэтому фактически доступные сети и валюты запрашивайте через метод ниже.

Возвращает, что проект этого ключа может принимать в текущей сети.

{
  "object": "list",
  "livemode": true,
  "currencies": ["USDT"],
  "data": [
    {
      "object": "chain", "chain": "bsc", "name": "BNB Smart Chain", "chain_id": 56, "testnet": false, "native": "BNB",
      "payout_registered": true, "active": true,
      "methods": { "wallet": true, "deposit_address": true },
      "tokens": [
        { "symbol": "USDT", "asset": "USDT", "address": "0x55d398326f99059fF775485246999027B3197955", "decimals": 18, "accepted": true },
        { "symbol": "USDC", "asset": "USDC", "address": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d", "decimals": 18, "accepted": false }
      ]
    }
  ]
}

Клиенты

Необязательно. Клиент создаётся, когда значение customer появляется впервые; эти методы нужны только для фильтрации по тегам в кабинете.

Возвращает теги, заметки и deposit_addresses (адреса пополнения по сетям).