在订单、退款和收款链接上挂自己的业务标识。
订单、退款和收款链接都支持 metadata：一组你自己定义的键值对，随对象一起存储、一起返回、一起出现在 Webhook 里。
用它把 KukoPay 的对象和你自己系统里的记录关联起来，而不是把多个 id 编码进 out_trade_no 再解析出来——out_trade_no 是幂等键，不该兼任这个职责。
curl -X POST "https://web.kukopay.com/api/v1/orders" \
-H "X-Api-Key: kuko_live_你的密钥" \
-H "Content-Type: application/json" \
-d '{
"out_trade_no": "ORD_20260921_0001",
"amount": 2990,
"metadata": {
"customer_id": "cus_42",
"order_source": "shopify",
"sales_rep": "alice"
}
}'| 项目 | 限制 |
|---|---|
| 键数量 | 最多 50 个 |
| 键长度 | 1 ~ 40 字符 |
| 值长度 | 不超过 500 字符 |
| 值类型 | 必须是字符串 |
只允许字符串是有意的限制。允许嵌套结构，metadata 就会变成一份我们必须永远兼容的隐式 schema——需要结构化数据时，请在自己的系统里存，这里只放一个指向它的 id。
curl -G "https://web.kukopay.com/api/v1/orders" \
-H "X-Api-Key: kuko_live_你的密钥" \
-d "metadata[customer_id]=cus_42"可以传多个，含义是"同时满足"。
POST /api/v1/orders/{trade_no}
POST /api/v1/refunds/{refund_no}
POST /api/v1/payment_links/{link_id}这些接口目前只支持更新 metadata——金额、币种和环境是已经告知上游渠道的事实，允许在这里改会让平台记录与真实资金脱节。
更新是增量合并，不是整体替换：
# 只写入 shipped_at，其它键保持不变
curl -X POST "https://web.kukopay.com/api/v1/orders/TRD_9F3A2C7E" \
-H "X-Api-Key: kuko_live_你的密钥" \
-H "Content-Type: application/json" \
-d '{ "metadata": { "shipped_at": "2026-09-22" } }'
# 值传 null 删除单个键
curl -X POST "https://web.kukopay.com/api/v1/orders/TRD_9F3A2C7E" \
-H "X-Api-Key: kuko_live_你的密钥" \
-H "Content-Type: application/json" \
-d '{ "metadata": { "sales_rep": null } }'整个 metadata 字段传 null 表示清空。
合并而不是替换，是为了让只认识自己那个键的客户端不会把别的系统写入的键洗掉。