webhooks通知

什么是webhooks通知？

通过配置 webhooks，商户可订阅需要的事件，当这些事件发生时，Paymax会将对应的事件消息推送到商户指定的地址。Paymax现支持如下webhooks：

  • 支付结果通知
  • 退款结果通知

如何订阅

  1. 从应用列表里点击某应用

应用中心

  1. 点击左侧导航中webhooks

webhooks通知 - 图2

  1. 点击右上角添加按钮，开始添加webhooks

webhooks通知 - 图3

可靠通知规则

由于网络等原因，商户可能未接收或未正常处理webhooks通知，Paymax会通过一定重发机制来保证通知的可靠性。

Paymax是否重发，取决于商户收到通知后response的结果是否为success字符串。若不是，才会按照一定机制重发，直到收到success为止。

当然，Paymax重发的时间间隔也会随着重发次数逐步变长。

对后台通知交互时，如果Paymax收到商户的应答不是成功或超时（正常的response是：http code 200 && content 为 success），Paymax认为通知失败，在36小时之内，一共发送17次，第一次发送失败之后，之后每次发送的间隔为：2s,4s,8s,16s,32s,64s,128s,256s,512s,1024s,2048s,4096s,8192s,16384s,32768s,65536s

通知格式

支付示例

  2.  {
  3.     "data":{
  4.         "amount":7,
  5.         "amount_refunded":0,
  6.         "amount_settle":0,
  7.         "body":"测试商品",
  8.         "client_ip":"120.197.202.48",
  9.         "credential":{
  10.             "wechat_wap":{
  11.                 "jsApiParams":"{"appId":"wxbtest9e022e2d07","timeStamp":"1478361807","signType":"MD5","package":"prepay_id=test211060003265e6f4f86970458446dd081","nonceStr":"06ZSHzTTeswakmu4","paySign":"BB4706E3F97174AAC1341F25dssw88DA16"}"
  12.             }
  13.         },
  14.         "currency":"CNY",
  15.         "description":"测试商品描述信息",
  16.         "extra":{
  17.             "terminal_id":"9223131",
  18.             "open_id":"oOOL0jdyiLwslASo7UmSwrtOCW4k",
  19.             "merchant_id":"8221023420011716"
  20.         },
  21.         "id":"ch_5d0eca3b8f707ed425122e56",
  22.         "livemode":false,
  23.         "metadata":{
  24.             "callbackUrl":"http://www.demo.com"
  25.         },
  26.         "order_no":"ch_828d6ef97f3c45a3acd41a59",
  27.         "refunds":[
  29.         ],
  30.         "status":"SUCCEED",
  31.         "subject":"测试商品标题",
  32.         "time_created":1478361807000,
  33.         "time_expire":1478362046272,
  34.         "time_paid":1478361806000,
  35.         "transaction_no":"4004512001201611068876533536"
  36.     },
  37.     "notifyNo":"evt_7fb2378f457ewerwa9afe17a942ae389e",
  38.     "timeCreated":1478361840304,
  39.     "type":"CHARGE"
  40. }

退款示例

  2.  {
  3.     "data":{
  4.         "amount":0.01,
  5.         "charge":"ch_6abba29e41edddd8b062dab",
  6.         "description":"协商一致退款",
  7.         "extra":{
  8.             "refundUrl":"http://www.demo.com/gateway.do?sign=251af6477bxxxxxxx"
  9.         },
  10.         "id":"re_06cfeewewe4dc14de10fe",
  11.         "metadata":{
  12.             "use_id":"12345678"
  13.         },
  14.         "order_no":"06cf59c008b004dc14de10fe",
  15.         "status":"SUCCEED",
  16.         "time_created":1478518692000,
  17.         "time_succeed":1478518705000,
  18.         "transaction_no":"2016110721001004480236849549"
  19.     },
  20.     "notifyNo":"evt_eff98bb453f0429b9b8fd5adfasdfc7c9",
  21.     "timeCreated":1478518708532,
  22.     "type":"REFUND"
  23. }

参数说明

参数 类型 描述
data Charge对象或者Refund对象 详情见 API文档 中对Charge对象、Refund对象的说明
notifyNo String 通知事件唯一标识
timeCreated Long 时间戳，自1970年以后的毫秒数
type String 通知类型，共以下几种:
CHARGE : 支付
REFUND : 退款

如何验签

每一次事件通知，Paymax都会对request body整体做签名，并将签名后的结果放request header中，header名称sign。

签名算法为SHA1WithRSA，签名时会使用Paymax官方私钥做签名，所以商户验签时需要用Paymax官方公钥来做验签。

Paymax官方公钥可通过商户后台“开发信息”中获取。