Visa 回调 - MC Platform Open API

Visa Webhook 会推送到商户在 SpeedPay 商户平台 API KEY 中配置的 HTTPS 回调地址。每次回调只对应一个 api_name。

接入方式

项目	说明
方法	`POST`
地址	商户在 SpeedPay 商户平台 API KEY 中配置的 HTTPS 回调地址
内容类型	`application/json`
签名 Header	`Authorization`

Authorization 是 SpeedPay 使用平台私钥对完整原始 JSON 请求体生成的签名。商户必须使用 SpeedPay 公钥验签，并在验签通过后处理业务数据。

处理流程

读取并保留完整原始 JSON 请求体和 Authorization Header。
使用 SpeedPay 公钥对原始请求体验签，验签失败时停止处理。
读取 api_name，将回调分发到对应的业务处理逻辑。
根据业务流水号、交易流水号或卡号做幂等处理。
建议先持久化或写入队列，再执行耗时业务逻辑。
接收成功后返回数字类型的 code: 0。

回调索引

`api_name`	说明	详情
`pr_card_activation_result_push`	开卡与申请结果	查看详情
`transaction_advice`	交易通知	查看详情
`change_advice`	卡状态变更	查看详情
`express_advice`	物流信息变更	查看详情
`mobile_advice`	手机号变更	查看详情
`apply_edit_advice`	申请资料变更	查看详情

开卡与申请结果

在 Visa 开卡或申请流程完成后通知商户处理结果。

项目	值
`api_name`	`pr_card_activation_result_push`
数据位置	JSON 顶层

字段说明

字段	类型	必填	说明
`app_id`	`string`	否	商户应用 ID
`api_name`	`string`	否	固定为 `pr_card_activation_result_push`
`busi_water_no`	`string`	否	商户侧业务流水号
`card_no`	`string`	否	卡号，可能为脱敏卡号
`active_status`	`1 \| 2`	否	结果状态：`1` 成功，`2` 失败
`fail_reason`	`string`	否	失败原因，失败时返回

请求示例

{
  "api_name": "pr_card_activation_result_push",
  "app_id": "mc-bEreOeGNrHju78Gyd",
  "busi_water_no": "APPLY202607240001",
  "card_no": "411111******1111",
  "active_status": 1
}

交易通知

在 Visa 交易状态发生变化时推送交易、金额、商户和费用信息。

项目	值
`api_name`	`transaction_advice`
数据位置	JSON 顶层

字段说明

字段	类型	必填	说明
`app_id`	`string`	否	商户应用 ID
`api_name`	`string`	否	固定为 `transaction_advice`
`trade_no`	`string`	否	平台交易流水号
`org_trade_no`	`string`	否	原交易流水号
`pan_type`	`string`	否	卡号类型
`pan`	`string`	否	卡号，可能为脱敏卡号
`app_time`	`string`	否	交易时间
`channel_code`	`string`	否	交易渠道编码
`mer_order_no`	`string`	否	商户订单号
`mer_country`	`string`	否	商户国家或地区
`mer_type`	`string`	否	商户类型
`card_accptr_termnl_id`	`string`	否	受卡终端编号
`order_type`	`string`	否	订单类型
`trans_type`	`string`	否	交易类型
`trans_status`	`string`	否	交易状态
`return_code`	`string`	否	交易返回码
`return_desc`	`string`	否	交易返回说明
`goods_id`	`string`	否	商品 ID
`goods_name`	`string`	否	商品名称
`remark`	`string`	否	备注
`trans_amount`	`string`	否	交易金额
`trans_currency_type`	`string`	否	交易币种
`pay_type`	`string`	否	支付类型
`pay_channel`	`string`	否	支付渠道
`pay_reference_no`	`string`	否	支付参考号
`payer_bank_code`	`string`	否	付款方银行编码
`payer_acct_no_mask`	`string`	否	付款方脱敏账号
`payer_name_mask`	`string`	否	付款方脱敏名称
`payer_amount`	`string`	否	付款方金额
`debit_currency`	`string`	否	扣款币种
`payee_bank_code`	`string`	否	收款方银行编码
`payee_acct_no_mask`	`string`	否	收款方脱敏账号
`payee_name_mask`	`string`	否	收款方脱敏名称
`payee_amount`	`string`	否	收款方金额
`credit_currency`	`string`	否	入账币种
`freeze_amount`	`string`	否	冻结金额
`balance_avail`	`string`	否	可用余额
`fee_list`	`FeeItem[]`	否	费用明细列表
`inappropriate_notify`	`InappropriateNotify`	否	不适当交易手续费提醒信息

