Skip to content

支付分服务用户支付成功(PAYSCORE.USER_PAID)通知(JSON)

支付分服务用户支付成功通知

注意:

  • 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。 推荐的做法是,当商户系统收到通知进行处理时,先检查对应业务数据的状态,并判断该通知是否已经处理。如果未处理,则再进行处理;如果已处理,则直接返回结果成功。在对业务数据进行状态检查和处理之前,要采用数据锁进行并发控制,以避免函数重入造成的数据混乱。
  • 如果在所有通知频率后没有收到微信侧回调,商户应调用查询订单接口确认订单状态。
  • 特别提醒:商户系统对于开启结果通知的内容一定要做签名验证,并校验通知的信息是否与商户侧的信息一致,防止数据泄露导致出现“假通知”,造成资金损失。
  • 商户退款完成后,微信会把相关退款结果和用户信息发送给清算机构,清算机构需要接收处理后返回应答成功,然后继续给异步通知到下游从业机构。
  • 对后台通知交互时,如果微信收到商户的应答不符合规范或超时,微信认为通知失败,微信会通过一定的策略定期重新发起通知,尽可能提高通知的成功率,但微信不保证通知最终能成功。(通知频率为15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - 总计 24h4m)
请求参数类型描述
headersobject通知的头参数
Content-Typestringapplication/json
Request-IDstring通知的唯一标识
Wechatpay-Noncestring数据签名使用的随机串
Wechatpay-Serialstring平台证书序列号/平台公钥ID
Wechatpay-Signaturestring签名串
Wechatpay-Signature-Typestring签名算法
WECHATPAY2-SHA256-RSA2048 枚举值
Wechatpay-Timestampstring时间戳
bodyobject通知的JSON数据结构
idstring通知的唯一ID
create_timestring通知创建的时间
event_typestring通知的类型
PAYSCORE.USER_PAID 枚举值
resource_typestring通知的资源数据类型
summarystring回调摘要
resourceobject通知资源数据
algorithmstring对数据进行加密的加密算法
AEAD_AES_256_GCM 枚举值
associated_datastring数据加密的附加数据
noncestring加密使用的随机串
ciphertextstring加密后的密文数据
original_typestring原始回调类型
service_idstring调用授权服务接口提交的服务ID。
appidstring调用授权服务接口提交的应用ID。
mchidstring调用授权服务接口提交的商户号。
sub_appidstring子商户应用ID
sub_mchidstring子商户商户号
channel_idstring调用创单接口时传入的渠道商商户号
out_order_nostring商户服务订单号
out_trade_nostring商户系统内部扣款单号
openidstring微信用户在商户对应AppID下的唯一标识。
sub_openidstring子商户公众号下的用户标识
statestring服务订单状态
service_introductionstring服务信息
total_amountnumber商户收款总金额
post_paymentsobject[]后付费项目
namestring付费项目名称
amountnumber金额
descriptionstring计费说明
countnumber付费数量
post_discountsobject[]商户优惠
namestring优惠名称
descriptionstring优惠说明
amountnumber优惠金额
risk_fundobject订单风险金
amountnumber风险金额
descriptionstring风险说明
time_rangeobject服务时间段
start_timestring服务开始时间
start_time_remarkstring服务开始时间备注
end_timestring服务结束时间
end_time_remarkstring服务结束时间备注
locationobject服务位置
start_locationstring服务开始地点
end_locationstring服务结束位置
attachstring商户数据包
order_idstring微信支付服务订单号
need_collectionboolean是否需要收款
collectionobject收款信息
statestring收款状态
total_amountnumber总收款金额
paying_amountnumber待收金额
paid_amountnumber已收金额
detailsobject[]收款明细列表
seqnumber收款序号
amountnumber单笔收款金额
paid_typestring收款成功渠道
paid_timestring收款成功时间
transaction_idstring微信支付交易单号
promotion_detailobject[]优惠功能
coupon_idstring券ID
namestring优惠名称
scopestring优惠范围
typestring优惠类型
amountnumber优惠券面额
stock_idstring活动ID
wechatpay_contributenumber微信出资
merchant_contributenumber商户出资
other_contributenumber其他出资
currencystring优惠币种
goods_detailobject[]单品列表
goods_idstring商品编码
quantitynumber商品数量
unit_pricenumber商品价格
discount_amountnumber商品优惠金额
goods_remarkstring商品备注
user_service_statusstring1、USER_OPEN_SERVICE:授权成功
2、USER_CLOSE_SERVICE:解除授权成功
openorclose_timestring服务开启/解除授权成功时间。
authorization_codestring商户系统内部授权协议号,预授权时返回,非预授权不返回。
state_descriptionstring订单状态说明
out_request_nostring调用授权服务接口提交的商户请求唯一标识(新签约的用户,且在授权签约中上传了该字段,则在解约授权回调通知中有返回)。
php
// 使用Psr标准规范,示例如何处理(取值、验签、解密)「回调通知」事件,WebServer不同,用法略有差异,供参考实现。
function webhookProcessor(\Psr\Http\Message\RequestInterface $request,
  array $platformPublicKeyMap, string $apiv3Key): array {
  if (!\count($platformPublicKeyMap)) {
    throw new \WeChatPay\Exception\InvalidArgumentException('平台证书或者平台公钥数组不能为空');
  }

  if (\strlen($apiv3Key) !== 32) {
    throw new \WeChatPay\Exception\InvalidArgumentException('APIV3密钥为32字节,长度不对');
  }

  if (!($request->hasHeader(\WeChatPay\WechatpayNonce)
    && $request->hasHeader(\WeChatPay\WechatpaySerial)
    && $request->hasHeader(\WeChatPay\WechatpaySignature)
    && $request->hasHeader(\WeChatPay\WechatpayTimestamp))) {
    throw new \WeChatPay\Exception\InvalidArgumentException('通知的头参数缺失必要参数');
  }

  // 检查通知的时间偏移量,允许5分钟之内的偏移
  [$inWechatpayTimestamp] = $request->getHeader(\WeChatPay\WechatpayTimestamp);
  if (\WeChatPay\MAXIMUM_CLOCK_OFFSET < \abs(
    \WeChatPay\Formatter::timestamp() - (int)$inWechatpayTimestamp)) {
    throw new \WeChatPay\Exception\InvalidArgumentException('通知头参数的时间偏移量超过可信阈值');
  }

  // 检查通知的平台证书/平台公钥实例是否存在
  [$inWechatpaySerial] = $request->getHeader(\WeChatPay\WechatpaySerial);
  if (!\array_key_exists($inWechatpaySerial, $platformPublicKeyMap)) {
    throw new \WeChatPay\Exception\InvalidArgumentException('通知头参数的证书序列号/公钥ID本地不存在');
  }

  // 验证通知的数据签名
  [$inWechatpaySignature] = $request->getHeader(\WeChatPay\WechatpaySignature);
  [$inWechatpayNonce] = $request->getHeader(\WeChatPay\WechatpayNonce);
  $inBody = (string)$request->getBody();
  if (!\WeChatPay\Crypto\Rsa::verify(
    \WeChatPay\Formatter::joinedByLineFeed($inWechatpayTimestamp, $inWechatpayNonce, $inBody),
    $inWechatpaySignature, $platformPublicKeyMap[$inWechatpaySerial]
  )) {
    throw new \WeChatPay\Exception\InvalidArgumentException('通知头参数的数据签名校验未通过');
  }

  // 转换通知的JSON文本消息为PHP Array数组
  $inBodyArray = (array)\json_decode($inBody, true);
  // 使用PHP7+的数据解构语法,从Array中解构并赋值变量
  ['resource' => [
    'ciphertext'      => $ciphertext,
    'nonce'           => $nonce,
    'associated_data' => $aad
  ]] = $inBodyArray;
  // 加密文本消息解密,有可能解密异常(eg: 平台探测流量)会抛 \UnexpectedValueException
  $inBodyResource = \WeChatPay\Crypto\AesGcm::decrypt($ciphertext, $apiv3Key, $nonce, $aad);
  // 把解密后的文本转换为PHP Array数组
  $inBodyResourceArray = (array)\json_decode($inBodyResource, true);
  // 把解密后的数组定义为'original_data'函数返回
  $inBodyArray['resource']['original_data'] = $inBodyResourceArray;

  return [
    'headers' => $request->getHeaders(),
    'body' => $inBodyArray
  ];
}

// do your business
// ...
// ...
$json = \json_encode([
  'code' => 'SUCCESS',
  'message' => 'OK'
]);
应答规范类型描述
statusnumberHTTP状态码
20X 4XX 5XX 枚举值之一
bodyobject应答的JSON数据结构
codestring业务处理状态码
SUCCESS | FAIL 枚举值之一
messagestring业务处理附加信息

参阅

Published on the GitHub by TheNorthMemory