> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 金额与币种

> Waffo 金额格式规范与多币种支付说明。

## 金额格式

Waffo 的金额统一使用 **String 类型**，不要使用 Number / float / double。

```
✅ "100.00"
✅ "0.99"
✅ "10000"     （JPY 等零小数币种）

❌ 100.00      （Number 类型，浮点精度问题）
❌ 100         （Number 类型）
```

<Note>
  使用 String 而非 Number 是为了避免浮点精度问题。`0.1 + 0.2 = 0.30000000000000004` 在金融场景中不可接受。
</Note>

## 金额小数位规则

不同币种对小数位的要求不同。

<Warning>
  传错小数位会返回参数错误（A0003）。
</Warning>

### 2 位小数的币种（大部分）

以下币种金额必须精确到 2 位小数：

```
"100.00"  ✅
"9.99"    ✅
"100"     ❌（缺少小数位）
"100.0"   ❌（只有 1 位小数）
```

| 地区 | 币种                                                                                                                     |
| -- | ---------------------------------------------------------------------------------------------------------------------- |
| 亚太 | `PHP`（菲律宾比索）、`MYR`（马来西亚林吉特）、`THB`（泰铢）、`KHR`（柬埔寨瑞尔）、`SGD`（新加坡元）、`HKD`（港币）、`MOP`（澳门元）、`CNY`（人民币）、`AUD`（澳元）、`MNT`（蒙古图格里克） |
| 美洲 | `USD`（美元）、`BRL`（巴西雷亚尔）、`MXN`（墨西哥比索）、`PEN`（秘鲁索尔）、`CAD`（加元）、`AWG`（阿鲁巴弗罗林）                                                |
| 欧非 | `EUR`（欧元）、`GBP`（英镑）、`RUB`（俄罗斯卢布）、`TRY`（土耳其里拉）、`PLN`（波兰兹罗提）、`SEK`（瑞典克朗）、`NGN`（尼日利亚奈拉）                                   |
| 加密 | `USDC`、`USDT`                                                                                                          |

### 0 位小数的币种

以下币种的金额精度为 0 位小数。对于 `VND`，小数位可以省略，也可以保留为全 0；小数部分只要包含非 0 数字，就无法通过金额校验。

```text theme={null}
"10000"    ✅
"10000.00" ✅（小数部分全为 0）
"10000.01" ❌（包含非 0 小数）
```

| 币种    | 名称   |
| ----- | ---- |
| `JPY` | 日元   |
| `KRW` | 韩元   |
| `VND` | 越南盾  |
| `CLP` | 智利比索 |

### 特殊币种（同币种 0 位，跨币种 2 位）

以下币种在**同币种下单**时不允许有小数，但在**跨币种下单**时允许 2 位小数：

| 币种    | 名称     | 同币种下单                        | 跨币种下单          |
| ----- | ------ | ---------------------------- | -------------- |
| `IDR` | 印尼盾    | `"10000"` ✅ / `"10000.50"` ❌ | `"10000.50"` ✅ |
| `COP` | 哥伦比亚比索 | `"5000"` ✅ / `"5000.00"` ❌   | `"5000.00"` ✅  |
| `KES` | 肯尼亚先令  | `"100"` ✅ / `"100.50"` ❌     | `"100.50"` ✅   |
| `TWD` | 新台币    | `"300"` ✅ / `"300.00"` ❌     | `"300.00"` ✅   |

## 什么是同币种 / 跨币种下单

| 场景      | 示例                       | 说明                        |
| ------- | ------------------------ | ------------------------- |
| **同币种** | 商品定价 IDR，用户用 DANA（IDR）支付 | `orderCurrency` 与用户支付币种一致 |
| **跨币种** | 商品定价 USD，用户用 DANA（IDR）支付 | `orderCurrency` 与用户支付币种不同 |

### 跨币种下单传参

```json theme={null}
{
  "orderCurrency": "USD",
  "orderAmount": "10.00"
}
```

跨币种场景下，`userCurrency` 可不传。但如果 `payMethodType` 或 `payMethodName` 未完全指定，需要额外传 `payMethodCountry` 告诉 Waffo 用户在哪个国家。

Waffo 自动处理汇率换算，用户在收银台看到的是当地货币金额。

## 完整币种列表

| 币种代码   | 名称       | 小数位   | 备注                |
| ------ | -------- | ----- | ----------------- |
| `IDR`  | 印尼盾      | 0 / 2 | 同币种 0 位，跨币种 2 位   |
| `USD`  | 美元       | 2     |                   |
| `PHP`  | 菲律宾比索    | 2     |                   |
| `BRL`  | 巴西雷亚尔    | 2     |                   |
| `MXN`  | 墨西哥比索    | 2     |                   |
| `MYR`  | 马来西亚林吉特  | 2     |                   |
| `THB`  | 泰铢       | 2     |                   |
| `CAD`  | 加元       | 2     |                   |
| `EUR`  | 欧元       | 2     |                   |
| `AUD`  | 澳元       | 2     |                   |
| `GBP`  | 英镑       | 2     |                   |
| `VND`  | 越南盾      | 0     | 可省略小数位，或使用全 0 小数位 |
| `CLP`  | 智利比索     | 0     | 无小数               |
| `COP`  | 哥伦比亚比索   | 0 / 2 | 同币种 0 位，跨币种 2 位   |
| `PEN`  | 秘鲁索尔     | 2     |                   |
| `RUB`  | 俄罗斯卢布    | 2     |                   |
| `KES`  | 肯尼亚先令    | 0 / 2 | 同币种 0 位，跨币种 2 位   |
| `NGN`  | 尼日利亚奈拉   | 2     |                   |
| `TWD`  | 新台币      | 0 / 2 | 同币种 0 位，跨币种 2 位   |
| `HKD`  | 港币       | 2     |                   |
| `JPY`  | 日元       | 0     | 无小数               |
| `KRW`  | 韩元       | 0     | 无小数               |
| `MOP`  | 澳门元      | 2     |                   |
| `SGD`  | 新加坡元     | 2     |                   |
| `CNY`  | 人民币      | 2     |                   |
| `PLN`  | 波兰兹罗提    | 2     |                   |
| `TRY`  | 土耳其里拉    | 2     |                   |
| `KHR`  | 柬埔寨瑞尔    | 2     |                   |
| `SEK`  | 瑞典克朗     | 2     |                   |
| `AWG`  | 阿鲁巴弗罗林   | 2     |                   |
| `MNT`  | 蒙古图格里克   | 2     |                   |
| `USDC` | USD Coin | 2     | 加密货币              |
| `USDT` | Tether   | 2     | 加密货币              |