跳轉到主要內容

支付接口為什麼用「分」傳金額:最小貨幣單位、整數與四捨五入

支付接口為什麼用分傳金額:什麼是最小貨幣單位、浮點數為什麼會算錯錢、如何安全地換算價格,以及 KukoPay 對金額的規則。

發佈於 約 3 分鐘閲讀

手繪插畫:一個 $29.90 的價格吊牌經箭頭變成整數 2990,旁邊一個被劃掉的浮點數 29.9,還有一個人正指着它
本文目錄
  1. 什麼是最小貨幣單位?
  2. 浮點數為什麼會把錢算錯
  3. KukoPay 如何校驗金額
  4. 如何安全地把價格換算成最小單位
  5. 你仍然會遇到小數的地方
  6. 總結

支付接口要求以「分」——更準確地説,以幣種的最小貨幣單位——傳入整數金額:2990 表示 $29.90。原因是錢必須精確,而大多數編程語言默認使用的小數並不精確。以最小單位傳整數,就把四捨五入誤差從最不能容忍它的地方徹底去掉了。

這篇文章説明什麼是最小貨幣單位、浮點數為什麼會把錢算錯、如何在代碼裏安全地換算價格,以及 KukoPay 對金額的具體規則。

什麼是最小貨幣單位?

最小貨幣單位是支付所使用的、一種貨幣的最小單位:

幣種最小單位2990 表示
USD美分(1/100 美元)$29.90
HKD仙(1/100 港元)HK$29.90
CNY分(1/100 元)¥29.90

KukoPay 支持的三種幣種都是兩位小數,所以以最小單位表示的金額總是價格 × 100。

浮點數為什麼會把錢算錯

大多數語言用二進制浮點數存儲小數,而二進制浮點數無法精確表示大多數十進制小數:

0.1 + 0.2            // 0.30000000000000004
19.99 * 100          // 1998.9999999999998
Math.floor(19.99 * 100)  // 1998 —— 少了一分錢

每次的誤差都很小,但錢會在成千上萬筆訂單中累積,差一分錢的合計和差一千塊的合計一樣會讓對賬失敗。整數個「分」沒有這種誤差:1999 + 1 就是 2000。

KukoPay 如何校驗金額

  • 只接受 JSON 整數。 訂單和收款鏈接的 amount 必須是以最小貨幣單位表示的正整數。字符串(即使是 "2990")、小數(29.9)或負數都會被拒絕並返回 400——不會替你四捨五入或轉換。
  • 一切都以最小單位表示。 API 中的手續費、淨額、退款、餘額和資金流水,都是以最小貨幣單位表示的整數。
  • 在安全範圍之內。 餘額和賬本數值都保持在 JavaScript 的安全整數範圍內,所以 JSON 數字在客戶端裏不會丟失精度。
  • 手續費只四捨五入一次。 手續費是以最小單位計算的 round(金額 × 費率 + 固定費),所以一筆 $29.90、費率 3.5% + $0.30 的銀行卡支付,手續費為 round(2990 × 0.035 + 30) = 135,即 $1.35。見 跨境收款手續費怎麼算。
curl -X POST "https://api.kukopay.com/v1/orders" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $KUKOPAY_API_KEY" \
  -d '{ "amount": 2990, "currency": "USD" }'

傳 "amount": 29.9 是接入第一天最常見的錯誤,API 日誌 一眼就能看出來。

如何安全地把價格換算成最小單位

最安全的做法是從一開始就沒有浮點數:在數據庫裏用整數「分」(或十進制類型)存儲價格,並對它們做運算。

如果必須轉換像 "19.99" 這樣的小數字符串,請不要經過浮點數:

from decimal import Decimal, ROUND_HALF_UP
 
def to_minor_units(price: str) -> int:
    return int((Decimal(price) * 100).quantize(Decimal("1"), rounding=ROUND_HALF_UP))
 
to_minor_units("19.99")   # 1999
// 按位解析 "19.99",而不是用浮點數相乘
function toMinorUnits(price) {
  const [whole, frac = ""] = price.split(".")
  return Number(whole) * 100 + Number((frac + "00").slice(0, 2))
}
toMinorUnits("19.99")  // 1999

只在最後展示時從整數格式化:用 (2990 / 100).toFixed(2) 生成顯示文本沒問題,但不要拿這個結果繼續做運算。

你仍然會遇到小數的地方

  • CSV 導出中的金額是兩位小數,方便在表格裏直接求和。自動化處理請使用 API 返回的整數,見 支付對賬。
  • 易支付協議的 money 是像 29.90 這樣的小數字符串。KukoPay 按位解析它,從不經過浮點數,見 易支付接入指南。
  • 帶匯率的插件,比如 Xboard 插件,會乘以匯率後四捨五入到最小單位的整數,見 Xboard 支付插件。

總結

  • 支付接口以「分」(幣種的最小貨幣單位)的整數傳金額,因為浮點數無法精確表示錢;
  • 在 KukoPay,amount 必須是正的 JSON 整數:2990 即 $29.90、HK$29.90 或 ¥29.90,字符串、小數和負數都會被拒絕;
  • 手續費、退款和餘額同樣是以最小單位表示的整數,手續費只四捨五入一次;
  • 用整數「分」或十進制類型存儲價格,不經過浮點數轉換字符串,只在最後展示時格式化。

在沙箱裏把它跑通

註冊商戶後即可申請測試密鑰,不需要等待資質審核。