# 重要说明

> 现有对接自身无法察觉的 HansaPay 行为。接入前请先阅读。

本文档中的请求与响应格式没有变化，现有对接无需修改代码即可继续使用。以下行为是现有对接自身无法察觉的：

- **金额可能向下取整到价位。** Apple Pay、Google Pay 及部分卡通道只按固定价位收款。HansaPay 会把金额向下取整到最接近的价位（最多 5%）：`trans_amount` 为实收金额，`requested_amount` 为你传入的金额。见 [钱包支付直连](https://www.hansapay.io/docs/zh/payments#direct-wallet-payment)。请按 `order_no` / `merchant_order_no` 对账，不要按金额对账。
- **通知返回实收的美元金额。** 对于其他币种的订单，API 响应返回你传入的币种与金额，而 `payment.updated` 与 `refund.updated` 通知返回实收或实退的美元金额。
- **其他币种的支付含汇率加点。** 以美元以外币种发起的银行卡或钱包支付，按市场汇率加汇率加点（默认 1.5%，另有约定的除外）以美元扣款。你的余额入账与手续费均按你的价格以市场汇率换算后的金额计算。加点不属于你，因此 `payment.updated` 中的美元金额会高于余额在扣除手续费前的入账金额。退款或拒付只扣减属于你的部分。
- **支持的币种。** 支付与支付链接可使用以下币种定价：`USD`, `EUR`, `GBP`, `CAD`, `AUD`, `NZD`, `CHF`, `JPY`, `HKD`, `SGD`, `PLN`, `SEK`, `NOK`, `AED`, `SAR`, `OMR`。其他币种会以 `code=422` 拒绝，错误信息会列出支持的币种。以美元以外币种定价的支付按当日市场汇率换算后以美元扣款。若暂时没有可用的汇率，支付会以 `code=422` 拒绝，信息为 "exchange rate is temporarily unavailable"：请稍后重试或改用美元。
- **拒付不发通知。** 拒付一经记录即从你的余额中冻结：属于你的金额部分与拒付手续费将无法提现，并在其结算日从冻结中扣除。若余额不足，余额会变为负数，由你之后的入账优先抵扣。拒付仅在商户后台展示。不发送通知，支付状态保持 `SUCCESS`。
- **卡类退款为全额退款且需审核。** 卡、Apple Pay 与 Google Pay 支付只能退款一次，且须全额。退款初始为 `PENDING`，审核后才完成。见 [创建退款](https://www.hansapay.io/docs/zh/refunds#create-refund)。
- **已停用的账户不能收款。** `/payments/create` 与 `/payments/checkout` 返回 `code=1001`。查询、退款与结算不受影响。
- **下单有频率限制。** 每个商户账户通过 `/payments/create` 与 `/payments/checkout` 合计每分钟最多创建 600 笔付款（另有约定的除外）。超出时请求以 HTTP `429` 和 `code=4001`（`tooManyRequests`）拒绝，且不会创建订单：请稍候以相同的 `merchant_order_no` 重试。查询、退款与代付不计入。
- **`PAYPAL` 与 `PIX` 目前不可用。** 它们能通过参数校验，随后以 `code=3003` 拒绝。**代付目前仅支持 `CASH_APP`**：在您的账户开通代付后，以 `USD` 付至 Cash App `$cashtag`。其他代付方式返回 `code=5007`。见第 8 节。
- **通知必须以 `success` 应答。** 其他任何应答都会重试，约 90 分钟内最多 9 次。同一通知可能到达多次。见 [商户回调响应要求](https://www.hansapay.io/docs/zh/webhooks#merchant-notification-response-requirement)。
- **结算按美国工作日计算。** `T+N` 从订单创建当天起按周一至周五计算，不含元旦、阵亡将士纪念日、独立日、劳动节、感恩节和圣诞节。部分支付通道仅在特定工作日放款：经这类通道的付款在其 `T+N` 日期当天或之后的第一个放款日结算（例如随后的周五）。每笔订单的结算日期会随订单一起显示。
