kokiwa

接入引導

你的服務端調用 API 建立收款，kokiwa 在到帳後發 Webhook 通知你。資金由鏈上直接進你的錢包，kokiwa 不經手。

先在測試網用免費的測試幣跑通全部流程，見測試。想先看用戶看到的頁面，到付款體驗試一筆。

準備工作

以下都在商戶後台完成。

  1. 註冊驗證郵箱，綁定身份驗證器，保存恢復碼。
  2. 建立項目一個項目對應你的一個產品或網站，有自己的收款地址、API key 和 Webhook。
  3. 設定收款在項目的「收款設定」頁選擇鏈、收款方式和代幣，並在每條鏈上用錢包登記一次收款地址。收款地址記錄在鏈上，只有登記它的錢包能修改。登記需要你的錢包付一點 gas，同一個錢包可以登記所有 EVM 鏈。
  4. 建立 API keykey 只顯示一次，保存在服務端的環境變量裡，不要放進前端或 App。
  5. 設置 Webhook在「回調通知」頁填寫 https 接收地址，保存簽名密鑰，再點「發送測試事件」確認能收到。

選擇收款方式

支付單充值地址
適合訂單：金額固定，一次付清帳戶充值：金額由用戶決定，可以多次
地址每張單一個，過期作廢每個用戶一個，永久不變
用戶怎麼付打開收銀台，用錢包付款；BNB Chain 上也可以轉帳到專屬地址從錢包或交易所轉帳
鏈全部 8 條BNB Chain
gas錢包付款由用戶支付；轉帳的歸集由 kokiwa 支付轉帳由用戶支付；歸集由 kokiwa 支付

兩種方式可以同時使用。

支付單

用戶下單時建立支付單，把返回的 checkout_url 給用戶打開。下面的請求會列出項目所有能收 USDT 的鏈，用戶自己選擇。

curl https://api.kokiwa.com/v1/payment_intents \
  -H "Authorization: Bearer $KOKIWA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-10086" \
  -d '{
    "currency": "USDT",
    "amount": "25.00",
    "customer": "user_42",
    "metadata": { "order_id": "10086" },
    "success_url": "https://your-shop.com/orders/10086"
  }'

充值地址

customer 填你系統裡的用戶 ID。同一個用戶重複調用，返回同一個地址。

curl https://api.kokiwa.com/v1/deposit_addresses \
  -H "Authorization: Bearer $KOKIWA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "customer": "user_42" }'

確認入帳

付款在鏈上確認後，kokiwa 發送 Webhook。只憑 Webhook 入帳，不要憑用戶跳回 success_url。

  • 支付單：收到 payment_intent.paid，把訂單標記為已付款。
  • 充值地址：收到 deposit.confirmed，給 data.deposit.customer 加餘額。

每個事件都要校驗簽名，並按事件 id 去重，見 Webhook。

金額

所有金額都是代幣數量的字符串，例如 "25.00"、"24.9125"。請求、返回和 Webhook 都一樣，不需要按鏈換算精度。金額保留鏈上的完整精度，所以小數位數不固定。不要用浮點數計算。

退款

資金已經在你的錢包裡，kokiwa 沒有退款接口，也無法撤回付款。退款時從你的收款地址轉給用戶。請向用戶索取退款地址，不要直接退到 transaction.from：用戶從交易所提幣時，那是交易所的地址。手續費不退還。

上線前檢查

  • API key 只存在服務端，不在代碼倉庫和日誌裡。
  • Webhook 校驗了簽名，同一事件重複到達不會重複入帳。
  • 建立支付單時帶了 Idempotency-Key，網絡重試不會產生兩張單。
  • 處理了 payment_intent.paid_late：過期後才到帳的付款不會被漏掉。
  • 主網上已登記收款地址，並換成 sk_live_ 開頭的 key。
  • 收款地址的助記詞已備份。
下一篇：測試

Connect a wallet with WalletConnect