跳转到内容

模拟卡交易 ​

POST /openapi/v2/cards/transactions/simulate

仅用于 Sandbox 联调;受理成功不代表消费已完成,应结合交易查询和商户 Webhook 验证最终结果。

项内容
请求方法POST
请求路径/openapi/v2/cards/transactions/simulate
请求类型application/json

产品支持范围 ​

卡产品支持的模拟类型商户信息
万事达香港美元卡AUTHORIZE、CAPTURE可选
万事达全球美元卡AUTHORIZE、VOID、REFUND以下五个商户字段均必填

当前接口的请求币种仅支持 USD(三位代码),不支持 USDT。服务方处理币种取自卡产品,不能通过请求币种改变卡产品的结算币种。

请求参数 ​

字段类型必填说明
requestNostring是调用方业务幂等号,1 到 64 位可见 ASCII 字符,不能包含空格。
cardIdstring是卡 ID,最大 128 位。
transactionTypestring是AUTHORIZE、CAPTURE、VOID 或 REFUND;支持范围见上表。
originalTransactionIdstring条件CAPTURE、VOID、REFUND 必填,最大 128 位;必须是当前租户、同卡的服务方原交易 ID,不是 requestNo 或 simulationNo。
amountnumber是大于 0,最多 18 位整数和 18 位小数;仍受卡产品金额限制约束。
currencystring是当前使用 USD。
mccstring条件商户类别码,最大 8 位;全球美元卡必填。
merchantNamestring条件商户名称,最大 128 位;全球美元卡必填。
merchantCountrystring条件商户国家或地区二位码;全球美元卡必填。
merchantCitystring条件商户城市,最大 128 位;全球美元卡必填。
merchantPostcodestring条件商户邮编,最大 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 ​

字段类型说明
simulationNostring平台模拟订单号。
requestNostring调用方业务幂等号。
cardIdstring卡 ID。
providerNamestring公开渠道别名:CPS、PHY;未配置别名的渠道返回 UNKNOWN。
transactionTypestring请求的模拟类型。
acceptedboolean是否已明确受理,不表示消费已完成。
statusstring模拟请求状态:CREATED、PROCESSING、UNKNOWN、FAILED;已受理通常为 PROCESSING。
providerTransactionIdstring/null服务方交易 ID;未返回时为空。
codestring/null结果码或失败码;与外层 code 分开判断。
messagestring/null结果说明或失败原因。

UNKNOWN 表示请求结果未知,不能直接当作失败再次扣款或退款。最终业务结果以查询卡交易记录和商户 Webhook为准。