退款WEBHOOK

如何配置 WEBHOOK 回调

1.配置回调 URL：

在您的商户管理平台上的开发者菜单，您需要提供一个可接收回调数据的 URL。这是您的服务器端接收 WEBHOOK 请求的地址。

2.接收事件通知：

每当触发某个事件时（如退款成功、退款失败等），我们的系统会向您提供的回调 URL 发送一个 HTTP POST 请求。请求的主体将包含事件的详细信息，通常为 JSON 格式。

3.请求头信息：

在接收到的 POST 请求中，您需要验证请求的有效性。您可以使用以下信息来校验请求：

Content-Type: application/json
Authorization: 24be30a26b05f284a3a838abcaabcfc44fd7d02c2622a9d0d7efcaa2b21f12f2 --这是用于验证请求来源和完整性的签名，确保回调请求的安全性。
merchantId: 11122333 --户的唯一标识符
appId: 1 --应用的唯一标识符
curTime: 1735279386000 --回调请求的时间戳

说明：
Content-Type: application/json 表示请求体是 JSON 格式。 Authorization: 是一个签名字符串，用于验证请求的合法性。 merchantId: 表示商户的唯一标识。 appId: 表示应用的唯一标识。 curTime: 表示当前时间戳。

4.回调数据格式

接收到的回调请求主体通常会包括以下字段：

参数	类型	描述	示例
`appId`	String	商户应用 ID	`1802583469172330496`
`merchantId`	String	商户 ID	`1802557498776006656`
`notificationItems`	Array	通知信息的数组	见下表（`notificationItems` 数组详细说明）

2.2 `notificationItems` 数组详细说明

参数	类型	描述	示例
`amount`	Object	支付金额信息	见下表（`amount` 对象详细说明）
`eventCode`	String	事件代码，表示发生的交易事件类型	`REFUND`
`eventDate`	Long	事件日期，时间戳格式，单位为毫秒	`1727603276000`
`merchantReference`	String	商户的参考 ID，用于标识订单	`4BE747A411DA4D1A95EFEDF5144D80F2`
`paymentMethod`	String	支付方式，表示使用的支付渠道	`mpesa`
`pspReference`	String	支付服务提供商参考 ID	`1820355384561500160`
`originalReference`	String	退款订单原支付平台订单号	`1928000058213662720`
`reason`	String	退款失败/成功原因	`payment in process`
`resultCode`	String	交易结果，表示支付的状态	`SUCCEED`

2.3 `amount` 对象详细说明

参数	类型	描述	示例
`currency`	String	支付金额的货币类型	`KES` (肯尼亚先令)
`value`	Integer	支付金额的数值，单位为货币的最小单位（例如分、厘等）	`100`

{
    "appId": "2",
    "merchantId": "1",
    "notificationItems": [
        {
            "amount": {
                "currency": "HKD",
                "value": 1
            },
            "eventCode": "REFUND",
            "eventDate": 1743407280000,
            "merchantReference": "1906612899628093440",
            "originalReference": "1906612322743484416",
            "paymentMethod": "alipayhk",
            "pspReference": "1906612899669999616",
            "reason": "payment in process",
            "resultCode": "SUCCEED"
        }
    ]
}

加密内容为：

{
    "appId": "2",
    "merchantId": "1",
    "notificationItems": [
        {
            "amount": {
                "currency": "HKD",
                "value": 1
            },
            "eventCode": "REFUND",
            "eventDate": 1743407280000,
            "merchantReference": "1906612899628093440",
            "originalReference": "1906612322743484416",
            "paymentMethod": "alipayhk",
            "pspReference": "1906612899669999616",
            "reason": "payment in process",
            "resultCode": "SUCCEED"
        }
    ]
}

将加密后的签名与请求头中的 Authorization 字段值进行比对，确认是否一致。