API 參考

所有接口都從你的服務端調用，請求和返回都是 JSON。

基本約定

地址	`https://api.kokiwa.com`
認證	請求頭 `Authorization: Bearer sk_…`，key 在商戶後台的項目裡建立。一個 key 只能操作它所屬的項目。
金額	代幣最小單位的整數，用字符串表示，例如 18 位小數的 25 USDT 寫作 `"25000000000000000000"`。不要用浮點數計算金額。
冪等	POST 請求可帶 `Idempotency-Key`（最長 255 字符）。同一個 key 重試會返回第一次的結果，並帶上 `Idempotent-Replayed: true`；同一個 key 換了請求內容會返回 422。
時間	ISO 8601 UTC，例如 `2026-11-02T08:30:00Z`。

API key 格式

key 形如 sk_test_… 或 sk_live_…，中間一段表示它屬於哪個環境。kokiwa 目前運行在測試網，發出的都是 sk_test_ key；正式上線後發出 sk_live_ key，測試網的 key 不能在正式環境使用，反之亦然，避免用錯環境。

錯誤

失敗時返回 4xx 或 5xx，內容統一為：

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

請按 code 判斷錯誤類型，message 只用於排查。常見的 code：

code	說明
`unauthorized`	缺少 API key，或 key 無效、已撤銷。
`project_disabled`	項目已被停用。
`chain_not_enabled`	項目在這條鏈上還沒有生效的收款地址，先到後台登記。
`token_not_enabled`	項目沒有勾選這個代幣。
`amount_below_minimum`	金額低於最低收款金額（目前為 5 USDT）。`details.min_amount` 是以代幣最小單位表示的最低金額。
`invalid_*`	參數不合法，`message` 會指出是哪個字段。
`not_found`	資源不存在，或不屬於這個項目。
`idempotency_key_reused`	同一個 Idempotency-Key 用於了不同的請求。

支付單

一張支付單代表一筆需要用戶支付的訂單。用戶在 kokiwa 收銀台完成付款，你通過 Webhook 收到結果。

建立支付單

POST/v1/payment_intents

參數	說明
`options` 必填	可選的付款幣種，1 到 4 個，每個是 `{ chain, token, amount }`，金額不低於 5 USDT。`chain` 目前為 `bsc`；`token` 填代幣符號（如 `USDT`）或合約地址；`amount` 為最小單位。用戶在收銀台選其中一個付款。
`customer`	你系統裡的用戶 ID，1 到 128 個字符，可用字母、數字和 `_ - . : @`。不存在時自動建立。
`expires_in`	有效期秒數，60 到 604800（7 天），默認 1800（30 分鐘）。
`metadata`	任意 JSON 對象，最多 50 個鍵、8KB，原樣出現在查詢結果和 Webhook 裡，適合放訂單號。
`success_url`	付款成功後收銀台跳轉的 https 地址。
`cancel_url`	用戶點「取消」時跳轉的 https 地址。

返回 201 和支付單對象：

{
  "id": "pi_7Gm4Rk2Wp9Ls1Qv8Bd3Zt6",
  "object": "payment_intent",
  "status": "pending",
  "customer": "user_42",
  "checkout_url": "https://pay.kokiwa.com/p/pi_7Gm4Rk2Wp9Ls1Qv8Bd3Zt6",
  "expires_at": "2026-11-02T09:00:00Z",
  "metadata": { "order_id": "10086" },
  "success_url": "https://your-shop.com/orders/10086",
  "cancel_url": null,
  "paid_at": null,
  "created_at": "2026-11-02T08:30:00Z",
  "options": [
    {
      "id": "pio_5Hq2Tz8rLw0aVb3Kc9XyN1",
      "chain": "bsc",
      "token": { "symbol": "USDT", "address": "0x55d3…7955", "decimals": 18 },
      "amount": "25000000000000000000",
      "received": "0",
      "deposit_address": "0x8b1f…c04e"
    }
  ],
  "deposits": []
}

把 checkout_url 給用戶打開即可。也可以在自己的頁面直接展示 deposit_address 讓用戶轉帳；金額太小時這個字段為 null，只能用錢包付款。

查詢支付單

GET/v1/payment_intents/{id}

返回同樣的支付單對象。deposits 列出這張單收到的每一筆鏈上付款（最早的在前），每筆都帶原始交易哈希、區塊和付款地址，格式與 Webhook 裡的 deposit 相同，見 Webhook 通知。Webhook 丟失或需要對帳時用它確認最新狀態。

支付單狀態

status	說明
`pending`	等待付款。
`partially_paid`	已收到一部分，還差 `amount − received`。用戶補足後變為 `paid`。
`paid`	已全額收到，可以發貨。多付的部分也記在 `received` 裡。
`expired`	超過有效期仍未付款。
`paid_late`	過期之後，才有款項轉入這張單的專屬地址。錢已經到你的錢包，請按你的業務決定發貨還是退款。

充值地址

獲取用戶的充值地址

POST/v1/deposit_addresses

參數	說明
`customer` 必填	你系統裡的用戶 ID，規則同上。
`chain`	目前只支援 `bsc`，默認 `bsc`。

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

同一個用戶永遠返回同一個地址，可以長期展示給用戶。tokens 列出這個地址接受的代幣，只有轉入這些代幣才會入帳。

每筆入帳都會發 deposit.confirmed。單筆低於 min_settle_amount（目前為 5 USDT）的入帳狀態為 held，同樣計入，等這個地址累積到最低金額後一起歸集到你的收款錢包，只收一次固定費用。歸集的 gas 由 kokiwa 支付。

入帳記錄

每一筆計入的鏈上付款都是一條入帳記錄（deposit），包括支付單的付款和充值地址的轉帳。對象格式與 Webhook 裡的 deposit 相同，包含付款交易 transaction 和分帳交易 settlement。

查詢入帳

GET/v1/deposits/{id}

列出入帳

GET/v1/deposits

查詢參數	說明
`customer`	只看某個用戶的入帳。
`payment_intent`	只看某張支付單的入帳。
`tx_hash`	按鏈上交易哈希查找，付款交易或分帳交易都可以。用戶拿著交易哈希來問「我的錢到了嗎」時用它。
`limit`	每頁條數，1 到 100，默認 20。
`starting_after`	上一頁最後一條的 `id`，取下一頁。

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 }

按時間從新到舊返回。

客戶

建立或更新客戶

PUT/v1/customers/{external_id}

可選。建立支付單或充值地址時會自動建立客戶，這個接口用於加上標籤和備註，方便在後台篩選。

參數	說明
`tags`	最多 20 個標籤，每個 1 到 64 個字符（字母、數字和 `_ - . :`）。
`metadata`	任意 JSON 對象，最多 50 個鍵、8KB。

查詢客戶

GET/v1/customers/{external_id}

返回客戶的標籤、備註和 deposit_addresses（已生成的充值地址，按鏈列出）。

Webhook 地址

也可以在後台的「回調通知」頁管理，效果相同。

新增

POST/v1/webhook_endpoints

參數 url（必填，公網 https 地址）、description、events（要接收的事件類型，留空表示全部）。每個項目最多 10 個。返回的 secret 只出現這一次，用於校驗簽名。

列出

GET/v1/webhook_endpoints

刪除

DELETE/v1/webhook_endpoints/{id}

發送測試事件

POST/v1/webhook_endpoints/{id}/test

向這個地址發送一個 webhook.test 事件，用來檢查接收和簽名校驗是否正常。

下一篇：Webhook 通知