1. 交易通知及对账
星驿支付文档中心
  • AI快速对接
    • xypay-skills使用说明
  • 文档说明
    • 阅读对象
    • 版本说明
  • 术语
    • 支付模式
    • 名词解释
    • 支付产品
      • 付款码支付
      • 聚合码支付
      • PC支付
      • 小程序支付
        • 支付宝小程序支付
        • 微信小程序支付
      • APP支付
        • 微信支付
        • 支付宝支付
      • H5支付
        • 微信H5支付
        • 支付宝H5支付
        • 云闪付H5支付
        • 手机浏览器H5支付
      • Native支付
        • 支付宝支付
        • 云闪付支付
      • 终端支付
        • 智能云MIS
        • 智能APP
  • 接口规则
    • 协议规则
    • 常见问题
    • 安全规范
  • 支付交易
    • 交易前指引
      • 微信认证操作流程
      • 支付宝认证操作流程
      • H5页面微信支付对接前准备
      • H5页面支付宝支付对接前准备
      • 支付流程
      • 支付接入注意事项
      • 消费者IP获取指引
      • 微信小程序资金管控操作指南
    • 基础支付
      • 付款码支付
      • JSAPI支付
      • 订单查询
      • 扫码支付-星驿码
      • 扫码支付-官方码
      • 扫码支付-场景码
      • 关闭订单
      • 撤销订单
      • 退款
      • 退款查询
      • 授权码查询openid
      • 获取微信刷脸凭证
      • 获取银联用户标识
      • 风控ip检查
    • 半屏小程序支付
      • 使用说明
      • 小程序半屏-星驿付
      • 小程序半屏-场景
    • 扫码预授权
      • 扫码预授权
      • 预授权查询
      • 预授权撤销
      • 预授权撤销查询
      • 预授权完成
      • 预授权完成查询
      • 预授权完成撤销
      • 预授权完成撤销查询
    • 订单推送
      • 推送终端交易
      • 关闭推送终端交易
      • 碰一下推单状态查询
      • 碰一下订单取消
      • 碰一下订单推送
    • 智能终端SDK
      • 智能终端SDK
    • 交易通知及对账
      • 交易对账文件-场景应用
        GET
      • 交易对账文件-ISV
        GET
      • 交易和退款结果通知
        POST
      • 交易手续费通知
        POST
      • 后返对账文件-ISV
        GET
    • 刷卡预授权
      • 预授权完成撤销
      • 预授权撤销
    • 行业开票
      • 开票申请
      • 发票冲红
      • 发票结果查询
      • 发票结果通知
  • 商户管理
    • 进件前指引
      • 进件说明
      • 图片示例
      • 微信认证操作流程
      • 支付宝认证操作流程
      • 附件下载
    • 商户入网
      • 商户进件上传图片
      • 普通商户进件
      • 普通商户信息修改
      • 小微商户进件
      • 小微商户信息修改
      • 审核结果查询
      • 商户审核结果通知
      • 待审核商户撤回
      • 商户信息查询
      • 结算卡修改
      • 商户快捷修改
      • 受益人信息查询
      • 商户报备查询
      • 商户报备结果通知
      • 商户状态修改
      • 终端报备查询
      • 商户阶梯费率配置
      • 商户阶梯费率查询
    • 商户协议签约
      • 入网协议签约接口调用流程
      • 普通商户用户开户
      • 小微商户用户开户
      • 发短信验证码
      • 获取签约链接
      • 校验验证码
      • 校验验证码-补签
      • 签约结果通知
    • 微信支付宝认证
      • 微信申请单提交
      • 微信申请单撤销
      • 微信申请单状态查询
      • 微信商户授权状态查询
      • 支付宝申请单提交
      • 支付宝申请单撤销
      • 支付宝申请单状态查询
      • 支付宝商户授权状态查询
    • 商户开发配置
      • 绑定APPID配置
      • 微信支付目录配置
      • 微信公众号查询
      • 商户开发配置查询
      • 重发报备
      • 微信小程序冻结状态查询
      • 微信小程序冻结通知(非接口)
    • 商户限额调整
      • 商户限额查询
      • 商户提额申请
      • 商户提额记录查询
    • 商户风险处置
      • 商户风险处置通知
      • 风险商户图片上传
      • 微信官方风险商户文件
      • 支付宝官方风险商户文件
      • 风险商户异常流水查询
      • 风险商户调查列表
      • 风险商户调查详情
      • 风险调查单历史查询
      • 风险调查材料下载
      • 风险调查单处理
    • 商户手续费开票
      • 开具发票
      • 开票详情
      • 待开发票信息查询
      • 合并开票商户信息查询
      • 电子普票重发邮箱
      • 开票历史查询
    • 无界收款
      • 无界收款图片上传
      • 无界收款开通
      • 无界收款审核查询
      • 无界收款审核结果通知
  • 资金结算
    • D0开通及提现相关问题Q&A
    • D0结算业务
      • 产品介绍
      • 获取人脸识别链接
      • 人脸认证结果查询
      • D0开通
      • D0信息修改
      • D0状态查询
      • D0开通失败申诉
      • D0申诉结果查询
      • D0申诉结果通知
    • 特殊结算业务
      • 产品介绍
      • 结算业务申请
      • 结算业务变更
      • 结算业务结果查询
      • 结算业务结果通知
    • 提现查账
      • 手工提现
      • 到账记录查询
      • 到账记录批量查询
      • 秒到提现记录查询
      • 账户余额查询
      • 挂账记录查询
      • 补付申请
      • 提现结果通知
      • 账户余额变动通知
      • 提现对账文件
      • 批量结算提现通知
      • 到账附言配置
      • 查询到账附言
  • 星账云管家
    • 星账云管家
    • 功能开通
      • 功能开通(XZY001)
      • 编辑(XZY003)
      • 编辑上传付款凭证(XZY002)
      • 修改生效状态(XZY004)
      • 查询详情信息(XZY005)
      • 产品开通审核通知(XZY006)
    • 公共接口
      • 上传文件(XZY013)
    • 分账
      • 交易
        • 分账结算电子回单下载(XZY037)
        • 余额查询接口(XZY041)
        • 分账结果回调(XZY016)
        • 分账合并入账电子回单下载(XZY039)
        • 订单查询(XZY015)
        • 分账(XZY014)
        • 完结分账(XZY040)
        • 查询交易订单分账金额信息(XZY041)
        • 分账撤销退回(XZY017)
      • 客户管理
        • 新增客户(XZY018)
        • 分账授权申请接口-收单统一结算(XZY043)
        • 批量分账授权申请接口-收单统一结算(XZY044)
        • 合作状态调整(XZY020)
        • 解约/重启签约(XZY-001-002)
        • 编辑客户(XZY023)
        • 替换客户结算卡(XZY022)
        • 审核通知(XZY019)
        • 查询分账客户信息(XZY021)
    • 归集
      • 开户/授权
        • 归集授权申请接口-收单统一结算(XZY037)
        • 审核通知(XZY025)
        • 合作状态调整(XZY026)
        • 查询归集客户信息(XZY027)
        • 替换结算卡(XZY028)
        • 编辑信息(XZY029)
      • 交易
        • 归集合并入账电子回单下载(XZY040)
        • 归集结算电子回单下载(XZY038)
        • 余额查询接口(XZY042)
        • 订单查询(XZY031)
        • 归集(XZY030)
        • 归集结果回调(XZY032)
        • 归集撤销退回(XZY033)
    • 提现
      • 提现订单查询(XZY035)
      • 结算回调通知(XZY050)
      • 提现电子回单下载(XZY040)
      • 提现(XZY036)
    • 账户
      • 结算资金流水查询(XZY047)
      • 结算卡资金流水查询(XZY049)
  • 设备管理与推送
    • 设备管理
      • 收款设备绑定
      • 收款设备解绑
      • 收款设备绑定查询
      • 设备绑定/解绑结果通知
      • 音箱绑定
      • 音箱绑定查询
      • 音箱解绑
      • 设备信息修改
    • 设备推送
      • 音箱播报
      • 交易打印
  • 营销活动
    • 银行活动
      • 产品介绍
      • 图片上传
      • 商户补贴额度列表查询
      • 银行活动报名
      • 银行活动报名结果查询
      • 银行活动报名结果通知
      • 银行活动列表查询
      • 银行活动退出
    • 特殊行业活动
      • 产品介绍
      • 特殊行业活动报名申请
      • 特殊活动报名结果通知
      • 特殊行业商户活动查询
      • 特殊行业活动图片上传
    • 综合账户
      • 营销增资-订单
      • 营销增资-金额
      • 营销增资查询
      • 综合账户余额查询
      • 综合账户流水查询
      • 撤销营销增资-金额
    • 支付宝分期商家贴息
      • 贴息活动报名配置
      • 查询贴息活动
      • 修改活动里的费率
      • 贴息活动取消报名
      • 贴息活动商户列表查询
    • 增值服务
      • 获取增值营销产品列表
      • 获取增值营销产品明细
      • 获取分享链接
      • 推广结果列表查询
      • 推广结果详情
  • 慧徕店开放平台
    • 慧+SPI
      • 对接前准备
      • 商户同步
        • 开发配置
          • 请求域名
          • 加签&验签
        • 商户同步
        • 商户同步查询
        • 商户同步回调
      • 应用模块
        • 产品介绍
        • 开发配置
          • 请求域名
          • 加签&验签
        • 应用及增值服务列表查询
        • 商户应用注册及增值服务状态查询
        • 应用注册
        • 应用注册状态查询
        • 应用注册回调通知
        • 增值服务激活
        • 增值服务激活状态查询
        • 增值服务激活回调通知
      • 聚合支付SPI
        • 产品介绍
        • 开发配置
          • 签名方式
          • 公共参数
          • 验签方式
        • 支付API
        • 付款码支付
        • 扫码支付-官方码
        • JSAPI支付
        • 扫码支付-聚合码
        • 微信半屏小程序支付
        • 订单查询
        • 交易结果通知
        • 退款
        • 退款查询
        • 关闭订单
        • 获取银联用户标识
        • 公共参数
    • 应用开发API
      • 验签说明
      • 应用支付
      • 门店信息同步
      • 门店增值服务激活
  • 微信物业缴费
    • 小区楼房信息推送
    • 用户账单信息同步
    • 用户账单信息删除
    • 物业缴费订单查询
    • 代扣申请签约/解约通知
    • 代扣申请签约/解约结果同步
    • 微信代扣信息同步
    • 申请代扣扣费
  • 支付广告
    • SDK资源文件
    • 微信小程序广告
    • 支付宝小程序广告
    • 支付宝H5广告
  • 数据字典
    • MCC
      • 搜索查询二级mcc
      • 获取一级mcc目录
      • 获取二级mcc目录
    • 地区码
      • 获取省
      • 获取市
      • 获取区县
    • 落地银行
      • 落地银行查询
      • 落地银行下级机构查询
    • 银行信息
      • 获取银行省信息-联行号
      • 获取银行市信息-联行号
      • 银行信息查询
      • 查询联行号信息
      • 根据银行卡号获取银行信息
    • 连锁品牌
      • 获取连锁品牌信息
  • 分账服务
    • 订单分账
      • 订单分账
      • 订单分账结果查询
      • 订单分账撤销
      • 订单分账对帐文件
    • 余额分账
      • 余额分账
      • 余额分账结果查询
      • 可分账余额查询
    • 分账配置
      • 分账图片上传
      • 分账商户配置
      • 分账商户配置结果查询
      • 分账商户配置结果通知
      • 分账商户移除
      • 快捷创建资金接收方
      • 修改分账比例与金额
      • 商圈信息查询
  • 数据模型
    • PostPayRsp?
    • CompAccSubDocFileResponse
    • TermInfo
    • FileHeader
    • TitokDishItem
    • CompAccSubSumVo
    • CompAccSubDocRow
    • IsvRspListTermInfo
    • FileBody
    • TitokDataUploadReq
    • CompAccSubSumRow
    • GetTermInfoReq
    • StandardResponse
    • RunResultVo
    • ErrorResponse
  1. 交易通知及对账

