文档
Start typing to search…

Webhook

推送通知或 webhook 允许您设置与 FuturePay 的“通知”相对应的集成。

WEBHOOK 回调接口描述

WEBHOOK 是一种让服务器能够主动向客户端发送实时事件通知的机制。当某个事件发生时，服务器会通过 POST 请求将事件数据发送到您预先配置的回调 URL（即 WEBHOOK 接口）。

1. 如何配置 WEBHOOK 回调

1.1 配置回调 URL：

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

1.2 接口请求参数中指定回调地址

如果接口和 商户管理平台 中都指定了通知地址，则接口中指定的地址优先。该参数需参与签名

{
	"webhookUrl":"https://api.futurepay-develop.com/webhook"
}

2. 接收事件通知：

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

2.1 请求头信息：

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

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

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

2.2 回调数据格式

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

参数类型描述示例
appIdString商户应用 ID1802583469172330496
merchantIdString商户 ID1802557498776006656
notificationItemsArray通知信息的数组见下表（notificationItems 数组详细说明）

2.3 notificationItems 数组详细说明

参数类型描述示例
amountObject支付金额信息见下表（amount 对象详细说明）
eventCodeString事件代码，表示发生的交易事件类型TRANSACTION、REFUND、DISPUTE
eventDateLong事件日期，时间戳格式，单位为毫秒1727603276000
merchantReferenceString商户的参考 ID，用于标识订单4BE747A411DA4D1A95EFEDF5144D80F2
paymentMethodString支付方式，表示使用的支付渠道mpesa
pspReferenceString支付服务提供商参考 ID1820355384561500160
resultCodeString交易结果，表示支付的状态SUCCEED

2.4 amount 对象详细说明

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

2.5 resultCode 字段说明

值英文描述中文含义
INITIALIZEDTransaction initialization预支付
PENDINGTrade is pending processing交易/退款处理中/需要回应
SUCCEEDTrade has been successful交易/退款成功/已赢
FAILEDTrade is failed交易/退款失败/已输
CANCELTrade has been cancelled交易已取消/已关闭
EXPIREDTrade is expired交易已过期
REFUSEDTrade has been refused交易被拒绝

3. 付款订单回调内容

{
    "appId": "2",
    "merchantId": "1",
    "notificationItems": [
        {
         "amount": {
             "currency": "USD",
             "value": 200
         },
         "eventCode": "TRANSACTION",
         "eventDate": 1761819678000,
         "merchantReference": "09E062ACC0724A4DA6EDFAB0635CB1DD",
         "paymentMethod": "intercards",
         "pspReference": "1983841542498025472",
         "resultCode": "SUCCEED",
          //additionalData 该字段为卡token支付出现 正常普通支付不会通知改字段
         "additionalData":{
         			"payToken": "08cf046b-879e-424e-bf64-36f40f8b2aa6"
         }
        }
    ],
    "providerReference": "pi_3SNsyk08pryDCbBW0oEBkPmE",
    "sign": "5b346328e8b6eea41346e573155d090b73df925e82f060ba13f9a0400618952f",
    "webhookUrl": "https://develop.futureshop.global/api/checkout/payment"
}

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

加密内容为：

{
    "notificationItems": [
        {
         "amount": {
             "currency": "USD",
             "value": 200
         },
         "eventCode": "TRANSACTION",
         "eventDate": 1761819678000,
         "merchantReference": "09E062ACC0724A4DA6EDFAB0635CB1DD",
         "paymentMethod": "intercards",
         "pspReference": "1983841542498025472",
         "resultCode": "SUCCEED",
          //additionalData 该字段为卡token支付出现 正常普通支付不会通知改字段
         "additionalData":{
         			"payToken": "08cf046b-879e-424e-bf64-36f40f8b2aa6"
         }
        }
    ]
}

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

正向订单的 WEBHOOK 加密示例

待加密的排序结果：

notificationItems=[{"amount":{"currency":"USD","value":200},"eventCode":"TRANSACTION","eventDate":1761819678000,"merchantReference":"09E062ACC0724A4DA6EDFAB0635CB1DD","paymentMethod":"intercards","pspReference":"1983841542498025472","resultCode":"SUCCEED"}]sandbox_123131231312313131118

