支付通知（订阅）

如何配置支付通知回调

1.配置回调 URL：

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

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` 数组详细说明

参数	类型	描述	示例
`additionalData`	Object	订阅计划信息	见下表（`additionalData` 对象详细说明）
`amount`	Object	支付金额信息	见下表（`amount` 对象详细说明）
`eventCode`	String	事件代码，表示发生的交易事件类型	`TRANSACTION、REFUND`
`eventDate`	Long	事件日期，时间戳格式，单位为毫秒	`1727603276000`
`merchantReference`	String	商户的参考 ID，用于标识订单	`4BE747A411DA4D1A95EFEDF5144D80F2`
`paymentMethod`	String	支付方式，表示使用的支付渠道	`mpesa`
`pspReference`	String	支付服务提供商参考 ID	`1820355384561500160`
`resultCode`	String	交易结果，表示支付的状态	`SUCCEED`

2.3`additionalData` 对象详细说明

参数	类型	描述	示例
`productsId`	String	订阅产品ID	1914583135190953984
`productsName`	String	订阅产品名称	测试计划
`subscriptionType`	String	订阅扣款类型	`trial`（试用期扣款）`subscription`（正式期扣款）
`consumerId`	String	消费者ID	USER-10002
`subscriptionCount`	String	订阅扣款期数	1
`customerName`	String	消费者姓名	Auto-Debit-Customer

2.4 `amount` 对象详细说明

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

{
    "appId": "2",
    "merchantId": "1",
    "notificationItems": [
        {
            "additionalData": {
                "productsId": "1914583135190953984",
                "subscriptionType": "trial",
                "consumerId": "USER-10002",
                "subscriptionCount": "1",
                "customerName": "Auto-Debit-Customer",
                "productsName": "测试计划"
            },
            "amount": {
                "currency": "USD",
                "value": 100
            },
            "eventCode": "SUBSCRIPTION_TRANSACTION",
            "eventDate": 1745393855000,
            "merchantReference": "1914946722543566848",
            "paymentMethod": "alipaycn",
            "pspReference": "1914946730495967232",
            "reason": "UAT 生产测试代扣",
            "resultCode": "SUCCEED"
        }
    ]
}

您需要对 notificationItems 部分进行加密验签，确保其数据的完整性和安全性。如果签名匹配，说明数据是有效且未被篡改，您可以继续处理这个回调请求。

加密内容为：

{
  "notificationItems": [
        {
            "additionalData": {
                "productsId": "1914583135190953984",
                "subscriptionType": "trial",
                "consumerId": "USER-10002",
                "subscriptionCount": "1",
                "customerName": "Auto-Debit-Customer",
                "productsName": "测试计划"
            },
            "amount": {
                "currency": "USD",
                "value": 100
            },
            "eventCode": "SUBSCRIPTION_TRANSACTION",
            "eventDate": 1745393855000,
            "merchantReference": "1914946722543566848",
            "paymentMethod": "alipaycn",
            "pspReference": "1914946730495967232",
            "reason": "UAT 生产测试代扣",
            "resultCode": "SUCCEED"
        }
    ]
}

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

5.回调内容说明

收到通知消息后，请回应 success 以确认成功接收。

如何配置 支付通知 回调