交易和退款结果通知

测试环境
https://xyf-server-test.postar.cn
测试环境
https://xyf-server-test.postar.cn
POST
/服务商的异步通知地址
使用场景:商户、ISV、应用开发者

简介#

请注意:邮驿付&星驿付后期会对返回参数保留扩展的权力,扩展方式为新增参数但不会删除参数,请商户在解析邮驿付&星驿付返回参数时要支持邮驿付&星驿付可能扩展参数这种情况。
返回值格式:所有异步通知返回参数均为 JSON 对象,且必须包含 "rspCod" 和 "rspMsg" 字段。
注意:返回的是对象,非字符串,rspMsg必须是一级参数。示例:{"rspCod":"","rspMsg":"success"}。
通知范围:只有支付成功和退款才会通知,支付失败,关单,撤单都没有通知
重试机制:若首次通知失败,平台将按照以下间隔重复推送,共推送 10 次:
10s → 15s → 30s → 1m → 5m → 10m → 30m → 1h → 1h → 3h
重要:商户在成功接收通知后,必须在响应中返回 "rspMsg":"success",否则平台会持续重试直至耗尽 10 次机会。
由于网络异常、系统波动等原因,可能会存在用户支付成功、但是商户侧未能成功接收到支付结果异步通知的情况。这将会导致商户获取不到支付结果、用户订单显示为未支付,用户体验差且易造成客诉。
为杜绝以上问题,需要商户同时接入支付结果异步通知与订单查询接口。当商户侧未收到支付结果异步通知时,必须调用 /yyfsevr/order/orderQuery(订单查询接口)查询订单的支付结果。
b扫c需要输入密码的情况下,支付成功后通道也不会回调给星驿付,我们也是定时去通道查支付状态,查到成功后再回调给服务商,这种情况回调会有延时(1至2分钟不等),没法实时,可以接入订单查询接口,短时定时来调接口查订单状态,这样时效性好一些。

