Documentation Index
Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/llms.txt
Use this file to discover all available pages before exploring further.
UQPAY 沙盒环境让你能测试完整的发卡生命周期 —— 从创建持卡人、签发卡片，到模拟交易、接收 webhook —— 且不会产生真实支付。
沙盒基础 URL
https://api-sandbox.uqpaytech.com/api
测试发卡流程
在沙盒中，你创建的是真实的持卡人和卡片，方式与生产环境完全一样。没有所谓的”测试”卡号 —— 你创建的卡就是你的测试卡。
典型测试流程：
确认你的 webhook endpoint 收到了预期的事件（例如 issuing.transaction.authorization）。
模拟交易
Simulator 接口让你能在沙盒卡上触发授权和冲正事件。这些接口仅在沙盒环境可用。
支持的 BIN
只有以下 BIN 的卡片支持模拟：
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 处理器前先行检视。 
