> ## 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.

# 常见问题（FAQ）

> 关于 Waffo 集成、支付与安全的常见问题与解答。

## 集成

<AccordionGroup>
  <Accordion title="推荐使用哪种集成方式？">
    如果你希望快速上线，推荐**收银台集成**（Checkout），无需处理敏感卡信息，集成工作量最小。
  </Accordion>

  <Accordion title="ONE_TIME_PAYMENT 和 DIRECT_PAYMENT 有什么区别？">
    `DIRECT_PAYMENT` 是早期产品，目前基本不再使用。新商户直接接入 `ONE_TIME_PAYMENT` 即可。

    两者在系统对接层面没有差别，差异体现在业务关系上：

    * **ONE\_TIME\_PAYMENT**：Waffo 作为 PSP，提供完整收单服务（信息流 + 资金结算）
    * **DIRECT\_PAYMENT**：Waffo 作为 ISV/PG，仅提供系统对接能力（不碰资金）
  </Accordion>

  <Accordion title="金额为什么要用 String 类型？">
    避免浮点精度问题。例如 `0.1 + 0.2 = 0.30000000000000004`，在金融场景中这是不可接受的。
  </Accordion>

  <Accordion title="币种精度有什么要求？">
    * **同币种下单**：大部分币种精度需符合 ISO 4217（2 位小数），但 `IDR`、`COP`、`KES`、`TWD` **不允许有小数**
    * **跨币种下单**：所有币种金额精度符合 ISO 4217 即可，无例外
  </Accordion>

  <Accordion title="如何在本地测试 Webhook？">
    使用 cloudflared 或 ngrok 等隧道工具将本地端口暴露为公网 URL。
  </Accordion>
</AccordionGroup>

## 传参

<AccordionGroup>
  <Accordion title="payMethodType 和 payMethodName 怎么传？">
    * **不传**：用户到 Waffo 收银台选择支付方式
    * **卡类支付**：建议 `payMethodType="CREDITCARD,DEBITCARD"`，不传 `payMethodName`。Waffo 根据用户输入的卡 BIN 自动确定卡组，一次创单同时支持 Visa/Mastercard、信用卡/借记卡
    * **VA（虚拟账户）**：建议 `payMethodType="VA"`，不传 `payMethodName`，用户到收银台选择银行
    * **指定具体支付方式**：同时传 `payMethodType` 和 `payMethodName`，具体值可在 Portal 的 Payin 页面查询

    详细传参规则见 [收银台集成 - 自定义选项](/docs/zh/developer-docs/integration/checkout/customization)。
  </Accordion>

  <Accordion title="userEmail 可以不传吗？">
    `userEmail` 为创单必传字段。

    若商户未收集用户邮箱，可使用 `userId@examples.com` 格式上送（用实际 `userId` 替换）。

    也可联系 Waffo，由 Waffo 代为覆写为该格式（需商户授权）。

    上线后建议传入真实邮箱，避免使用 `test` 等字符或多人共用同一邮箱，否则可能触发风控。
  </Accordion>

  <Accordion title="orderExpiredAt 要不要传？">
    可以传。该字段控制用户在收银台提交订单的时间窗口（必须为 UTC+0 时区）。一旦订单提交到支付渠道后，过期时间由支付方式自身控制。极少数支付方式支持商户传入渠道侧过期时间，具体可登录 Portal 到 Payin 页面查看。
  </Accordion>

  <Accordion title="什么是同币种下单和跨币种下单？">
    * **同币种**：商户定价币种与用户所在国家币种一致（如 IDR 定价 → 印尼用户用 IDR 支付）
    * **跨币种**：商户定价币种与用户支付币种不同（如 USD 定价 → 印尼用户用 IDR 的 DANA 支付）

    跨币种下单需要额外传 `payMethodCountry`（当 `payMethodType` 或 `payMethodName` 任一未指定时）。`userCurrency` 可以不传。
  </Accordion>

  <Accordion title="什么时候需要传 payMethodCountry？">
    当希望收银台只展示**指定国家**的支付方式时传入。不传则展示商户合约下所有国家的可用支付方式。

    * **全球卡**（CREDITCARD/DEBITCARD）：**不要传**，全球卡不属于任何国家

    详细传参规则见 [收银台集成 - 自定义选项](/docs/zh/developer-docs/integration/checkout/customization)。
  </Accordion>
</AccordionGroup>

## 支付