使用说明#

一、基本规则#

1.
报备要求:所有异步通知地址必须提前向运营人员报备,否则无效。
2.
运营后台配置(机构层的配置,只对当个机构生效):
默认异步通知地址:必配项,只有配置了该地址才会触发异步通知。
多异步通知地址列表:可选配置,可配置多个通知地址,用于根据业务规则推送不同地址。
3.
推送地址规则:
接口未上传异步通知地址/官品扫码刷卡 → 推送到默认异步通知地址。
接口上传了异步通知地址 → 将该地址与多异步通知地址列表进行路径匹配:
若匹配成功(地址已报备),则推送到接口上传的地址。
若匹配失败,则推送到默认异步通知地址。

二、环境差异说明#

测试环境#

服务商提供异步通知地址给运营报备后,可直接使用。
接口可不传地址(走默认)或显式上传自己的地址(需符合推送规则)。
后台配置的地址为服务商提供的原始地址。

生产环境#

服务商提供原始异步通知地址给运营报备后,运营会返回一个映射后的内网地址(仅星驿付服务器可访问,但对服务商而言等价于原始地址)。
后台配置的地址均为映射后的地址。
接口若显式上传异步通知地址,必须上传映射后的地址,否则无法匹配多地址列表,最终会走默认地址。
推送时,星驿付会将请求发往映射后的内网地址,但服务商收到的是对应原始地址的请求(由内部映射机制保证)。

