> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 沙盒测试

> UQPAY Global Acquiring 的测试卡号、电子钱包沙盒设置以及生产上线检查清单。

UQPAY 沙盒环境让你能在不产生真实交易的前提下测试集成。以下所有测试凭据仅在沙盒环境中可用。

<h2 id="test-card-numbers">测试卡号</h2>

使用下列测试卡调用 [Create Payment Intent](/zh/global-acquiring/v1.6/api-reference/create-payment-intent) API。`card_name` 可填任意值（例如 "John Doe"）。

<Note>
  `network` 字段使用小写：`mastercard`、`visa`、`unionpay`。卡号中不要带空格。若收到 `product_not_found` 错误，请联系 UQPAY 技术支持。
</Note>

| 卡组织        | 卡号                 | 有效期   | CVC | 支持的模式          |
| ---------- | ------------------ | ----- | --- | -------------- |
| Mastercard | `5413330057004047` | 12/25 | 989 | online、offline |
| Mastercard | `5346930100108117` | 12/26 | 811 | online、offline |
| Visa       | `4176660000000027` | 12/33 | 303 | offline（POS）   |
| UnionPay   | `6250947000000014` | 12/33 | 123 | online、offline |

<h3 id="card-payment-request-example">卡支付请求示例</h3>

```json theme={null}
{
  "amount": "8.98",
  "currency": "SGD",
  "payment_method": {
    "type": "card",
    "card": {
      "card_name": "UQPAY",
      "card_number": "5346930100108117",
      "expiry_month": "12",
      "expiry_year": "2026",
      "cvc": "811",
      "network": "mastercard",
      "billing": {
        "first_name": "UQPAY",
        "last_name": "ACQ",
        "email": "acq@uqpay.com",
        "phone_number": "0524-91353515",
        "address": {
          "country_code": "SG",
          "state": "Singapore",
          "city": "Singapore",
          "street": "444 Orchard Rd, Midpoint Orchard, Singapore",
          "postcode": "924011"
        }
      },
      "auto_capture": true,
      "authorization_type": "authorization",
      "three_ds_action": "skip_3ds"
    }
  },
  "merchant_order_id": "test-order-001",
  "description": "test",
  "metadata": {},
  "return_url": "https://example.com/callback"
}
```

<h2 id="e-wallet-sandbox-testing">电子钱包沙盒测试</h2>

<h3 id="alipaycn-alipayhk">AlipayCN 与 AlipayHK</h3>

<h4 id="setup">准备工作</h4>

<Tabs>
  <Tab title="方式 A：自行注册账户">
    1. 从[此处](https://docs.antom.com/ac/ref/testwallet?locale=en-us)安装 Alipay 测试钱包 App **AWallet**。
    2. 在[此处](https://global.alipay.com/ilogin/account_login.htm?_route=QK)注册一个 Alipay 沙盒账户。
  </Tab>

  <Tab title="方式 B：使用共享测试账户">
    1. 从[此处](https://docs.antom.com/ac/ref/testwallet?locale=en-us)安装 Alipay 测试钱包 App **AWallet**。
    2. 联系技术支持获取测试账户凭据。
  </Tab>
</Tabs>

<h4 id="qr-code-flow">二维码流程</h4>

发送带 `flow: "qrcode"` 和 `is_present: false` 的支付请求：

```json theme={null}
{
  "amount": "7.77",
  "currency": "SGD",
  "payment_method": {
    "type": "alipaycn",
    "alipaycn": {
      "flow": "qrcode",
      "is_present": false
    }
  },
  "merchant_order_id": "alipay-qr-test-001",
  "description": "acquiring sandbox testing",
  "metadata": {},
  "return_url": "https://example.com/callback"
}
```

响应会返回 `intent_status: "REQUIRES_CUSTOMER_ACTION"`，并在 `next_action.display_qr_code` 中包含二维码 URL。在浏览器中打开 `qr_code_url`，用 AWallet App 扫码完成支付。

<h4 id="payment-code-flow-in-person">付款码流程（线下）</h4>

线下付款码场景将 `is_present` 设为 `true`，并带上客户的 `payment_code`：

1. 打开 **AWallet** App，点击 **"Payment Code"**。
2. 点击条形码查看付款码数字。
3. 在 API 请求中使用该付款码：

```json theme={null}
{
  "amount": "1.11",
  "currency": "SGD",
  "payment_method": {
    "type": "alipaycn",
    "alipaycn": {
      "flow": "qrcode",
      "os_type": "ios",
      "is_present": true,
      "payment_code": "284057804613761079"
    }
  },
  "merchant_order_id": "alipay-paycode-test-001",
  "description": "acquiring sandbox testing",
  "metadata": {},
  "return_url": "https://example.com/callback"
}
```

付款码交易会立即完成 —— 响应会返回 `intent_status: "SUCCEEDED"`。

<h2 id="webhook-testing">Webhook 测试</h2>

测试 webhook 送达的步骤：

1. 在 UQPAY 控制台配置你的 webhook URL。
2. 发起一笔沙盒交易（卡支付或电子钱包）。
3. 确认你的服务器收到了 webhook 通知。
4. 返回 HTTP 200 以确认接收。

Webhook payload schema 参见 [Webhooks](/zh/global-acquiring/v1.6/webhooks/paymentintent-result) 标签页。

<Tip>
  开发阶段可使用 [webhook.site](https://webhook.site) 等工具查看 webhook payload。
</Tip>

<h2 id="go-live-checklist">生产上线检查清单</h2>

切换到生产环境前：

* [ ] **账户已审批**：在 [app.uqpay.com](https://app.uqpay.com/) 注册并完成 KYC/KYB 验证
* [ ] **生产 API 密钥**：在控制台创建生产环境的 `apiKey` 和 `clientId`
* [ ] **生产基础 URL**：将所有 API 调用切换到 `https://api.uqpay.com`
* [ ] **Webhook IP 白名单**：将 UQPAY 的 webhook 源 IP（`18.143.59.64`、`54.179.248.205`、`13.250.234.88`、`18.136.58.213`、`56.10.39.6`）加入白名单 —— 详情参见 [Webhooks Overview](/zh/account-center/v1.6/guide/webhooks-overview#production-environment)
* [ ] **Webhook 订阅**：订阅集成所需的 webhook 事件