UNIFIED API
一次接入，统一处理支付
使用稳定的 HTTP + JSON 接口创建订单、查询状态与发起退款。金额统一使用最小货币单位，接口契约清晰可预测。
HTTP + JSON
标准接口
无需绑定特定服务端 SDK
双环境
测试与正式隔离
密钥前缀决定交易环境
HMAC-SHA256
Webhook 验签
原始请求体验证与防重放
自动补偿
未决交易对账
支付与退款状态持续核验
Platform capabilities
从第一笔沙箱订单，到真实资金闭环
围绕商户最常用的支付链路提供必要能力，接口边界明确，状态变化可追踪，异常场景有补偿。
HOSTED CHECKOUT
托管收银台，减少前端负担
下单后获得带签名的 checkout_url，买家在 KukoPay 收银台完成付款，你的系统无需直接处理支付凭据。
SAFE ENVIRONMENTS
沙箱与正式环境天然隔离
kuko_test_ 与 kuko_live_ 密钥决定请求环境。测试代码不会因请求参数写错而意外触发真实交易。
RELIABLE EVENTS
可验证、可重试的异步通知
Webhook 使用 HMAC-SHA256 签名，失败后按退避策略重投，并提供投递记录与手动重发能力。
RECONCILIATION
支付与退款状态自动补偿
后台对账任务持续核对未决交易。即使买家关闭页面或渠道通知短暂丢失，也会再次确认最终结果。
FUNDS
钱包、账本与提现闭环
支付入账、退款冻结与扣账、提现审核都沉淀为可追踪的资金流水，帮助商户看清每一笔余额变化。
create-order.sh
curl -X POST https://web.kukopay.com/api/v1/orders \
-H "Content-Type: application/json" \
-H "X-Api-Key: kuko_test_mch_xxx" \
-d '{
"out_trade_no": "ORD_2026_001",
"amount": 2990,
"currency": "USD",
"subject": "Premium plan",
"notify_url": "https://shop.example.com/webhooks/kukopay"
}'
{
"code": 200,
"data": {
"trade_no": "TRD_SB_9F3A...",
"status": "pending",
"checkout_url": "https://web.kukopay.com/checkout?..."
}
}Integration flow
四步跑通支付闭环
浏览器回跳只负责用户体验，服务端异步通知才是可靠的履约依据。
01
注册商户并获取沙箱密钥
无需等待正式资质审核，即可在开发者中心申请测试密钥并开始联调。
02
服务端创建支付订单
传入商户订单号、金额与通知地址，获得 KukoPay 交易号和托管收银台链接。
03
买家完成付款
将买家重定向到 checkout_url，由 KukoPay 收银台承接支付流程与状态展示。
04
验签通知并履约
服务端验签 payment.succeeded 事件，以 event_id 去重后再发货或开通服务。
买家浏览器
访问 checkout_url
商户服务端
调用 /api/v1
KukoPay
订单与支付编排
异步通知
验签后履约
钱包与账本
记录资金变化
Security by design
把关键安全边界放在系统里
不依赖开发者“记得做对”，而是通过环境隔离、签名校验、密钥存储和账本约束降低误操作风险。
密钥安全
API 密钥以指纹定位、加密密文保存，并可在商户后台主动重置。
来源控制
支持商户级 API 限流与可选 IP 白名单，减少凭据滥用风险。
环境隔离
测试和正式使用独立密钥与独立账本，正式能力受入驻审核状态约束。
资金一致性
支付结算与退款使用幂等状态转换，所有余额变更写入对应流水。
FAQ
接入前常见问题
开发者 API 文档应该在哪里查看？
公开接入文档统一放在 kukopay.com/docs。登录、密钥申请、Webhook 投递记录和订单操作位于 web.kukopay.com 商户后台。
商户需要直接调用 router.kukopay.com 吗？
不需要。商户只对接 web.kukopay.com/api/v1。Router 是 KukoPay 内部的支付路由引擎，不属于公开商户 API。
如何避免重复下单或重复发货？
创建订单时使用唯一的 out_trade_no 作为幂等键；处理 Webhook 时使用 event_id 去重。网络超时后可以安全重试同一个订单号。
买家浏览器回跳可以作为支付成功依据吗？
不可以。浏览器可能被关闭或回跳可能被伪造。请以验签后的 payment.succeeded Webhook 为履约依据，并用订单查询接口补充核验。