沙盒测试

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

沙盒基础 URL

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

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

测试发卡流程

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

模拟交易

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

支持的 BIN

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

BIN	环境
`40963608`	沙盒

Simulate authorization

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

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`

模拟交易的 merchant_category_code 必须为 5734。Simulator 不支持其他 MCC 值。

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

{
  "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": ""
  }
}

Simulate reversal

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

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：

{
  "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": ""
  }
}

Webhook 测试

在控制台订阅 webhook 事件，即可在测试期间实时接收通知。完整事件列表和 payload 格式参见 Webhooks。

开发阶段可使用 webhook.site 等工具查看 webhook payload，以便在构建生产环境 webhook 处理器前先行检视。

入门

持卡人

卡片

充值

管理与安全

集成

参考

沙盒基础 URL

测试发卡流程

模拟交易

支持的 BIN

Simulate authorization

Simulate reversal

Webhook 测试

​沙盒基础 URL

​测试发卡流程

​模拟交易

​支持的 BIN

​Simulate authorization

​Simulate reversal

​Webhook 测试

​相关文档

沙盒基础 URL

测试发卡流程

模拟交易

支持的 BIN

Simulate authorization

Simulate reversal

Webhook 测试

相关文档