> ## Documentation Index > Fetch the complete documentation index at: https://developer.speedpay.hk/llms.txt > Use this file to discover all available pages before exploring further. # Visa 回调 > 接收 Visa 卡申请、状态、交易、物流、手机号和申请资料变更通知。 Visa Webhook 会推送到商户在 SpeedPay 商户平台 API KEY 中配置的 HTTPS 回调地址。每次回调只对应一个 `api_name`。 ## 请求头 | Header | 说明 | | --------------- | -------------------------------- | | `Content-Type` | 固定为 `application/json` | | `Authorization` | SpeedPay 使用平台私钥对完整 JSON 请求体生成的签名 | 商户需要使用 SpeedPay 公钥验签。验签通过后再处理业务数据。 ## 返回示例 ```json theme={null} { "code": 0, "msg": "success" } ``` `code` 必须为数字 `0`。 ## 回调类型 | `api_name` | 说明 | 主体结构 | | -------------------------------- | ------- | ---------------------------- | | `pr_card_activation_result_push` | 开卡/申请结果 | `VisaActivationWebhook` | | `transaction_advice` | 交易通知 | `VisaTransactionWebhook` | | `change_advice` | 卡状态变更 | `VisaChangeAdviceWebhook` | | `express_advice` | 物流信息变更 | `VisaExpressAdviceWebhook` | | `mobile_advice` | 手机号变更 | `VisaMobileAdviceWebhook` | | `apply_edit_advice` | 申请资料变更 | `VisaApplyEditAdviceWebhook` | ## Webhook 结构体 ```ts theme={null} 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; } ``` ## 字段说明 | 字段 | 说明 | | ---------------------- | --------------------- | | `app_id` | 商户应用 ID | | `api_name` | 回调类型 | | `busi_water_no` | 商户侧业务流水号 | | `card_no` | 卡号，可能为脱敏卡号 | | `active_status` | 开卡/申请结果：`1` 成功，`2` 失败 | | `fail_reason` | 失败原因 | | `card_status` | 平台卡状态，参考卡状态附录 | | `trade_no` | 平台交易流水号 | | `org_trade_no` | 原交易流水号 | | `trans_type` | 交易类型，参考交易类型附录 | | `trans_status` | 交易状态 | | `trans_amount` | 交易金额，字符串类型 | | `trans_currency_type` | 交易币种 | | `fee_list` | 费用明细列表 | | `inappropriate_notify` | 不适当交易手续费提醒信息，仅相关场景返回 | ## 请求示例 ### 开卡/申请结果 ```json theme={null} { "api_name": "pr_card_activation_result_push", "app_id": "mc-bEreOeGNrHju78Gyd", "busi_water_no": "APPLY202607240001", "card_no": "411111******1111", "active_status": 1 } ``` ### 交易通知 ```json theme={null} { "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" } ``` ### 卡状态变更 ```json theme={null} { "api_name": "change_advice", "app_id": "mc-bEreOeGNrHju78Gyd", "push_no": "PUSH202607240001", "card_no": "411111******1111", "card_status": 6 } ``` ### 物流信息变更 ```json theme={null} { "api_name": "express_advice", "app_id": "mc-bEreOeGNrHju78Gyd", "card_no": "411111******1111", "express_no": "SF1234567890", "express_company": "顺丰快递" } ``` ### 手机号变更 ```json theme={null} { "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" } ``` ### 申请资料变更 ```json theme={null} { "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" } ```