支付接口為什麼用「分」傳金額:最小貨幣單位、整數與四捨五入
支付接口為什麼用分傳金額:什麼是最小貨幣單位、浮點數為什麼會算錯錢、如何安全地換算價格,以及 KukoPay 對金額的規則。
支付接口要求以「分」——更準確地説,以幣種的最小貨幣單位——傳入整數金額: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,字符串、小數和負數都會被拒絕; - 手續費、退款和餘額同樣是以最小單位表示的整數,手續費只四捨五入一次;
- 用整數「分」或十進制類型存儲價格,不經過浮點數轉換字符串,只在最後展示時格式化。
在沙箱裏把它跑通
註冊商戶後即可申請測試密鑰,不需要等待資質審核。