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

> 如何获取沙箱凭据、模拟支付成功与失败、使用测试卡号、在本地接收 Webhook，以及理解沙箱与生产环境的差别。

## 如何获得沙箱的访问权限？

每个 Waffo 商户账户都可以使用沙箱。你需要：

1. 一个 Waffo 商户账户。
2. 一个 API Key——在 **Merchant Portal → Integration** 查看（需要 Dev 或 Admin 角色）。
3. 一对用于请求签名的 RSA 密钥——沙箱提供预生成的密钥；参见 [Authentication and signing](/docs/zh/developer-docs/integration/api/overview)。

沙箱中绝不会产生真实扣款。

## 如何把我的集成指向沙箱？

| 环境 | Base URL |
| - | - |
| 沙箱 | `https://api-sandbox.waffo.com` |
| 生产 | `https://api.waffo.com` |

如果你使用 Waffo SDK，设置 `Environment.SANDBOX` / `Environment.PRODUCTION` 即可——无需手动修改 URL。

## 如何模拟支付成功或失败？

沙箱不连接真实支付渠道。取而代之，收银台页面会显示模拟按钮：

1. 调用 `POST /api/v1/order/create`，从 `orderAction` 中取得收银台 URL。
2. 在浏览器中打开收银台页面。
3. 点击 **Payment succeeded**（订单状态变为 `PAY_SUCCESS`）或 **Payment failed**（订单状态变为 `ORDER_CLOSE`）。

点击后，Waffo 会自动向你的 `notifyUrl` 发送 `PAYMENT_NOTIFICATION` Webhook。所有支付方式的模拟流程相同——不会调用真实渠道。若卡流程显示卡表单，使用快速填充按钮或下方的测试卡。

## 如何在不等待账单周期的情况下测试订阅续订？

1. 创建并激活一个订阅（`POST /api/v1/subscription/create`，然后在收银台页面模拟首期支付——状态变为 `ACTIVE`）。
2. 调用 `POST /api/v1/subscription/manage` 获取 `managementUrl`，并在浏览器中打开。
3. 点击 **Simulate next payment succeeded**（发送 `PAYMENT_NOTIFICATION` 和 `SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION`）或 **Simulate next payment failed**（发送失败的 `PAYMENT_NOTIFICATION`）。

每次点击模拟一个续订周期，因此可以串联多周期场景（第 2 期成功，第 3 期失败）。管理页面也支持取消，取消会发送状态为 `USER_CANCELLED` 的 `SUBSCRIPTION_STATUS_NOTIFICATION`。详见 [Sandbox simulator](/docs/zh/developer-docs/tools-and-references/developer-tools/sandbox-simulator)。

## 我可以使用哪些测试卡号？

对于需要输入卡号的流程，使用以下沙箱卡号（与 Portal 的 **Test Cards** 列表一致；它们都不会触发 3DS 挑战——沙箱没有 3DS 模拟）：

| payMethodName | 支付成功 | 支付失败 |
| - | - | - |
| CC\_VISA | `4576750000000110` | `4576750000000220` |
| CC\_MASTERCARD | `2226900000000110` | `2226900000000220` |
| CC\_JCB | `3528000000000214` | `3528000000120006` |
| CC\_AMEX | `3799960000000110` | `3799960000000220` |
| DC\_VISA | `4001700000000110` | `4001700000000220` |
| DC\_MASTERCARD | `2226930000000110` | `2226930000000220` |
| DC\_JCB | `3088850000000116` | `3088850000200004` |
| DC\_AMEX | `3421560000000110` | `3421560000000220` |

有效期：任意未来日期。CVV：任意 3 位数字（AMEX 为 4 位）。大多数场景下，收银台的模拟按钮已经足够，不需要卡号。

当流程确实要求输入卡号时，优先使用**沙箱收银台页面上的快速填充按钮**，或 **Merchant Portal → Integration → Test Cards** 中的列表——如果任何文档与产品内列表不一致，以产品内为准。参见 [Sandbox Simulation Limits FAQ](/docs/zh/support/sandbox-simulation-limits-faq)。

## 如何在沙箱中触发特定错误码？

沙箱保留了一些特殊订单金额，会故意返回对应的错误码——例如金额 `90`、`990`、`1990`、`19990` 会在创建订单或订阅时触发 `C0005 Payment Channel Rejection`，其他保留金额会触发 `C0001 System Error` 或 `E0001 Unknown Status`。保留金额适用于**订单创建、订单取消、订阅创建和订阅取消**；在退款 API 上，`refundAmount` 等于创建类保留金额之一时，退款请求会在请求时失败并留下一笔 `REFUND_FAILED` 的退款订单，而已发布模拟器页面上的退款专用金额则不生效。只想走正常成功/失败流程时请避开这些金额——并注意这只是沙箱规则，不是生产行为。完整映射以及真实价格与保留金额冲突时的处理方式，见 [Sandbox Simulation Limits FAQ](/docs/zh/support/sandbox-simulation-limits-faq)。

## 为什么我收不到沙箱发来的 Webhook？

沙箱会发送真实的 Webhook，但你的 `notifyUrl` 必须可公网访问——Waffo 无法访问 `localhost` 或内网地址。本地开发时，使用内网穿透工具（如 ngrok 或 cloudflared），并把隧道的公网 URL 设为你的 `notifyUrl`。回调契约见 [Webhook overview](/docs/zh/developer-docs/webhook/overview)。

## 沙箱和生产环境有什么不同？

| 方面 | 沙箱 | 生产 |
| - | - | - |
| Base URL / SDK | `https://api-sandbox.waffo.com` / `Environment.SANDBOX` | `https://api.waffo.com` / `Environment.PRODUCTION` |
| 资金 | 无真实扣款 | 真实交易 |
| 支付渠道 | 模拟器按钮；不连接真实渠道 | 真实支付渠道 |
| API Key | 沙箱专用 | 独立的生产 API Key |
| RSA 密钥 | 预生成的沙箱密钥 | 生成新的生产密钥对——不要复用沙箱密钥 |

Octopus、Apple Pay 和 Google Pay 在常规沙箱测试之外还需要额外的专项检查——参见 [Sandbox and testing](/docs/zh/developer-docs/getting-started/sandbox)。切换到生产之前，完成[上线检查清单](/docs/zh/developer-docs/getting-started/go-live)中的每一项，包括向 Waffo 技术支持群提交集成验收。


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