kokiwa

測試

kokiwa 目前整個運行在 BNB Chain 測試網（chain ID 97）。用免費的測試幣，可以把註冊、登記收款地址、付款、Webhook 全部走一遍，不涉及真實資金。

測試網上的數據在正式上線前會被清空，屆時需要重新建立項目、API key 和 Webhook，API key 前綴也會從 sk_test_ 變為 sk_live_。

1. 準備測試錢包

  1. 安裝一個瀏覽器錢包，例如 MetaMask 或 OKX Wallet。建議新建一個只用於測試的帳戶。
  2. 到 BNB Chain 官方水龍頭領取少量 tBNB。測試時你同時扮演付款人，付款交易的 gas 由付款人支付；登記收款地址也需要一次 gas。
  3. 在下方領取測試穩定幣 tUSDT（18 位小數，每次最多 1000）：
領取 1000 tUSDT

沒有檢測到瀏覽器錢包。請安裝 MetaMask、OKX Wallet 等錢包插件後刷新頁面。

tUSDT 合約地址：0x98FFFaC1f8a26828AFFD1d9e022bf95d978C5917。如果錢包裡看不到餘額，在錢包中手動添加這個代幣。

2. 設置項目

按接入引導的準備工作操作：註冊、建立項目、用測試錢包登記收款地址、勾選 tUSDT、建立 API key、設置 Webhook。登記交易同樣在測試網上進行。

Webhook 地址必須是公網可訪問的 https 地址。本機開發時，可以用 cloudflared tunnel 或 ngrok 把本機服務暴露出去，再在後台點「發送測試事件」確認簽名校驗通過。

3. 建立一張支付單

curl https://api.kokiwa.com/v1/payment_intents \
  -H "Authorization: Bearer $KOKIWA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "test_user_1",
    "options": [{ "chain": "bsc", "token": "tUSDT", "amount": "10000000000000000000" }]
  }'

打開返回的 checkout_url，用另一個測試帳戶付款（自己付給自己也可以，但分帳結果不直觀）。到帳後你會收到 deposit.confirmed、deposit.settled 和 payment_intent.paid，後台「收款明細」裡能看到這筆付款、手續費和鏈上交易。把 Webhook 裡的 transaction.hash 拿到 BscScan 測試網上查，可以看到同一筆交易裡分給你和 kokiwa 的兩筆轉帳。

4. 建議測試的場景

場景怎麼做預期結果
錢包付款在收銀台選「連接錢包付款」並確認payment_intent.paid，channel 為 router
轉帳付款在收銀台選「轉帳到地址」，從錢包向顯示的地址轉入全額deposit.confirmed，然後 payment_intent.paid；歸集後 deposit.settled
少付向支付單地址轉入少於訂單的金額payment_intent.partially_paid；補足後變為 paid
過期建立時設 "expires_in": 60，等 1 分鐘payment_intent.expired
過期後到帳過期後再向支付單地址轉帳payment_intent.paid_late
充值地址調用 POST /v1/deposit_addresses，向返回的地址轉入 tUSDTdeposit.confirmed，payment_intent 為 null
小額充值向充值地址轉入低於 min_settle_amount 的金額，再轉幾筆每筆都有 deposit.confirmed（狀態 held）；累積到最低金額後一起歸集
重試讓你的接口對一個付款事件先返回 500，之後再恢復正常kokiwa 按計劃重試（Kokiwa-Delivery-Attempt 遞增），你的系統只入帳一次；也可以在後台對失敗的投遞點「重新投遞」
簽名錯誤用錯誤的密鑰校驗你的接口返回 400，後台顯示投遞失敗並安排重試

到帳時間

kokiwa 只計入 BNB Chain 已最終確認（finalized）的區塊，從付款到收到 Webhook 通常需要幾秒到半分鐘。轉帳到地址的款項還需要等歸集交易確認，deposit.settled 會再晚一些。

費率

與正式費率相同：每筆 0.2 USD + 0.5%，錢包付款和轉帳到地址一樣，單筆最低 5 tUSDT。例如付 10 tUSDT，手續費 0.25，到你錢包 9.75。分帳和歸集的 gas 由 kokiwa 支付；付款人自己發起轉帳的網絡費由付款人的錢包支付。

回到接入引導