> ## 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.

# Webhook 通知

> Visa 与 JCB 回调通知的接入方式。

SpeedPay 会通过 Webhook 将异步业务结果推送给商户，例如 Visa 开卡结果、Visa 交易通知、JCB 申请状态、JCB 3DS 验证码、链上充值、卡片消费、物流信息和资料变更等。

## 回调地址

商户需要在 SpeedPay 商户平台的 API KEY 配置中填写回调地址。该地址是商户系统接收 SpeedPay 回调通知的 HTTPS 地址，不是固定的平台接口路径。

## 请求头

| Header          | 说明                               |
| --------------- | -------------------------------- |
| `Content-Type`  | 固定为 `application/json`           |
| `Authorization` | SpeedPay 使用平台私钥对完整 JSON 请求体生成的签名 |

商户需要使用 SpeedPay 公钥验签。验签失败时不得处理业务数据。

## 处理要求

| 要求     | 说明                                |
| ------ | --------------------------------- |
| 先验签后入库 | 使用 SpeedPay 公钥对完整 JSON 请求体进行验签    |
| 幂等处理   | 根据 `api_name`、业务流水号、交易 ID、卡号等字段去重 |
| 快速响应   | 业务处理较重时建议先入队列，再异步处理               |
| 可追踪    | 保存原始请求体、签名、处理状态和错误信息              |

## 成功应答

商户接收到异步通知并处理成功后，需要返回以下 JSON：

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

`code` 必须为数字 `0`。

## 回调文档

| 卡组织  | 文档                                                      |
| ---- | ------------------------------------------------------- |
| Visa | [Visa 回调](/open-api/api-list/callback/visa-callback)    |
| JCB  | [JCB 回调](/open-api/api-list/callback/jcb-card-callback) |