接入引導

從註冊到收到第一筆付款。整個過程只需要你的服務端調用幾個 API，並接收一個 Webhook。

準備工作

1. 註冊商戶到 kokiwa.com 註冊，用郵箱驗證碼確認郵箱，再綁定身份驗證器（Google Authenticator、1Password 等）並保存恢復碼。之後登錄只需要郵箱和驗證器中的 6 位數字。
2. 建立項目在「項目」頁建立一個項目。一個項目對應你的一個產品或網站，有自己的收款地址、API key 和 Webhook。
3. 登記收款地址在項目的「收款地址」頁連接你的錢包，簽名後發送一筆登記交易。收款地址記錄在鏈上，之後只有這個錢包能修改。這是唯一需要你的錢包支付 gas 的操作（一次，金額很少）；之後收款、分帳、歸集的 gas 都由 kokiwa 支付。可以把收款地址設為另一個地址，例如冷錢包。
4. 選擇收款代幣在「收款代幣」頁勾選要接受的穩定幣。
5. 建立 API key在「API key」頁建立，key 只顯示一次，請保存在服務端的環境變量裡，不要放進前端或 App。
6. 設置 Webhook在「回調通知」頁填寫你的 https 接收地址，保存好顯示的簽名密鑰，再點「發送測試事件」確認能收到。

選擇收款方式

兩種方式可以同時使用，按你的業務選擇。

支付單（適合訂單付款）

用戶下單時，你的服務端建立一張支付單，把返回的 checkout_url 給用戶打開。收銀台會讓用戶選擇用錢包付款，或者轉帳到這張單專屬的地址。

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

金額用代幣的最小單位、以字符串表示。上例的 USDT 在 BNB Chain 上是 18 位小數，25000000000000000000 就是 25 USDT。

充值地址（適合帳戶充值）

為你的每位用戶生成一個固定的充值地址，用戶隨時可以從交易所或錢包轉帳進來，地址永久不變。適合遊戲、交易平台這類需要「充值到帳戶餘額」的業務。

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

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

確認到帳

付款在鏈上最終確認後，kokiwa 向你的 Webhook 發送事件。請以 Webhook 為準入帳，不要依賴用戶跳回 success_url。

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

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

上線前檢查

• API key 只存在服務端，代碼倉庫和日誌裡都沒有。
• Webhook 校驗了簽名，重複收到同一事件不會重複入帳。
• 建立支付單時帶上了 Idempotency-Key，網絡重試不會產生兩張單。
• 收款地址是你自己掌控的錢包，助記詞已妥善備份。
• 綁定了 Telegram 到帳通知（「設置」頁），方便及時發現異常。