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

# 美元计价支付（USD-Denominated Payments）

> 了解 HaiPay 美元计价支付产品——商户以 USD 定价和结算，用户以本地币种支付，HaiPay 自动完成汇率转换。

## 什么是美元计价支付？

美元计价支付（USD-Denominated Payments）是 HaiPay 的跨币种支付能力：**商户以 USD 定价和结算，用户以本地币种（IDR、MYR、THB 等）支付**。

> [!TIP]
>
> **两个核心概念：**
>
> * **出示货币（Presentment）**：用户在收银台看到并支付的货币。美元计价支付下，出示货币为 USD。
> * **结算货币（Settlement）**：商户银行账户实际收到的货币。美元计价支付下，结算货币同样为 USD。
>
> 支付通过底层支付通道完成，但对商户和用户而言，全程以 USD 计价。

### 业务价值

* **商户一站式美金入账、美金提现** — 无需持有多种本地币种账户
* **用户看到 USD 标价** — 降低跨境商户用户的接入门槛和心理换算成本

### 工作原理

```mermaid theme={null}
sequenceDiagram
    participant M as 商户
    participant H as HaiPay
    participant P as 支付处理
    participant U as 用户

    M->>H: 创建代收订单，默认USD
    H->>H: 查询实时汇率
    H->>P: 处理支付
    P->>U: 用户完成支付
    U-->>P: 支付完成
    P-->>H: 支付成功
    H-->>M: 订单成功，USD 余额入账
```

## 支持的地区和支付方式

美元计价支付覆盖多个地区，每个地区均提供对应的 USD bankCode。以下是参考支持地区 （以各地区文档为准）：

| 地区 | 本地币种 | 支持的支付方式 | USD bankCode 示例 |
| - | - | - | - |
| 印尼 | IDR | QR、电子钱包、VA 银行转账 | `ID_QRIS_USD`、`ID_DANA_USD`、`ID_BRI_USD` |
| 日本 | JPY | 电子钱包、银行转账 | `JP_AU_PAY_USD`、`JP_GMO_AOZORA_USD` |
| 马来西亚 | MYR | 银行转账 | `TNG_USD`、`BOOST_USD`、`FPX_USD` |
| 泰国 | THB | QR、电子钱包 | `TH_QR_USD`、`TH_TM_USD` |
| 越南 | VND | QR、银行转账 | `VN_QR_USD`、`VN_BANK_USD` |
| 韩国 | KRW | 电子钱包、银行转账 | `KAKAOPAY_USD`、`KR_BANK_USD` |
| 新加坡 | SGD | QR | `PAYNOW_USD` |
| 全球 | — | 信用卡（VISA/MC/JCB）、Google Pay、Apple Pay | `CREDIT_CARD`、`GOOGLE_PAY`、`APPLE_PAY` |

