所有公開 API 都通過 X-Api-Key 請求頭認證：
curl "https://api.kukopay.com/v1/balance" \
-H "X-Api-Key: kuko_test_mch_xxxxx_a1b2c3d4"API Key 等同於賬戶的服務端操作權限。不要把它寫進瀏覽器 JavaScript、移動應用或公開倉庫。
應用
一個商戶賬戶下可以創建多個應用，每個應用對應一套獨立的接入——例如官網商城、移動 App 和第二個品牌各用一個。主體資質、餘額、費率、限額和提現屬於賬戶，所有應用共用；屬於應用的是：
- API Key（每個環境可以有多把）
- 回調簽名密鑰（簽名下單時自帶
notify_url的回調） - Webhook 端點
- IP 白名單
- 易支付商戶 ID
- 收銀台的展示名稱、品牌色和 Logo（留空則沿用賬戶設置）
一把密鑰只能訪問它所在應用的訂單、退款、拒付、收款鏈接、事件和 Webhook 端點；查詢其他應用的對象返回 404。out_trade_no、out_refund_no 和 Idempotency-Key 都在應用內唯一，兩個應用使用同一個訂單號互不衝突。餘額和資金流水屬於賬戶，任何應用的密鑰都可以讀取。
每個賬戶自帶一個默認應用：後台創建的測試訂單和未指定應用的收款鏈接歸它，它不能被停用。其他應用可以停用，停用後不能再創建訂單（API、易支付和收款鏈接都會返回 403 app_disabled），已有訂單的查詢、退款與通知不受影響。
商戶後台左上角是應用切換器（和 Stripe 切換賬戶的方式一樣），也可以在那裏創建應用；改名、停用在「設置 → 應用管理」，每個賬戶最多 20 個。切換後，概覽的交易數據、訂單與退款、拒付、收款鏈接，以及「開發者」下的 API 密鑰、Webhook、事件、調用日誌、易支付接入都只顯示當前應用；錢包、結算與提現和「設置」下的其他頁面屬於賬戶，所有應用共用。應用的收銀台名稱和 Logo 在「設置 → 商戶名稱與品牌」中設置，默認打開的就是當前應用。
兩種密鑰
| 前綴 | 環境 | 説明 |
|---|---|---|
kuko_test_ | 沙箱 | 隨時可以簽發，不產生真實資金 |
kuko_live_ | 正式 | 資質審核通過後簽發；未開通時返回 403 merchant_not_approved |
沙箱與正式環境的訂單、餘額和流水完全隔離。環境由密鑰決定，不接受請求體參數切換。
每個應用在每個環境下最多同時持有 5 把長期有效的密鑰，可以按服務器或用途分開簽發並命名。
正式環境的 API Key 和簽名密鑰只在簽發或輪換時完整顯示一次，之後後台只顯示前綴和末四位。請在簽發時立即保存到你的服務端配置；遺失後只能輪換。沙箱密鑰可以隨時在後台查看。正式密鑰的簽發、輪換和吊銷都會郵件通知賬戶的所有者和管理員。
商戶後台同樣按環境分開，並且環境寫在網址裏：/dashboard/... 是正式環境，/test/dashboard/... 是沙箱。把後台鏈接發給同事時，對方看到的就是你所在的環境；資質審核通過前，正式環境的鏈接會自動跳到對應的沙箱頁面。
IP 白名單
每個應用可以選配來源 IP 白名單，同時約束該應用的 API Key 和易支付商戶 ID。支持單個 IPv4、IPv4 CIDR 與 IPv6 精確地址，多個條目使用逗號或空格分隔；保存時會校驗格式。配置後立即生效，白名單外請求返回 403 ip_not_allowed。
雲函數或彈性容器的出口 IP 可能變化，未配置固定出口時不建議啓用。
調用頻率
- 寫接口（下單、退款）：每個商戶賬戶每分鐘 120 次。
- 讀接口（查詢類）：每個商戶賬戶每分鐘 600 次。
- 配額按賬戶計算，同一賬戶下的所有應用共用。
- 超出限制返回
429 rate_limited，並通過Retry-After響應頭告知等待秒數。
輪換與吊銷
- 輪換：立即簽發一把新密鑰，舊密鑰在你選擇的保留期內（立即、1 小時、24 小時、72 小時或 7 天）繼續可用。先部署新密鑰，再讓舊密鑰到期，切換過程不會中斷。
- 吊銷：密鑰立即失效，仍在使用它的請求返回
401 invalid_api_key。懷疑泄露時直接吊銷。
後台會顯示每把密鑰最近一次被使用的時間；API 請求日誌也記錄了調用使用的 key_id，可以據此確認舊密鑰已經沒有流量。