Sign 结果：

5b346328e8b6eea41346e573155d090b73df925e82f060ba13f9a0400618952f
⚠️

若为 收银台/SDK 集成方式，可能存在多次通知情况。 例如：用户先使用支付方式 A 失败，再改用方式 B 成功，会收到两条通知，但仅有一条最终成功状态。

4. 退款订单回调内容

{
    "appId": "2",
    "merchantId": "1",
    "notificationItems": [
        {
            "amount": {
                "currency": "USD",
                "value": 200
            },
            "eventCode": "REFUND",
            "eventDate": 1761819822000,
            "merchantReference": "1983842227570511872",
            "originalReference": "1983841542498025472",
            "paymentMethod": "intercards",
            "pspReference": "1983842228308672512",
            "resultCode": "SUCCEED"
        }
    ],
    "providerReference": "re_3SNsyk08pryDCbBW0wiDg2km",
    "sign": "844157f02c7c66f30137bc8a663e44c778372d0bc4432d25577959d23b706ddb",
    "webhookUrl": "https://develop.futureshop.global/api/checkout/payment"
}

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

加密内容为：

{
    "appId": "2",
    "merchantId": "1",
    "notificationItems": [
        {
            "amount": {
                "currency": "USD",
                "value": 200
            },
            "eventCode": "REFUND",
            "eventDate": 1761819822000,
            "merchantReference": "1983842227570511872",
            "originalReference": "1983841542498025472",
            "paymentMethod": "intercards",
            "pspReference": "1983842228308672512",
            "resultCode": "SUCCEED"
        }
    ]
}

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

退款订单的 WEBHOOK 加密示例

待加密的排序结果：

appId=2&merchantId=1&notificationItems=[{"amount":{"currency":"USD","value":200},"eventCode":"REFUND","eventDate":1761819822000,"merchantReference":"1983842227570511872","originalReference":"1983841542498025472","paymentMethod":"intercards","pspReference":"1983842228308672512","resultCode":"SUCCEED"}]sandbox_123131231312313131118

Sign 结果：

844157f02c7c66f30137bc8a663e44c778372d0bc4432d25577959d23b706ddb

5. 争议订单回调内容

{
    "appId": "2",
    "merchantId": "1",
    "notificationItems": [
        {
            "amount": {
                "currency": "USD",
                "value": 7990
            },
            "eventCode": "DISPUTE",
            "eventDate": 1763364118000,
            "merchantReference": "23E5D0DFF7A3491284214111E14070FC",
            "originalReference": "1990319291932737536",
            "pspReference": "1990319484518416384",
            "resultCode": "SUCCEED"
        }
    ],
    "providerReference": "1990319389018411008",
    "sign": "51d5fc00abdf06f53de914d2caccd32c1edb033cb9467fc1adb33c5eee8e3d8b",
    "webhookUrl": "https://develop.futureshop.global/api/checkout/payment"
}

加密内容为：

{
    "appId": "2",
    "merchantId": "1",
    "notificationItems": [
        {
            "amount": {
                "currency": "USD",
                "value": 7990
            },
            "eventCode": "DISPUTE",
            "eventDate": 1763364118000,
            "merchantReference": "23E5D0DFF7A3491284214111E14070FC",
            "originalReference": "1990319291932737536",
            "pspReference": "1990319484518416384",
            "resultCode": "SUCCEED"
        }
    ]
}

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

争议订单的 WEBHOOK 加密示例

待加密的排序结果：

notificationItems=[{"amount":{"currency":"USD","value":7990},"eventCode":"DISPUTE","eventDate":1763364118000,"merchantReference":"23E5D0DFF7A3491284214111E14070FC","originalReference":"1990319291932737536","pspReference":"1990319484518416384","resultCode":"SUCCEED"}]11111111111111111111111111111111

Sign 结果：

51d5fc00abdf06f53de914d2caccd32c1edb033cb9467fc1adb33c5eee8e3d8b

6. 商户响应要求 ✅

商户在成功处理回调后，必须返回：

success

系统收到此响应后将停止重试。 若返回其他内容或响应超时，系统会自动进行 最多 10 次重试（间隔时间指数递增）。


Updated 4 days ago