美金包装（USD Wrapping）

什么是美金包装？

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

两个核心概念：

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

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

业务价值

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

完整的支持列表请参阅各地区的支付方式文档。

代收（Collection）

流程概览

接入步骤

步骤 1：获取 USD 对应的 appId

在商户管理后台「业务管理 → 支付产品配置」中，获取 USD（美元） 对应的 appId 和密钥对。

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

{
  "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`）

响应示例

{
  "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`），涉及汇率转换时有值

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

常见问题

商户如何知道哪些支付方式支持美金包装？

每个地区的支付方式文档中会列出 USD 行的支付编码（通常带 _USD 后缀）。您也可以调用获取商户支付配置接口查询当前商户已启用的支付方式。

汇率是下单时确定还是实时查询？

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

代收和代付是否都支持美金包装？

代收支持美金包装的支付方式更广。代付的美金包装支持范围相对较少，具体以各地区文档为准。

用户实际支付的本币金额怎么计算？

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

全球收银台（Global Cashier）是否支持美金包装？

支持。开通美金包装后，通过 /global/cashier/collect/apply 接口，currency 参数传 USD 即可。

快速开始

商户指南

公共支付

全球支付

统一支付

测试与上线

附录

商户QA

美金包装（USD Wrapping）

什么是美金包装？

业务价值

工作原理

支持的地区和支付方式

代收（Collection）

流程概览

接入步骤

步骤 1：获取 USD 对应的 appId

步骤 2：选择目标地区的 USD 支付方式

步骤 3：调用代收接口

请求示例

响应示例

异步通知中的汇率字段

常见问题

相关主题

​什么是美金包装？

​业务价值

​工作原理

​支持的地区和支付方式

​代收（Collection）

​流程概览

​接入步骤

步骤 1：获取 USD 对应的 appId

步骤 2：选择目标地区的 USD 支付方式

步骤 3：调用代收接口

​请求示例

​响应示例

​异步通知中的汇率字段

​常见问题

​相关主题

什么是美金包装？

业务价值

工作原理

支持的地区和支付方式

代收（Collection）

流程概览

接入步骤

请求示例

响应示例

异步通知中的汇率字段

常见问题

相关主题