`fee_list` 字段

字段	类型	必填	说明
`fee_code`	`string`	否	费用编码
`amt_fee`	`string`	否	费用金额
`currcy_code_fee`	`string`	否	费用币种
`fee_memo`	`string`	否	费用说明

`inappropriate_notify` 字段

字段	类型	必填	说明
`scene`	`string`	是	场景：`exempt`、`fee_charged`、`fee_failed` 或 `auto_cancel`
`count`	`number`	是	相关次数
`unpaid_fee_count`	`number`	否	未支付费用次数
`reason`	`string`	否	原因
`failed_time`	`string`	否	失败时间
`cancel_time`	`string`	否	取消时间

请求示例

{
  "api_name": "transaction_advice",
  "app_id": "mc-bEreOeGNrHju78Gyd",
  "trade_no": "T202607240001",
  "org_trade_no": "",
  "pan_type": "01",
  "pan": "411111******1111",
  "app_time": "2026-07-24 12:30:00",
  "channel_code": "VISA",
  "order_type": "0",
  "trans_type": "0201",
  "trans_status": "success",
  "return_code": "000000",
  "return_desc": "success",
  "trans_amount": "100.00",
  "trans_currency_type": "HKD",
  "freeze_amount": "0.00",
  "balance_avail": "900.00"
}

卡状态变更

在 Visa 卡状态发生变化时通知商户更新本地卡状态。

项目	值
`api_name`	`change_advice`
数据位置	JSON 顶层

字段说明

字段	类型	必填	说明
`app_id`	`string`	是	商户应用 ID
`api_name`	`string`	是	固定为 `change_advice`
`push_no`	`string`	否	推送流水号
`card_no`	`string`	是	卡号，可能为脱敏卡号
`card_status`	`number`	是	平台卡状态
`inappropriate_notify`	`InappropriateNotify`	否	不适当交易手续费提醒信息

请求示例

{
  "api_name": "change_advice",
  "app_id": "mc-bEreOeGNrHju78Gyd",
  "push_no": "PUSH202607240001",
  "card_no": "411111******1111",
  "card_status": 6
}

物流信息变更

在实体卡物流信息发生变化时通知商户承运方和运单号。

项目	值
`api_name`	`express_advice`
数据位置	JSON 顶层

字段说明

字段	类型	必填	说明
`app_id`	`string`	是	商户应用 ID
`api_name`	`string`	是	固定为 `express_advice`
`card_no`	`string`	否	卡号，可能为脱敏卡号
`express_no`	`string`	否	物流单号
`express_company`	`string`	否	物流公司

请求示例

{
  "api_name": "express_advice",
  "app_id": "mc-bEreOeGNrHju78Gyd",
  "card_no": "411111******1111",
  "express_no": "SF1234567890",
  "express_company": "顺丰快递"
}

手机号变更

在 Visa 卡绑定手机号变更后通知商户同步新旧手机号。

项目	值
`api_name`	`mobile_advice`
数据位置	JSON 顶层

字段说明

字段	类型	必填	说明
`app_id`	`string`	是	商户应用 ID
`api_name`	`string`	是	固定为 `mobile_advice`
`busi_water_no`	`string`	是	商户侧业务流水号
`card_no`	`string`	是	卡号，可能为脱敏卡号
`old_mob_no`	`string`	是	原手机号
`old_mob_no_of`	`string`	是	原手机号区号
`new_mob_no`	`string`	是	新手机号
`new_mob_no_of`	`string`	是	新手机号区号

请求示例

{
  "api_name": "mobile_advice",
  "app_id": "mc-bEreOeGNrHju78Gyd",
  "busi_water_no": "MOBILE202607240001",
  "card_no": "411111******1111",
  "old_mob_no": "13800000000",
  "old_mob_no_of": "86",
  "new_mob_no": "13900000000",
  "new_mob_no_of": "86"
}

申请资料变更

在 Visa 申请资料发生变更后通知商户同步持卡人资料。

项目	值
`api_name`	`apply_edit_advice`
数据位置	JSON 顶层

字段说明

字段	类型	必填	说明
`app_id`	`string`	是	商户应用 ID
`api_name`	`string`	是	固定为 `apply_edit_advice`
`busi_water_no`	`string`	是	商户侧业务流水号
`card_no`	`string`	否	卡号，可能为脱敏卡号
`name`	`string`	否	姓名
`name_en`	`string`	否	英文姓名
`birthday`	`string`	否	出生日期
`cert_id`	`string`	否	证件号码
`cert_start_date`	`string`	否	证件有效期开始日期
`cert_end_date`	`string`	否	证件有效期结束日期
`office_tel_no_of`	`string`	否	办公电话区号
`office_tel_no`	`string`	否	办公电话
`office_address`	`string`	否	办公地址
`address`	`string`	否	联系地址

