模拟卡交易
POST/openapi/v2/cards/transactions/simulate仅用于 Sandbox 联调;受理成功不代表消费已完成,应结合交易查询和商户 Webhook 验证最终结果。
| 项 | 内容 |
|---|---|
| 请求方法 | POST |
| 请求路径 | /openapi/v2/cards/transactions/simulate |
| 请求类型 | application/json |
产品支持范围
| 卡产品 | 支持的模拟类型 | 商户信息 |
|---|---|---|
| 万事达香港美元卡 | AUTHORIZE、CAPTURE | 可选 |
| 万事达全球美元卡 | AUTHORIZE、VOID、REFUND | 以下五个商户字段均必填 |
当前接口的请求币种仅支持 USD(三位代码),不支持 USDT。服务方处理币种取自卡产品,不能通过请求币种改变卡产品的结算币种。
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
requestNo | string | 是 | 调用方业务幂等号,1 到 64 位可见 ASCII 字符,不能包含空格。 |
cardId | string | 是 | 卡 ID,最大 128 位。 |
transactionType | string | 是 | AUTHORIZE、CAPTURE、VOID 或 REFUND;支持范围见上表。 |
originalTransactionId | string | 条件 | CAPTURE、VOID、REFUND 必填,最大 128 位;必须是当前租户、同卡的服务方原交易 ID,不是 requestNo 或 simulationNo。 |
amount | number | 是 | 大于 0,最多 18 位整数和 18 位小数;仍受卡产品金额限制约束。 |
currency | string | 是 | 当前使用 USD。 |
mcc | string | 条件 | 商户类别码,最大 8 位;全球美元卡必填。 |
merchantName | string | 条件 | 商户名称,最大 128 位;全球美元卡必填。 |
merchantCountry | string | 条件 | 商户国家或地区二位码;全球美元卡必填。 |
merchantCity | string | 条件 | 商户城市,最大 128 位;全球美元卡必填。 |
merchantPostcode | string | 条件 | 商户邮编,最大 32 位;全球美元卡必填。 |
后续模拟操作使用前次响应中的 providerTransactionId 或已落库交易的服务方交易 ID。只有原交易已被平台识别并归属当前卡,才可继续;不要仅根据 HTTP 200 判定交易成功。退款可按小于原交易金额的金额模拟部分退款;已识别的原消费存在时,本次退款不得超过扣除已成功退款后的剩余可退金额。
请求示例
cardId 应替换为当前租户实际可用的 Sandbox 卡:
json
{
"requestNo": "SIM-20261010-001",
"cardId": "card_001",
"transactionType": "AUTHORIZE",
"amount": 10.5,
"currency": "USD",
"mcc": "5812",
"merchantName": "Example Restaurant",
"merchantCountry": "US",
"merchantCity": "New York",
"merchantPostcode": "10001"
}响应 data
| 字段 | 类型 | 说明 |
|---|---|---|
simulationNo | string | 平台模拟订单号。 |
requestNo | string | 调用方业务幂等号。 |
cardId | string | 卡 ID。 |
providerName | string | 公开渠道别名:CPS、PHY;未配置别名的渠道返回 UNKNOWN。 |
transactionType | string | 请求的模拟类型。 |
accepted | boolean | 是否已明确受理,不表示消费已完成。 |
status | string | 模拟请求状态:CREATED、PROCESSING、UNKNOWN、FAILED;已受理通常为 PROCESSING。 |
providerTransactionId | string/null | 服务方交易 ID;未返回时为空。 |
code | string/null | 结果码或失败码;与外层 code 分开判断。 |
message | string/null | 结果说明或失败原因。 |
UNKNOWN 表示请求结果未知,不能直接当作失败再次扣款或退款。最终业务结果以查询卡交易记录和商户 Webhook为准。
