快速接入 | KukoPay

开发者文档

快速接入

在沙箱环境完成从创建订单到确认支付的完整流程。

沙箱不涉及真实资金。主动申请测试密钥后即可开始，无需等待资质审核。

注册并取得测试密钥

前往 KukoPay 商户后台注册。登录后进入开发者中心，主动申请一把以 kuko_test_ 开头的沙箱 API Key。

创建一笔订单

curl -X POST "https://web.kukopay.com/api/v1/orders" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: kuko_test_你的测试密钥" \
  -d '{
    "out_trade_no": "ORD_20260921_0001",
    "amount": 2990,
    "currency": "USD",
    "subject": "测试商品"
  }'

成功后返回 KukoPay 交易号和托管收银台地址：

{
  "code": 200,
  "message": "下单成功",
  "data": {
    "trade_no": "TRD_SB_9F3A2C7E...",
    "out_trade_no": "ORD_20260921_0001",
    "amount": 2990,
    "currency": "USD",
    "status": "pending",
    "mode": "sandbox",
    "checkout_url": "https://web.kukopay.com/checkout?trade_no=TRD_SB_9F3A...&token=..."
  }
}

把买家引导到收银台

将买家浏览器重定向到 checkout_url。这个 URL 含有短期访问令牌，不要写入公开日志、埋点参数或自行修改查询参数。

接收异步通知

支付成功后，KukoPay 会向下单时提供的 notify_url 推送 payment.succeeded 事件。请先完成Webhook 验签，再发货或开通服务。

主动查询订单

curl "https://web.kukopay.com/api/v1/orders/ORD_20260921_0001" \
  -H "X-Api-Key: kuko_test_你的测试密钥"

切换到正式环境

沙箱跑通后，需要完成商户资质审核并申请 kuko_live_ 密钥。接口地址和请求参数不变，只替换密钥；正式订单的 notify_url 必须是公网可访问的 HTTPS 地址。

⚠️

请求体里没有 mode 或 environment 开关。环境只由 API Key 前缀决定，避免测试代码误触发真实扣款。

文档首页商户入驻与审核

快速接入

在沙箱环境完成从创建订单到确认支付的完整流程。

curl -X POST "https://web.kukopay.com/api/v1/orders" \ -H "Content-Type: application/json" \ -H "X-Api-Key: kuko_test_你的测试密钥" \ -d '{ "out_trade_no": "ORD_20260921_0001", "amount": 2990, "currency": "USD", "subject": "测试商品" }'

{ "code": 200, "message": "下单成功", "data": { "trade_no": "TRD_SB_9F3A2C7E...", "out_trade_no": "ORD_20260921_0001", "amount": 2990, "currency": "USD", "status": "pending", "mode": "sandbox", "checkout_url": "https://web.kukopay.com/checkout?trade_no=TRD_SB_9F3A...&token=..." } }

切换到正式环境

⚠️

请求体里没有 mode 或 environment 开关。环境只由 API Key 前缀决定，避免测试代码误触发真实扣款。