请求示例

{
  "api_name": "apply_edit_advice",
  "app_id": "mc-bEreOeGNrHju78Gyd",
  "busi_water_no": "EDIT202607240001",
  "name": "张三",
  "name_en": "ZHANG SAN",
  "birthday": "1990-01-01",
  "cert_id": "A1234567",
  "address": "Hong Kong"
}

TypeScript 类型参考

type VisaApiName =
  | "pr_card_activation_result_push"
  | "transaction_advice"
  | "change_advice"
  | "express_advice"
  | "mobile_advice"
  | "apply_edit_advice";

interface VisaActivationWebhook {
  app_id?: string;
  api_name?: "pr_card_activation_result_push";
  busi_water_no?: string;
  card_no?: string;
  active_status?: 1 | 2;
  fail_reason?: string;
}

interface VisaTransactionWebhook {
  app_id?: string;
  api_name?: "transaction_advice";
  trade_no?: string;
  org_trade_no?: string;
  pan_type?: string;
  pan?: string;
  app_time?: string;
  channel_code?: string;
  mer_order_no?: string;
  mer_country?: string;
  mer_type?: string;
  card_accptr_termnl_id?: string;
  order_type?: string;
  trans_type?: string;
  trans_status?: string;
  return_code?: string;
  return_desc?: string;
  goods_id?: string;
  goods_name?: string;
  remark?: string;
  trans_amount?: string;
  trans_currency_type?: string;
  pay_type?: string;
  pay_channel?: string;
  pay_reference_no?: string;
  payer_bank_code?: string;
  payer_acct_no_mask?: string;
  payer_name_mask?: string;
  payer_amount?: string;
  debit_currency?: string;
  payee_bank_code?: string;
  payee_acct_no_mask?: string;
  payee_name_mask?: string;
  payee_amount?: string;
  credit_currency?: string;
  freeze_amount?: string;
  balance_avail?: string;
  fee_list?: FeeItem[];
  inappropriate_notify?: InappropriateNotify;
}

interface VisaChangeAdviceWebhook {
  app_id: string;
  api_name: "change_advice";
  push_no?: string;
  card_no: string;
  card_status: number;
  inappropriate_notify?: InappropriateNotify;
}

interface VisaExpressAdviceWebhook {
  app_id: string;
  api_name: "express_advice";
  card_no?: string;
  express_no?: string;
  express_company?: string;
}

interface VisaMobileAdviceWebhook {
  app_id: string;
  api_name: "mobile_advice";
  busi_water_no: string;
  card_no: string;
  old_mob_no: string;
  old_mob_no_of: string;
  new_mob_no: string;
  new_mob_no_of: string;
}

interface VisaApplyEditAdviceWebhook {
  app_id: string;
  api_name: "apply_edit_advice";
  busi_water_no: string;
  card_no?: string;
  name?: string;
  name_en?: string;
  birthday?: string;
  cert_id?: string;
  cert_start_date?: string;
  cert_end_date?: string;
  office_tel_no_of?: string;
  office_tel_no?: string;
  office_address?: string;
  address?: string;
}

interface FeeItem {
  fee_code?: string;
  amt_fee?: string;
  currcy_code_fee?: string;
  fee_memo?: string;
}

interface InappropriateNotify {
  scene: "exempt" | "fee_charged" | "fee_failed" | "auto_cancel";
  count: number;
  unpaid_fee_count?: number;
  reason?: string;
  failed_time?: string;
  cancel_time?: string;
}

成功响应与失败处理

商户完成验签并成功接收回调后返回：

{
  "code": 0,
  "msg": "success"
}

code 必须为数字 0。非 0、网络错误或响应超时会被记录为回调失败。

​接入方式

​处理流程

​回调索引

​开卡与申请结果

​交易通知

​fee_list 字段

​inappropriate_notify 字段

​卡状态变更

​物流信息变更

​手机号变更

​申请资料变更

​TypeScript 类型参考

​成功响应与失败处理

接入方式

处理流程

回调索引

开卡与申请结果

交易通知

`fee_list` 字段

`inappropriate_notify` 字段

卡状态变更

物流信息变更

手机号变更

申请资料变更

TypeScript 类型参考

成功响应与失败处理