支付 metadata 怎麼用？把你自己的業務標識掛到訂單、退款和收款鏈接上

支付 metadata 是你掛在支付對象（訂單、退款、收款鏈接）上的一組鍵值對，讓它帶上你自己的業務標識：你的客戶 id、購物車 id、銷售渠道、營銷活動。支付服務商把它和對象一起存儲，每次查詢都會返回，每個 Webhook 裏也都有它，「這筆付款對應我哪條記錄」就變成了一個直接讀取的字段，而不是一張需要你自己維護的映射表。

這篇文章説明支付 metadata 裏該放什麼（以及不該放什麼）、有哪些限制、如何按 metadata 查詢訂單，以及如何修改它而不覆蓋其他系統寫入的內容。

支付 metadata 有什麼用？

• 把付款和你的記錄關聯起來。 payment.succeeded Webhook 帶着 metadata.customer_id 到達，你的處理代碼不用查表就知道該給誰的賬戶入賬。
• 報表與對賬。 給訂單打上銷售渠道、營銷活動或地區的標籤，再按它篩選和導出，見 支付對賬怎麼做。
• 客服。 客服查看一筆訂單時，能直接看到它對應的購物車 id 或工單號。
• 多個系統共用一筆訂單。 你的商城、CRM 和發貨服務，可以各自在同一筆訂單上保留自己的鍵。

metadata 和 out_trade_no

不要把好幾個 id 編碼進 out_trade_no，再解析出來。out_trade_no 是你的訂單號，也是防止訂單被重複創建的冪等鍵，它應該只做這一件事。讓訂單號保持簡單，其他信息都放進 metadata：

curl -X POST "https://api.kukopay.com/v1/orders" \
  -H "X-Api-Key: $KUKOPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "out_trade_no": "ORD_20261105_0001",
    "amount": 2990,
    "currency": "USD",
    "metadata": {
      "customer_id": "cus_42",
      "order_source": "shopify",
      "campaign": "winter-2026"
    }
  }'

支付 metadata 的限制

只允許字符串是有意的限制。允許嵌套對象，metadata 就會變成一份所有讀取它的系統都必須永遠遵守的隱式 schema。需要結構化數據時，把它存在你自己的數據庫裏，metadata 裏只放指向它的那個 id。數字也要以字符串寫入："42"，而不是 42。

哪些對象帶有 metadata？

• 訂單：創建時設置，查詢、列表和每一個訂單 Webhook 都會返回。
• 退款：給退款標上它對應的退貨單或工單。
• 收款鏈接：鏈接的 metadata 會被複制到鏈接生成的每一筆訂單上，平台還會加上 kukopay_payment_link（鏈接 id），所以每一筆付款都能追溯到它的鏈接和活動。見 收款鏈接是什麼。

Webhook 發送的對象和查詢接口返回的完全一樣，包括 metadata，所以一套解析代碼就能同時處理兩者。

如何按 metadata 查詢訂單

curl -G "https://api.kukopay.com/v1/orders" \
  -H "X-Api-Key: $KUKOPAY_API_KEY" \
  -d "metadata[customer_id]=cus_42"

傳入多個 metadata[...] 篩選條件時，訂單必須同時滿足所有條件。它可以和創建時間等常用列表篩選條件組合，也可以加上 format=csv，導出某個客戶或某次活動的訂單。

如何修改 metadata 而不覆蓋其他系統的鍵

訂單、退款和收款鏈接創建後，可以修改它們的 metadata：

POST /v1/orders/{trade_no}
POST /v1/refunds/{refund_no}
POST /v1/payment_links/{link_id}

對訂單和退款來説，這些接口只能修改 metadata：金額、幣種和環境是已經告知支付通道的事實，允許在這裏修改會讓平台記錄與真實資金脱節。

更新是合併，而不是整體替換：

# 寫入 shipped_at，其他鍵保持不變
curl -X POST "https://api.kukopay.com/v1/orders/TRD_9F3A2C7E" \
  -H "X-Api-Key: $KUKOPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "shipped_at": "2026-11-06" } }'
 
# 值傳 null 刪除單個鍵
curl -X POST "https://api.kukopay.com/v1/orders/TRD_9F3A2C7E" \
  -H "X-Api-Key: $KUKOPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "sales_rep": null } }'

整個 metadata 字段傳 null 表示清空。合併讓多個系統可以安全地共用一筆訂單：只認識自己 shipped_at 這個鍵的發貨服務，不會把你的商城寫入的 customer_id 洗掉。

使用支付 metadata 的最佳實踐

• 存 id，不存數據。 寫 customer_id: "cus_42"，而不是客戶的姓名、地址和購買記錄。
• 不要放密鑰和個人敏感信息。 metadata 會返回給所有使用你密鑰的調用方，也會出現在每一個 Webhook 裏。不要放密碼、令牌、卡號、證件號或其他敏感個人信息。
• 統一鍵名。 選一種命名規範（order_id，而不是有時寫 orderId）並寫成文檔；可以考慮按系統加前綴（crm_contact_id、wms_shipment_id）。
• 把 kukopay_ 前綴留給平台，平台會用它寫入 kukopay_payment_link 這類鍵。
• 不要只憑 metadata 做關鍵判斷。 它由你自己的代碼寫入，之後也可以被修改。判斷訂單是否已付款，要看訂單的 status 和驗簽後的 Webhook，而不是 metadata 裏的某個標記，見 return_url 和 notify_url 的區別。
• 讓 Webhook 處理代碼容忍缺失的鍵。 在你新增某個鍵之前創建的訂單，不會有這個鍵。

總結

• 支付 metadata 把你自己的字符串鍵值對掛到訂單、退款和收款鏈接上，每次查詢和每個 Webhook 都會返回；
• 最多 50 個鍵，鍵最長 40 個字符，值最長 500 個字符，只能是字符串，存 id 而不是結構；
• 讓 out_trade_no 只做訂單號和冪等鍵，其他 id 放進 metadata；
• 用 metadata[key]=value 篩選訂單，多個條件需要同時滿足；
• 更新是合併，null 刪除單個鍵，共用一筆訂單的多個系統不會互相抹掉彼此的鍵；
• 不要放密鑰和個人敏感信息，也永遠不要憑 metadata 判斷訂單是否已付款。