<AccordionGroup>
  <Accordion title="orderAction 里的 webUrl 和 deeplinkUrl 选哪个？">
    根据 `orderAction.actionType` 判断：

    * `actionType = "WEB"` → 取 `webUrl`
    * `actionType = "DEEPLINK"` → 取 `deeplinkUrl`

    一般只会有 `webUrl`。如果传参 `userTerminal=APP`，部分需要外部授权的钱包类支付方式会返回 deeplink。

    > 沙盒环境因使用模拟器，deeplink 无法唤起真实钱包 App，此效果需要在生产环境验证。
  </Accordion>

  <Accordion title="创单返回 orderStatus = AUTHORIZATION_REQUIRED 怎么办？">
    需要将用户引导到外部授权页面。URL 取自 `orderAction`，根据 `actionType` 取 `webUrl` 或 `deeplinkUrl`。
  </Accordion>

  <Accordion title="收到 UnknownStatus 异常怎么办？">
    这个异常是因为调渠道出现网络超时，不确定创单是否成功。

    * **创单时**：如果能确定用户在异常情况下不可能支付成功（如需要返回收银链接的支付方式），可以弃单
    * **退款时**：**必须**使用相同的 `refundRequestId` 进行重试，不能弃单

    参见 [错误处理](/docs/zh/developer-docs/core-concepts/error-handling)。
  </Accordion>

  <Accordion title="为什么沙盒里传某些金额会直接报 C0005、C0001 或 E0001？">
    这是沙盒验收和异常测试的预设行为。当前验收模板会用一组特殊金额主动触发渠道拒绝、系统不可用和 Unknown 状态。

    * 如果你只想测试正常支付链路，请避开这些特殊金额
    * 如果你要复现指定异常，请按 [沙盒模拟器](/docs/zh/developer-docs/tools-and-references/developer-tools/sandbox-simulator) 中的“特殊金额触发异常”使用对应金额
    * `A0011` 和退款 `A0003` 不是特殊金额触发，而是由请求参数组合触发
  </Accordion>

  <Accordion title="用户支付成功但我没有收到 Webhook——该怎么办？">
    1. 检查 `notifyUrl` 是否 HTTPS 且公网可达
    2. 检查回调端口是否为 80 或 443（Waffo 生产环境只支持标准端口）
    3. 检查响应 body 是否为 `{"message": "success"}`，Content-Type 是否为 `application/json`
    4. 检查响应是否包含 `X-SIGNATURE` Header
    5. 主动调用查询接口获取最新状态
    6. 如果持续收不到，联系 Waffo 技术支持
  </Accordion>

  <Accordion title="inquiry 接口一定要接吗？">
    强烈建议接入。使用场景：

    * 用户跳转到成功/失败页时主动查询，给用户最顺畅的体验
    * 对历史订单做订单回溯
    * Webhook 验签不通过时，通过查询接口兜底获取结果
  </Accordion>

  <Accordion title="可以同时使用多种支付方式吗？">
    不指定 `payMethodType` / `payMethodName` 时，收银台会展示所有可用的支付方式，用户自行选择。
  </Accordion>
</AccordionGroup>

## 签名 & 安全

<AccordionGroup>
  <Accordion title="验签不通过的常见原因？">
    1. **私钥格式不正确**：必须是 PKCS#8 格式
    2. **签名内容不正确**：需要对 HTTP body 全部做加签，不能只签部分字段
  </Accordion>

  <Accordion title="RSA 密钥的最低要求是什么？">
    2048 位 RSA 密钥对，使用 SHA256WithRSA（RSASSA-PKCS1-v1\_5 + SHA-256）签名算法。
  </Accordion>

  <Accordion title="沙箱与生产环境可以使用同一套密钥吗？">
    不建议。沙盒和生产应使用不同的 API Key 和 RSA 密钥对。
  </Accordion>
</AccordionGroup>

## App 集成

<AccordionGroup>
  <Accordion title="商户 App 集成收银台有什么注意事项？">
    * 确认 App 和 WebView 是否允许打开外部 App 或外部浏览器页面
    * 确认 App 和 WebView 是否支持下载、复制、长按保存等能力，QR、OTC、银行转账等支付方式可能依赖这些能力
    * 确认原生 App 和 WebView 之间传递 URL 时完整保留 query 参数
    * 使用 WebView 加载时，`userTerminal` 应传 `APP`
    * 详细限制参见 [支付方式集成注意事项](/docs/zh/developer-docs/tools-and-references/references/payment-method-integration-notes)
  </Accordion>

  <Accordion title="商户可以自己集成 Google Pay / Apple Pay 吗？">
    不推荐。建议直接使用 Waffo 收银台内置的 GP/AP 能力，无需商户自行集成。

    | 对比项            | 使用 Waffo 收银台 | 商户自行集成 |
    | -------------- | ------------ | ------ |
    | 开通 GP/AP 开发者账号 | 不需要          | 需要     |
    | 域名注册验证         | 需要           | 需要     |
    | 管理加密证书/密钥      | Waffo 负责     | 商户自行管理 |
    | 服务端处理/解密 Token | Waffo 负责     | 商户自行处理 |
    | PCI DSS 合规     | 不需要          | 可能需要   |
    | 收银台 UI         | Waffo 提供     | 商户自行开发 |
    | **集成复杂度**      | **低**        | **高**  |

    如有特殊需求必须自行集成，请联系 Waffo 技术支持获取详细接入指南。
  </Accordion>

  <Accordion title="PayMe 支付会唤起 App 吗？">
    会唤起 PayMe App。如果用户没有安装，会提示下载。
  </Accordion>
</AccordionGroup>