> ## 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 沙盒环境让你能测试完整的发卡生命周期 —— 从创建持卡人、签发卡片，到模拟交易、接收 webhook —— 且不会产生真实支付。

<h2 id="sandbox-base-url">沙盒基础 URL</h2>

```
https://api-sandbox.uqpaytech.com/api
```

所有 API 路径与生产环境一致。切换环境时只需替换基础 URL。

<h2 id="test-the-card-issuance-flow">测试发卡流程</h2>

在沙盒中，你创建的是真实的持卡人和卡片，方式与生产环境完全一样。没有所谓的"测试"卡号 —— 你创建的卡就是你的测试卡。

典型测试流程：

<Steps>
  <h3 id="create-a-cardholder">创建持卡人</h3>

  调用 [Create Cardholder](/zh/card-issuance/v1.6/api-reference/create-cardholder)，使用测试数据。邮箱和手机号使用任意合法格式即可。

  <h3 id="issue-a-card">签发卡片</h3>

  调用 [Create Card](/zh/card-issuance/v1.6/api-reference/create-card)，使用沙盒支持的卡产品。完整流程参见[快速开始](/zh/card-issuance/v1.6/guide/quickstart)。

  <h3 id="simulate-a-transaction">模拟交易</h3>

  使用 [Simulate Authorization](#simulate-authorization) 接口对你的卡触发一笔交易。

  <h3 id="verify-webhooks">验证 webhook</h3>

  确认你的 webhook endpoint 收到了预期的事件（例如 `issuing.transaction.authorization`）。
</Steps>

<h2 id="simulate-transactions">模拟交易</h2>

Simulator 接口让你能在沙盒卡上触发授权和冲正事件。这些接口仅在沙盒环境可用。

<h3 id="supported-bins">支持的 BIN</h3>

只有以下 BIN 的卡片支持模拟：

| BIN        | 环境 |
| ---------- | -- |
| `40963608` | 沙盒 |

<h3 id="simulate-authorization">Simulate authorization</h3>

对一张卡触发一笔授权交易。

```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/simulation/issuing/authorization \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "card_id": "50418faa-57a8-4ce2-9157-621b00b13a3b",
    "transaction_amount": 10.00,
    "transaction_currency": "USD",
    "merchant_name": "Test Merchant",
    "merchant_category_code": "5734"
  }'
```

| 字段                       |  必填 | 说明                 |
| ------------------------ | :-: | ------------------ |
| `card_id`                |  是  | 交易对应的卡片            |
| `transaction_amount`     |  是  | 授权金额               |
| `transaction_currency`   |  是  | 币种（例如 `USD`、`SGD`） |
| `merchant_name`          |  是  | 商户名称               |
| `merchant_category_code` |  是  | MCC。模拟时必须为 `5734`  |

<Note>
  模拟交易的 `merchant_category_code` 必须为 `5734`。Simulator 不支持其他 MCC 值。
</Note>

这会触发一个 `issuing.transaction.authorization` webhook：

```json theme={null}
{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "issuing.transaction.authorization",
  "event_id": "234fca01-1ace-4d34-baf5-29b10e9d11c0",
  "source_id": "1a53aebf-900c-4e25-9852-b98f4338d94c",
  "data": {
    "authorization_code": "W6MJU9",
    "billing_amount": "11.5",
    "billing_currency": "USD",
    "card_available_balance": "988.5",
    "card_id": "50418faa-57a8-4ce2-9157-621b00b13a3b",
    "card_number": "40963608****1764",
    "cardholder_id": "25ea804d-7fd5-43d5-8792-0fc0214cdb2f",
    "description": "",
    "fee_pass_through": "Y",
    "merchant_data": [
      {
        "category_code": "5734",
        "city": "",
        "country": "",
        "name": "Test Merchant"
      }
    ],
    "original_transaction_id": "",
    "posted_time": "2026-04-12T15:27:39.563+08:00",
    "short_transaction_id": "T260412-2AHV51KO5U68",
    "transaction_amount": "10",
    "transaction_currency": "USD",
    "transaction_fee": "1.5",
    "transaction_fee_currency": "USD",
    "transaction_id": "1a53aebf-900c-4e25-9852-b98f4338d94c",
    "transaction_status": "APPROVED",
    "transaction_time": "2026-04-12T15:27:39.48+08:00",
    "transaction_type": "AUTHORIZATION",
    "wallet_type": ""
  }
}
```

<h3 id="simulate-reversal">Simulate reversal</h3>

使用已授权通过的交易的 `transaction_id` 冲正该笔交易。

```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/simulation/issuing/reversal \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "1a53aebf-900c-4e25-9852-b98f4338d94c"
  }'
```

这会触发一个 `issuing.transaction.reversal` webhook：

```json theme={null}
{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "issuing.transaction.reversal",
  "event_id": "255d66c0-ddf6-479a-a0b1-923e23664648",
  "source_id": "5353d200-88de-49b2-b575-d4bdd3d7be30",
  "data": {
    "authorization_code": "5PHF2P",
    "billing_amount": "11.5",
    "billing_currency": "USD",
    "card_available_balance": "1000",
    "card_id": "50418faa-57a8-4ce2-9157-621b00b13a3b",
    "card_number": "40963608****1764",
    "cardholder_id": "25ea804d-7fd5-43d5-8792-0fc0214cdb2f",
    "description": "",
    "fee_pass_through": "Y",
    "merchant_data": [
      {
        "category_code": "5734",
        "city": "",
        "country": "",
        "name": "Test Merchant"
      }
    ],
    "original_transaction_id": "1a53aebf-900c-4e25-9852-b98f4338d94c",
    "posted_time": "2026-04-12T15:27:40.905+08:00",
    "short_transaction_id": "T260412-2AHV54BIN6RK",
    "transaction_amount": "10",
    "transaction_currency": "USD",
    "transaction_fee": "1.5",
    "transaction_fee_currency": "USD",
    "transaction_id": "5353d200-88de-49b2-b575-d4bdd3d7be30",
    "transaction_status": "APPROVED",
    "transaction_time": "2026-04-12T15:27:40.905+08:00",
    "transaction_type": "REVERSAL",
    "wallet_type": ""
  }
}
```

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

在控制台订阅 webhook 事件，即可在测试期间实时接收通知。完整事件列表和 payload 格式参见 [Webhooks](/zh/card-issuance/v1.6/webhooks/card-created)。

<Tip>
  开发阶段可使用 [webhook.site](https://webhook.site) 等工具查看 webhook payload，以便在构建生产环境 webhook 处理器前先行检视。
</Tip>

<h2 id="related">相关文档</h2>

* [快速开始](/zh/card-issuance/v1.6/guide/quickstart)
* [Simulate Authorization API](/zh/card-issuance/v1.6/api-reference/simulate-authorization)
* [Simulate Reversal API](/zh/card-issuance/v1.6/api-reference/simulate-reversal)
* [Transaction Authorization webhook](/zh/card-issuance/v1.6/webhooks/transaction)