收款鏈接

POST /v1/payment_links
GET  /v1/payment_links
GET  /v1/payment_links/{link_id}
POST /v1/payment_links/{link_id}

統一下單每次都要服務端調一次接口。收款鏈接把同一個收銀台放到一個固定地址背後：把 URL 發給買家，他打開就能付，你什麼都不用寫。

創建

curl -X POST "https://api.kukopay.com/v1/payment_links" \
  -H "X-Api-Key: kuko_live_你的密鑰" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 9900,
    "currency": "USD",
    "subject": "Pro 年度訂閲",
    "max_uses": 100,
    "expires_at": "2026-12-31T23:59:59Z",
    "metadata": { "campaign": "autumn-2026" }
  }'

響應

{
  "object": "payment_link",
  "link_id": "plink_7c2a41e9d8b30f56",
  "merchant_id": "mch_a1b2c3d4e5",
  "url": "https://checkout.kukopay.com/pay/plink_7c2a41e9d8b30f56",
  "mode": "live",
  "amount": 9900,
  "currency": "USD",
  "subject": "Pro 年度訂閲",
  "status": "active",
  "max_uses": 100,
  "used_count": 0,
  "paid_count": 0,
  "expires_at": "2026-12-31T23:59:59.000Z",
  "metadata": { "campaign": "autumn-2026" },
  "created_at": "2026-09-21T10:14:02.551Z"
}

把 url 發給買家即可。

收銀台語言

鏈接末尾追加 ?locale=（en、zh、ja、ko、de）即可指定收銀台語言，例如 https://checkout.kukopay.com/pay/plink_7c2a41e9d8b30f56?locale=ja。平台會把它原樣帶到收銀台，規則與統一下單的 checkout_url 相同：不帶或值不受支持時為英文，不跟隨買家瀏覽器。同一個鏈接可以按受眾分別發出不同語言的版本，計數和訂單不受影響。控制台的收款鏈接頁面可以選擇語言後直接複製。

每次訪問會發生什麼

買家打開鏈接時，平台生成一筆新訂單並跳轉到收銀台（同一瀏覽器的例外見下文）。因此一個鏈接可以收很多筆款，每一筆都是獨立訂單，有自己的 trade_no，走和 API 下單完全相同的結算、退款與通知流程。

同一個瀏覽器再次打開同一個鏈接時，如果上次生成的訂單還沒付款、也沒關閉，並且收銀台鏈接還有 10 分鐘以上的有效期，買家會回到那筆訂單，不會再生成新訂單。這樣買家在錢包或 3DS 頁面中途返回、重新打開鏈接時，不會出現兩筆訂單都付款成功的情況：回到原訂單後，收銀台會先取消那筆沒完成的支付，再讓買家重新選擇支付方式。訂單付款或關閉之後再打開，就是一筆新訂單。這個判斷靠的是鏈接路徑下的一個 Cookie，換瀏覽器或清除 Cookie 後會生成新訂單。

訂單的 out_trade_no 形如 plink_7c2a41e9d8b30f56_3（鏈接 id + 第幾次使用），metadata 裏會帶上 kukopay_payment_link，方便反查。

used_count 統計的是生成過多少筆訂單（每次訪問一筆），paid_count 統計的是成功收款多少筆。買家打開但沒付，只有 used_count 會增加。

只打開、沒有嘗試付款的訪問也是訂單，GET /v1/orders 照常返回它們，沒人付款的會在收銀台鏈接到期後變為 expired。控制台的訂單列表默認不顯示這類訂單，勾選「含收款鏈接未付款的訪問」即可看到；買家只要提交過一次支付（哪怕失敗），訂單就會出現在列表中。

收款筆數上限

max_uses 限制的是成功支付的筆數，不是打開次數，與 Stripe Payment Links 的「限制付款次數」相同。設為 1 的鏈接，買家打開後沒付款離開，不會佔掉這唯一的名額。

• 名額未滿時，任何人都可以打開鏈接並付款；同一筆訂單裏支付失敗後換支付方式重試，不會多佔名額。
• paid_count 達到 max_uses 後，鏈接不再生成新訂單，買家看到「已收滿」的説明頁；已經打開的收銀台也不再提供支付表單，該訂單關閉為 expired（正在進行中的 3DS 或錢包支付會先被取消）。
• 多位買家同時付款、搶最後一個名額時，先入賬的一筆計入，其餘的全額原路退回買家：該訂單關閉為 expired，並發送 payment.duplicate_refunded。退回的錢從未計入你的錢包，不影響餘額，也不收手續費。

退款不會把名額還回來：已經付款、後來退款的訂單仍計入 paid_count。需要更多名額時，把 max_uses 調大即可。

更新

curl -X POST "https://api.kukopay.com/v1/payment_links/plink_7c2a41e9d8b30f56" \
  -H "X-Api-Key: kuko_live_你的密鑰" \
  -H "Content-Type: application/json" \
  -d '{ "status": "inactive" }'

可以改 status、subject、max_uses、expires_at 和 metadata。

鏈接不可用時

買家會看到一個説明頁面，不會看到報錯。四種情況：鏈接不存在、已停用、已過期、收款筆數已滿。

公開地址天然會被反覆打開，所以按訪問者做了每分鐘 20 次的頻率限制。正常買家刷新或多開標籤頁不會觸發。