> 完整的支持列表请参阅各地区的 [支付方式文档](https://doc.haipay.net/docs/zh/api/version2/cashin_code_list.md)。

## 代收（Collection）

### 流程概览

```mermaid theme={null}
flowchart LR
    A[商户创建 USD 订单] --> B[HaiPay 查询汇率]
    B --> C[转换为本币金额]
    C --> D[用户支付本币]
    D --> E[支付回调成功]
    E --> F[商户 USD 余额入账]
```

### 接入步骤

> **步骤 1：获取 USD 对应的 appId**
>
> 在商户管理后台「业务管理 → 支付产品配置」中，获取 **USD（美元）** 对应的 appId 和密钥对。
>
> > [!WARNING]
> >
> > USD 的 appId 和本币的 appId 是独立的，不能混用。使用错误的 appId 会返回错误码 `4011`。

> **步骤 2：选择目标地区的 USD 支付方式**
>
> 根据用户所在地区，选择对应的 USD 支付编码（inBankCode）。USD 支付编码通常在本币编码基础上添加 `_USD` 后缀构成（如 `ID_DANA_USD`、`TH_TM_USD`），部分 bankCode 不含地区前缀（如 `TNG_USD`、`PAYNOW_USD`）：
>
> | 地区 | 本币编码 | USD 编码 |
> | - | - | - |
> | 印尼 | `DANA` | `ID_DANA_USD` |
> | 印尼 | `dynamic`（QRIS） | `ID_QRIS_USD` |
> | 日本 | `AU_PAY` | `JP_AU_PAY_USD` |
> | 日本 | `GMO_AOZORA` | `JP_GMO_AOZORA_USD` |

> **步骤 3：调用代收接口**
>
> 使用 USD 端点 `/usd/collect/apply` 创建代收订单。amount 以 **USD** 为单位传入。

### 请求示例

**URL：** `POST /usd/collect/apply`

```json theme={null}
{
  "appId": 1088,
  "orderId": "M233323000099",
  "amount": "50.00",
  "phone": "02012345678",
  "email": "james.anderson@gmail.com",
  "name": "James Anderson",
  "inBankCode": "ID_DANA_USD",
  "payType": "EWALLET",
  "partnerUserId": "149597870",
  "sign": "base64-encoded-rsa-signature"
}
```

**关键字段说明：**

| 参数 | 说明 |
| - | - |
| `appId` | USD 对应的业务 ID |
| `amount` | 交易金额，单位为 **USD**（精确到小数点后两位） |
| `inBankCode` | USD 支付编码（如 `ID_DANA_USD`） |
| `payType` | 支付类型，与 inBankCode 配套（如 `EWALLET`） |

### 响应示例

```json theme={null}
{
  "status": "1",
  "error": "00000000",
  "msg": "",
  "data": {
    "orderId": "M233323000099",
    "orderNo": "6023071013539074",
    "payUrl": "https://pay.haipay.asia/cashier/1L9zQS2",
    "sign": "base64-encoded-haipay-signature"
  }
}
```

### 异步通知中的汇率字段

当涉及美元计价支付的汇率转换时，代收异步通知（webhook）会额外返回以下字段：

| 参数 | 类型 | 说明 |
| - | - | - |
| `originalCurrency` | String | 订单原始币种（如 `IDR`），涉及汇率转换时有值 |
| `originalAmount` | String | 订单原始金额（如 `2825000`），涉及汇率转换时有值 |

> [!TIP]
>
> 通过对比 `amount`（USD 金额）和 `originalAmount`（本币金额），商户可以计算出实际使用的汇率。

## 常见问题

> **商户如何知道哪些支付方式支持美元计价支付？**
>
> 每个地区的支付方式文档中会列出 USD 行的支付编码（通常带 `_USD` 后缀）。您也可以调用 [获取商户支付配置](https://doc.haipay.net/docs/zh/api/version2/MerchantPaymentConfig.md) 接口查询当前商户已启用的支付方式。

> **汇率是下单时确定还是实时查询？**
>
> 汇率在下单时由 HaiPay 系统确定。商户可通过 `/common/quote/v1/exchange-rate` 接口在下单前预览汇率，但实际汇率以下单时系统返回为准。

> **代收和代付是否都支持美元计价支付？**
>
> 代收支持美元计价支付的支付方式更广。代付的美元计价支付支持范围相对较少，具体以各地区文档为准。

> **用户实际支付的本币金额怎么计算？**
>
> 用户实际支付的本币金额 = 商户传入的 USD 金额 × 下单时的汇率。商户可通过异步通知中的 `originalAmount` 字段获取用户实际支付的本币金额。

> **全球收银台（Global Cashier）是否支持美元计价支付？**
>
> 支持。开通美元计价支付后，通过 `/global/cashier/collect/apply` 接口，`currency` 参数传 `USD` 即可。

## 相关主题

* [HaiPay 各地区支付方式](https://doc.haipay.net/docs/zh/api/version2/cashin_code_list.md)
* [HaiPay 公共接口](https://doc.haipay.net/docs/zh/guide/api_description_guide.md)
* [HaiPay 配置与签名指南](https://doc.haipay.net/docs/zh/guide/config_settings_and_signature_rules_guide.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.