> ## 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 与 JCB Webhook 回调说明。

SpeedPay 会通过 Webhook 将异步业务结果推送到商户在 API KEY 中配置的 HTTPS 回调地址。回调地址由商户提供，不是固定的平台接口路径。

## 通用请求

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

`Authorization` 的值为 SpeedPay 使用平台私钥对完整 JSON 请求体签名后的结果。商户需要使用 SpeedPay 公钥验签，验签失败时不得处理业务数据。

## 成功应答

商户处理成功后返回以下 JSON：

```json theme={null}
{
  "code": 0,
  "msg": "success"
}
```

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

## Visa 回调类型

| `api_name`                       | 说明           | 详情                                                   |
| -------------------------------- | ------------ | ---------------------------------------------------- |
| `pr_card_activation_result_push` | Visa 开卡/申请结果 | [Visa 回调](/open-api/api-list/callback/visa-callback) |
| `transaction_advice`             | Visa 交易通知    | [Visa 回调](/open-api/api-list/callback/visa-callback) |
| `change_advice`                  | Visa 卡状态变更   | [Visa 回调](/open-api/api-list/callback/visa-callback) |
| `express_advice`                 | Visa 物流信息变更  | [Visa 回调](/open-api/api-list/callback/visa-callback) |
| `mobile_advice`                  | Visa 手机号变更   | [Visa 回调](/open-api/api-list/callback/visa-callback) |
| `apply_edit_advice`              | Visa 申请资料变更  | [Visa 回调](/open-api/api-list/callback/visa-callback) |

## JCB 回调类型

| `api_name`                   | 说明          | 详情                                                      |
| ---------------------------- | ----------- | ------------------------------------------------------- |
| `jcb_card_apply_status`      | JCB 申请单状态变化 | [JCB 回调](/open-api/api-list/callback/jcb-card-callback) |
| `jcb_card_status_change`     | JCB 卡状态变更   | [JCB 回调](/open-api/api-list/callback/jcb-card-callback) |
| `jcb_card_transaction_3ds`   | JCB 3DS 验证码 | [JCB 回调](/open-api/api-list/callback/jcb-card-callback) |
| `jcb_card_block_transaction` | JCB 链上充值    | [JCB 回调](/open-api/api-list/callback/jcb-card-callback) |
| `jcb_card_transaction`       | JCB 卡片消费    | [JCB 回调](/open-api/api-list/callback/jcb-card-callback) |
| `jcb_card_block_express`     | JCB 物流信息变更  | [JCB 回调](/open-api/api-list/callback/jcb-card-callback) |
| `jcb_card_to_card`           | JCB 卡对卡转账结果 | [JCB 回调](/open-api/api-list/callback/jcb-card-callback) |
| `jcb_mobile_advice`          | JCB 手机号变更   | [JCB 回调](/open-api/api-list/callback/jcb-card-callback) |
| `jcb_email_advice`           | JCB 邮箱变更    | [JCB 回调](/open-api/api-list/callback/jcb-card-callback) |
| `jcb_card_no_advice`         | JCB 卡号变更    | [JCB 回调](/open-api/api-list/callback/jcb-card-callback) |
| `jcb_apply_edit_advice`      | JCB 申请资料变更  | [JCB 回调](/open-api/api-list/callback/jcb-card-callback) |

## 处理要求

| 要求     | 说明                                |
| ------ | --------------------------------- |
| 先验签后入库 | 使用 SpeedPay 公钥对完整 JSON 请求体进行验签    |
| 幂等处理   | 根据 `api_name`、业务流水号、交易 ID、卡号等字段去重 |
| 快速响应   | 建议验签后先落库或入队列，再异步处理重业务逻辑           |
| 保留原文   | 建议保存原始请求体、签名、处理结果和错误信息，便于排查       |