三、配置与推送示例#

测试环境示例#

假设服务商有以下三个原始地址:
https://www.postar.cn/notify
https://pay.postar.cn/notify1
https://pay.postar.cn/notify2

场景1:默认地址为空,多地址列表为空#

无论接口是否上传地址,均不触发通知。

场景2:默认地址为 https://www.postar.cn/notify,多地址列表为空#

接口不上传地址 → 推送至 https://www.postar.cn/notify
接口上传 https://www.postar.cn/notify → 推送至 https://www.postar.cn/notify
接口上传其他地址(如 https://pay.postar.cn/notify1)→ 仍推送至 https://www.postar.cn/notify

场景3:默认地址为 https://www.postar.cn/notify,多地址列表包含 https://pay.postar.cn/notify1、https://pay.postar.cn/notify2#

接口不上传地址 → 推送至 https://www.postar.cn/notify
接口上传 https://www.postar.cn/notify → 推送至 https://www.postar.cn/notify
接口上传 https://pay.postar.cn/notify1 → 推送至 https://pay.postar.cn/notify1
接口上传 https://pay.postar.cn/notify2 → 推送至 https://pay.postar.cn/notify2
接口上传未报备地址(如 https://pay.postar.cn/notify3)→ 推送至 https://www.postar.cn/notify

生产环境示例(普通地址)#

原始地址与映射后地址对应关系:
https://www.postar.cn/notify → http://192.168.130.163:8009/yyfToIsvcs/notify
https://pay.postar.cn/notify1 → http://192.168.130.163:8009/yyfToIsvcspay/notify1
https://pay.postar.cn/notify2 → http://192.168.130.163:8009/yyfToIsvcspay/notify2

场景1:默认地址为空,多地址列表为空#

不触发通知。

场景2:默认地址为 http://192.168.130.163:8009/yyfToIsvcs/notify,多地址列表为空#

无论接口上传何种地址(或不上传),最终推送至原始地址 https://www.postar.cn/notify。

场景3:默认地址为 http://192.168.130.163:8009/yyfToIsvcs/notify,多地址列表包含 http://192.168.130.163:8009/yyfToIsvcspay/notify1、http://192.168.130.163:8009/yyfToIsvcspay/notify2#

接口不上传地址 → 推送至 https://www.postar.cn/notify
接口上传原始地址(如 https://www.postar.cn/notify、https://pay.postar.cn/notify1 等)→ 因与多地址列表不匹配,推送至 https://www.postar.cn/notify
接口上传映射后地址:
上传 http://192.168.130.163:8009/yyfToIsvcspay/notify1 → 推送至 https://pay.postar.cn/notify1
上传 http://192.168.130.163:8009/yyfToIsvcspay/notify2 → 推送至 https://pay.postar.cn/notify2
上传未在多列表中的映射地址 → 推送至默认地址

四、动态异步通知地址配置#

星驿付支持动态地址,即路径中包含可变部分(如订单号),例如:
https://www.postar.cn/notify/20260318101800
https://www.postar.cn/notify/20260318101801
注意事项:
如需使用动态地址,报备时必须告知运营,否则运营不会配置支持。
动态地址的匹配规则:只要接口上传的地址前缀与多地址列表中某条记录匹配(即域名+固定路径部分一致),则视为匹配成功,后续动态部分可任意变化。

生产环境动态地址示例#

原始地址与映射后地址对应关系:
https://www.postar.cn/notify → http://192.168.130.163:8009/yyfToIsvcs/notify(固定地址)
https://pay.postar.cn/ → http://192.168.130.163:8009/yyfToIsvcspay/(动态地址,前缀匹配)
https://cust.postar.cn/notify → http://192.168.130.163:8009/yyfToIsvcscust/notify(固定地址)

场景1:默认地址为空,多地址列表为空#

不触发通知。

场景2:默认地址为 http://192.168.130.163:8009/yyfToIsvcs/notify,多地址列表为空#

所有通知推送至 https://www.postar.cn/notify。

场景3:默认地址为 http://192.168.130.163:8009/yyfToIsvcs/notify,多地址列表包含 http://192.168.130.163:8009/yyfToIsvcspay/、http://192.168.130.163:8009/yyfToIsvcscust/notify#

接口不上传地址 → 推送至 https://www.postar.cn/notify
接口上传原始地址(如 https://www.postar.cn/notify、https://pay.postar.cn/notify1、https://cust.postar.cn/notify/xxx 等)→ 因与多地址列表(映射后地址)不匹配,推送至默认地址
接口上传映射后地址:
上传 http://192.168.130.163:8009/yyfToIsvcspay/notify1 → 推送至 https://pay.postar.cn/notify1(匹配前缀 http://192.168.130.163:8009/yyfToIsvcspay/)
上传 http://192.168.130.163:8009/yyfToIsvcspay/notify2 → 推送至 https://pay.postar.cn/notify2
上传 http://192.168.130.163:8009/yyfToIsvcspay/notify/20260318101800 → 推送至 https://pay.postar.cn/notify/20260318101800(动态部分任意)
上传 http://192.168.130.163:8009/yyfToIsvcscust/notify → 推送至 https://cust.postar.cn/notify
上传未匹配任何列表前缀的映射地址 → 推送至默认地址

五、总结#

核心原则:所有通知地址必须报备;生产环境使用映射地址进行配置和上传;动态地址需提前声明。
推送优先级:接口上传地址若匹配多地址列表 → 使用该地址;否则使用默认地址;默认地址未配置则无通知。
环境差异:测试环境使用原始地址,生产环境使用映射地址,但最终服务商收到的请求均为原始地址格式。

异步返回结果验签#

假设接收到通知的示例如下:
注意:以下示例报文仅供参考,实际返回的详细报文请以实际返回为准。
{"WX_AGET_SUBSIDY":"0","CUST_ID":"60000012628620","AGET_CUST_ID":"61000000582957","MEDIATYPE":"","POS_VOUCHERNO":"hi9njr","THREE_ORDER_NO":"2511042491723721","sign":"YZBvY7CN18RPi6wX/UeAhOO+/5F/zjgVRGbgfUoShnUui3xweD8TxPwT07+rYoz8q9XpsdQ7jTLBibK2rIevb6ojaq5FJcgbZke/IGOIJjLiEviQ7dGiU9xBQ3SUVyPEibxVHlMfzbo7PlxORjF2hvNlSXIB8o8vp0pvXVN99+PGZqyyksi1PDfPDiVJZdZX4uGy+S7//NXGaJTE2669g8FMSRadsc2wdaW/flMjb0kvI8BZhjvZVN8vohaBu1aoCufyUJqwcDtpvR9o5qA9txJQfJdwaddZdvzymJAZkWLmllXr4mzgMyU5bZefGTf8Fu2ydN7h00/PyMC32HxWXg==","CARD_TYPE":"01","OLD_FEE":"0","ORDER_NO":"20251104CChi9njr","ACTUAL_PAY_AMT":"2","T_ORDER_NO":"20251104CChi9njr","AGET_ID":"61000000582957","WX_CUST_SUBSIDY":"0","TERM_FEE":"0","ORDER_STATUS":"1","POS_PAY_WAY":"","CODE_AGE_AMT":"0","DISCOUNT_FEE":"0","BANK_CODE":"CCB_DEBIT","ORD_TYPE":"","SREF_NO":"","PAY_CHANNEL":"2","REFUND_DIS_AMT":"","DISCOUNT_FLAG":"0","LIMIT_FEE":"0","DEBT_STATE":"20251104","PAY_WAY":"8","OLD_TXAMT":"2","TRAN_TYPE_SER":"01","CODE_AMT":"0","TXAMT":"2","SUB_OPEN_ID":"oBY7i5WShNImAoHaKuY6zmu-gAc8","NETR_AMT":"2","OPEN_ID":"oBY7i5WShNImAoHaKuY6zmu-gAc8","MERCH_CONTRIBUTE":"0","CUST_AMT":"0","TRADING_IP":"39.144.92.50","MERCID":"856342004348074","CUST_FEE":"0","USTLDAT":"20251104","T_PAY_NO":"4200002861202511042403075191","ORDER_TIME":"20251104155010","OLD_ORDER_NO":"","BANK_NAME":"建设银行(借记卡)"}
第一步:在通知返回参数列表中,除去 sign 参数外,通知返回的参数均为待验签的参数。
第二步:将剩下参数进行字典排序,组成字符串,得到拼接串:
ACTUAL_PAY_AMT=2&AGET_CUST_ID=61000000582957&AGET_ID=61000000582957&BANK_CODE=CCB_DEBIT&BANK_NAME=建设银行(借记卡)&CARD_TYPE=01&CODE_AGE_AMT=0&CODE_AMT=0&CUST_AMT=0&CUST_FEE=0&CUST_ID=60000012628620&DEBT_STATE=20251104&DISCOUNT_FEE=0&DISCOUNT_FLAG=0&LIMIT_FEE=0&MEDIATYPE=&MERCH_CONTRIBUTE=0&MERCID=856342004348074&NETR_AMT=2&OLD_FEE=0&OLD_ORDER_NO=&OLD_TXAMT=2&OPEN_ID=oBY7i5WShNImAoHaKuY6zmu-gAc8&ORDER_NO=20251104CChi9njr&ORDER_STATUS=1&ORDER_TIME=20251104155010&ORD_TYPE=&PAY_CHANNEL=2&PAY_WAY=8&POS_PAY_WAY=&POS_VOUCHERNO=hi9njr&REFUND_DIS_AMT=&SREF_NO=&SUB_OPEN_ID=oBY7i5WShNImAoHaKuY6zmu-gAc8&TERM_FEE=0&THREE_ORDER_NO=2511042491723721&TRADING_IP=39.144.92.50&TRAN_TYPE_SER=01&TXAMT=2&T_ORDER_NO=20251104CChi9njr&T_PAY_NO=4200002861202511042403075191&USTLDAT=20251104&WX_AGET_SUBSIDY=0&WX_CUST_SUBSIDY=0
第三步:将拼接串使用 SHA256 编码,生成字符串1:
d8727d96bbb4bae07f5caef4d56c6c79b1d3e079c00bb55df8284cadd0351829
第四步:将签名参数(sign)使用 RSA 公钥解密为字符串2。
第五步:将字符串1和字符串2进行比较,相同即为验签通过,反之验签失败。

验签demo#

1.
java
展开查看完整demo
2.
c#
展开查看完整demo
using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Text;
using Org.BouncyCastle.Crypto;
using Org.BouncyCastle.Crypto.Parameters;
using Org.BouncyCastle.Security;
using Newtonsoft.Json.Linq;

namespace Api.XYFPay.Helper.Test
{
public class RSA2Helper
{
    //公钥,对接时候使用提供的公钥
    private static string pubKey = "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAg+xmmMsM04/q7yP+ykr8cagYhMls1612W5Mpq5WlofErS1ksfAH5GvW3qTwgwmgACOL8EcQE6xgmwCrHLe0jt6PfihZkTuNcBA88DEcSyBJeQhPwi1WeUcZF14AjUdLiLmdDGb7eQmiN/w8lMac8IwbjSiXfw4kju1DuISSIbcYFw+BpFIirTzPiyL1hNludAm15ecnLY79ONiZQP1BrkmV/lvwfkXCQkrrATtiCzCZdiZ2XLBhZm8R7GcVtPk5IB5bYKCg7HH6pdRPdul0futAow2mht4kBVeaZeQdA1xkumDPYaoLez9wQBOT5nGubc6NmgAA1AY70I9csXASnBwIDAQAB";

    /// <summary>
    /// 公钥加密demo(提交参数sign)
    /// </summary>
    /// <returns></returns>
    public static object PaTest()
    {
        try
        {
            var parameters = new Dictionary<string, object>();

            var jsonArray = JsonConvert.DeserializeObject("[{\"id\":\"123\" },{\"name\":\"123\"},{\"name12\":\"12333\"},{\"aa\":\"12333\"}]");

            parameters.Add("agetId", "FWH000018501");
            parameters.Add("orderNo", "test112121121212121");
            parameters.Add("orderno2", "方法");
            parameters.Add("orderno3", null);
            parameters.Add("orderNo4", jsonArray);

            // 按键排序字典,包括下划线
            var sortedParameters = parameters.OrderBy(p => p.Key, StringComparer.Ordinal)
             .Where(x=>x.Value!=null)
             .Select(p => p.Value is string ? $"{p.Key}={p.Value}" : $"{p.Key}={JsonConvert.SerializeObject(p.Value)}");

            // 拼接排序后的参数
            var parameterString = string.Join("&", sortedParameters);

            // 计算 SHA256 哈希
            string sha256Str = SHA256Encrypt(parameterString);


            string sign = EncryptByPublicKey(pubKey, sha256Str);

            parameters.Add("sign", sign);


            return parameters;
        }
        catch (Exception ex)
        {
            return "fail";
        }
    }

    /// <summary>
    /// 公钥解密demo,(异步通知 参数需要动态的获取,后面可能会有新增字段情况)
    /// </summary>
    /// <returns></returns>
    public static object ReceiveMessageTest()
    {
        try
        {
            //异步通知内容
            string content = "{\"REPAYMENT_TRANSACTION_ID\":\"\",\"ORDER_STATUS\":\"1\",\"THREE_ORDER_NO\":\"1718613332163578\",\"T_PAY_NO\":\"4200002164202406174443831052\",\"ORDER_TIME\":\"20240617163542\",\"BUSI_DATA\":\"\",\"MEDIATYPE\":\"\",\"REMARK\":\"\",\"CODE_AGE_AMT\":\"0\",\"POS_PAY_WAY\":\"\",\"USTLDAT\":\"20240617\",\"NETR_AMT\":\"1\",\"DISCOUNT_FLAG\":\"0\",\"DISCOUNT_FEE\":\"0\",\"TXAMT\":\"1\",\"CUST_ID\":\"60000007011491\",\"DEVICE_NO\":\"\",\"SREF_NO\":\"\",\"ORD_TYPE\":\"\",\"INVESTMENT_TYPE\":\"\",\"ORDER_CREATE_TIME\":\"\",\"MERCID\":\"\",\"LIMIT_FEE\":\"0\",\"CARD_TYPE\":\"03\",\"MERCH_CONTRIBUTE\":\"\",\"ORDER_NO\":\"20240617TTTardpq\",\"BAT_NO\":\"\",\"PAY_CHANNEL\":\"2\",\"T_ORDER_NO\":\"A0240617163533442648\",\"TXN_RSV1\":\"\",\"TXN_RSV2\":\"\",\"BANK_NAME\":\"零钱通或零钱\",\"PROMOTION_DETAIL\":\"\",\"OLD_ORDER_NO\":\"\",\"sign\":\"DQGWWVppvT0tn8YZP+N63hA1BFsig3d03Ghab6PUcATd71tLWqzPnQM4KtePeZUWLq7RxgwHmkwYi6EUdFSZbM2+9Y9GlcWGbJsC1oyZtWkIaIoyyO9IqoePutr8/Xk6asidkfFu4DcJQf9LsnFx6sj2wWOCAOMJHRPXMIdlqq+Tqasn8QUHotgtFbFEiHHaq4WmLVKrwpXrXb76hD4fUTpFrHTafD8DXZeOV/uodckxGX7jCyrmVBOi4xwlLsOGMPwqI3vyq01R9Af4ZzW8TgMZ+poWlXwGQFBO4WYaBqXbG2XsCggMlc1JDysUkFqnahYgR2gWO1RfBUnQQS+WBw==\",\"DEBT_STATE\":\"\",\"CUST_FEE\":\"0\",\"TRAN_TYPE_SER\":\"01\",\"PAY_TYPE\":\"\",\"AGET_ID\":\"FWH000018501\",\"BANK_CODE\":\"OTHERS\",\"OPEN_ID\":\"oBY7i5bBtwn9oyFyOjnTxhUcKOzk\",\"PAY_WAY\":\"8\",\"TRADING_IP\":\"120.33.197.108\",\"CUST_AMT\":\"0\"}";


            object notify = JsonConvert.DeserializeObject(content);

            //var json = JsonConvert.SerializeObject(notify, new JsonSerializerSettings { NullValueHandling = NullValueHandling.Ignore });
            var parameters = JsonConvert.DeserializeObject<Dictionary<string, object>>(content);

            string sign = parameters.FirstOrDefault(x => x.Key == "sign").Value.ToString();
            parameters.Remove("sign");

            // 按字典排序,包括下划线
            var sortedParameters = parameters.OrderBy(p => p.Key, StringComparer.Ordinal)
             .Select(p => p.Value is string ? $"{p.Key}={p.Value}" : $"{p.Key}={JsonConvert.SerializeObject(p.Value)}");

            // 拼接排序后的参数
            var parameterString = string.Join("&", sortedParameters);

            // 计算 SHA256 哈希
            string sha256Str = SHA256Encrypt(parameterString);


            string strRst = Encoding.UTF8.GetString(DecryptByPublicKey(sign, pubKey));

            if (strRst == sha256Str)
            {
                return JsonConvert.DeserializeObject<JObject>("{\"rspCod\":\"\",\"rspMsg\":\"success\"}");
            }

            return JsonConvert.DeserializeObject<JObject>("{\"rspCod\":\"\",\"rspMsg\":\"fail\"}");
        }
        catch (Exception ex)
        {
            return JsonConvert.DeserializeObject<JObject>("{\"rspCod\":\"\",\"rspMsg\":\"fail\"}");
        }
    }

    /// <summary>
    /// RSA公钥加密
    /// </summary>
    /// <param name="xmlPublicKey">加密公钥;为空则默认系统公钥</param>
    /// <param name="enptStr">需要加密的明文字符串</param>
    /// <param name="encoding">编码格式;默认:UTF-8</param>
    /// <returns>RSA公钥加密的密文</returns>
    public static string EncryptByPublicKey(string publicKey, string enptStr, string encoding = "UTF-8")
    {
        String pubKey = publicKey.Trim();
        String xmlPublicKey = RSAPublicKeyJava2DotNet(pubKey);

        using (RSACryptoServiceProvider rsa = new RSACryptoServiceProvider())
        {
            byte[] cipherbytes;
            rsa.FromXmlString(xmlPublicKey);
            cipherbytes = rsa.Encrypt(Encoding.GetEncoding(encoding).GetBytes(enptStr), false);
            return Convert.ToBase64String(cipherbytes);
        }
    }

    /// <summary>
    /// 用公钥解密
    /// </summary>
    /// <param name="data"></param>
    /// <param name="publicKey">公钥</param>
    /// <returns></returns>
    public static byte[] DecryptByPublicKey(String data, String publicKey)
    {
        String pubKey = publicKey.Trim();
        String xmlPublicKey = RSAPublicKeyJava2DotNet(pubKey);

        RSACryptoServiceProvider publicRsa = new RSACryptoServiceProvider();
        publicRsa.FromXmlString(xmlPublicKey);

        AsymmetricKeyParameter keyPair = DotNetUtilities.GetRsaPublicKey(publicRsa);
        //转换密钥  
        // AsymmetricCipherKeyPair keyPair = DotNetUtilities.GetRsaKeyPair(publicRsa);
        IBufferedCipher c = CipherUtilities.GetCipher("RSA/ECB/PKCS1Padding");// 参数与Java中加密解密的参数一致       
        c.Init(false, keyPair); //第一个参数为true表示加密,为false表示解密;第二个参数表示密钥 
        byte[] DataToEncrypt = Convert.FromBase64String(data);
        byte[] outBytes = c.DoFinal(DataToEncrypt);//解密  
        return outBytes;
    }


    /// <summary>
    /// RSA公钥格式转换,java->.net
    /// </summary>
    /// <param name="publicKey"></param>
    /// <returns></returns>
    private static string RSAPublicKeyJava2DotNet(string publicKey)
    {
        RsaKeyParameters publicKeyParam = (RsaKeyParameters)PublicKeyFactory.CreateKey(Convert.FromBase64String(publicKey));
        return string.Format("<RSAKeyValue><Modulus>{0}</Modulus><Exponent>{1}</Exponent></RSAKeyValue>",
            Convert.ToBase64String(publicKeyParam.Modulus.ToByteArrayUnsigned()),
            Convert.ToBase64String(publicKeyParam.Exponent.ToByteArrayUnsigned()));
    }



    public static string SHA256Encrypt(string data)
    {
        byte[] bytes = Encoding.UTF8.GetBytes(data);
        byte[] hash = SHA256Managed.Create().ComputeHash(bytes);


        string ret = "";
        for (int i = 0; i < hash.Length; i++)
        {
            ret += Convert.ToString(hash[i], 16).PadLeft(2, '0');
        }

        return ret.PadLeft(32, '0').ToLower();

    }


}
}
3.
php
展开查看完整demo
4.
python
展开查看完整demo
5.
go
展开查看完整demo
6.
nodejs
展开查看完整demo

收不到异步通知排查方案#

若商户未收到异步通知,请按以下顺序排查:
1.
异步通知地址是否已报备
所有地址(包括默认地址和多地址列表中的地址)必须提前向运营报备,可向运营咨询目前的通知地址配置。
2.
接口上传的地址是否正确
测试环境:上传原始地址。
生产环境:如需显式上传,必须上传映射后的内网地址,否则无法匹配多地址列表,最终推送至默认地址。
若不传地址,确保默认地址已配置且报备。
3.
地址的可访问性
异步通知地址必须外网可正常访问(生产环境映射地址由星驿付内部网络访问,商户侧无需关心其外网可达性,但商户的原始地址必须能接收来自星驿付服务器的回调)。
4.
地址权限校验
若商户的异步通知地址设有IP白名单、HTTP Basic认证等访问控制,需确保星驿付服务器IP在允许范围内,或临时关闭校验进行测试。
详细规则请参考上文 【使用说明】 部分。

请求参数

Header 参数

Body 参数application/json

示例

返回响应

🟢200成功
application/json
Bodyapplication/json

🟢200成功
请求示例请求示例
Java
Shell
C#
PHP
响应示例响应示例
200 - 成功 - 示例 1
{
    "rspCod": "000000",
    "rspMsg": "success"
}
修改于 2026-07-30 02:16:26
上一页
交易对账文件-ISV
下一页
交易手续费通知
Built with