API 參考

所有接口都從你的服務端調用，請求和返回都是 JSON。Webhook 地址和 API key 在商戶後台管理。

基本約定

錯誤

失敗時返回 4xx 或 5xx。請按 code 判斷錯誤類型，message 只用於排查。

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

支付單

一張支付單是一筆要用戶支付的訂單。用戶在收銀台付款，結果通過 Webhook 通知你。

低於最低收款金額的鏈會被排除；所有鏈都不滿足時返回錯誤。默認最低金額是 5 美元，你的費率見後台項目的「費率」部分。

指定每條鏈的代幣和金額

需要同時收多個幣種，或者每條鏈金額不同時，用 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": []
}

返回支付單對象。用於對帳，或在沒有收到 Webhook 時確認狀態。

支付單狀態

充值地址

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

這裡是可以填寫的全部範圍，不代表某個項目都能使用。每個商戶的配置不同，實際可用的鏈和幣種請用下面的接口查詢。

返回這個 key 所屬的項目在當前網絡的收款能力。

{
  "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（按鏈列出的充值地址）。