> ## 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 Wrapping）

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

## 什么是美金包装？

美金包装（USD Wrapping）是 HaiPay 的跨币种支付能力：**商户以 USD 定价和结算，用户以本地币种（IDR、MYR、THB 等）支付**。

<Tip>
  **两个核心概念：**

  * **出示货币（Presentment）**：用户在收银台看到并支付的货币。美金包装下，出示货币为 USD。
  * **结算货币（Settlement）**：商户银行账户实际收到的货币。美金包装下，结算货币同样为 USD。

  支付通过底层支付通道完成，但对商户和用户而言，全程以 USD 计价。
</Tip>

### 业务价值

* **商户一站式美金入账、美金提现** — 无需持有多种本地币种账户
* **用户看到 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`   |

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

## 代收（Collection）

### 流程概览

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

### 接入步骤

<Card title="步骤 1：获取 USD 对应的 appId" icon="key">
  在商户管理后台「业务管理 → 支付产品配置」中，获取 **USD（美元）** 对应的 appId 和密钥对。

  <Warning>
    USD 的 appId 和本币的 appId 是独立的，不能混用。使用错误的 appId 会返回错误码 `4011`。
  </Warning>
</Card>

<Card title="步骤 2：选择目标地区的 USD 支付方式" icon="list">
  根据用户所在地区，选择对应的 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` |
</Card>

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

### 请求示例

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

```json theme={null}
{
  "appId": 1088,
  "orderId": "M233323000099",
  "amount": "50.00",
  "phone": "08230219312",
  "email": "user@example.com",
  "name": "John Doe",
  "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.example.com/checkout",
    "sign": "base64-encoded-haipay-signature"
  }
}
```

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

当涉及美金包装的汇率转换时，代收异步通知（webhook）会额外返回以下字段：

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

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

## 常见问题

<Accordion title="商户如何知道哪些支付方式支持美金包装？">
  每个地区的支付方式文档中会列出 USD 行的支付编码（通常带 `_USD` 后缀）。您也可以调用 [获取商户支付配置](/docs/zh/api/version2/MerchantPaymentConfig) 接口查询当前商户已启用的支付方式。
</Accordion>

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

<Accordion title="代收和代付是否都支持美金包装？">
  代收支持美金包装的支付方式更广。代付的美金包装支持范围相对较少，具体以各地区文档为准。
</Accordion>

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

<Accordion title="全球收银台（Global Cashier）是否支持美金包装？">
  支持。开通美金包装后，通过 `/global/cashier/collect/apply` 接口，`currency` 参数传 `USD` 即可。
</Accordion>

## 相关主题

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