1.1 小程序支付接入

公告：微信小程序「P云支付插件」已停止维护。已接入的插件版本可继续使用，但新接入请一律使用「半屏小程序拉起支付」方案（本文档），体验更好、接入更简单。

1 适用场景与角色

2 整体流程

关键原则：④ 前端回调仅用于 UI 展示，不能作为发货或业务凭证；业务状态必须以 ⑤ 服务端通知 或 ⑥ 主动查询为准。

3 接入前置条件

1. 提供公司全称给商务，由研发开通并下发：
   • app_id：平台分配的接入应用 ID
   • app_secret：签名密钥（仅存服务端，严禁下发到小程序端）
   • merchant：商户号
2. 确认交易场景值 trade_scene 与 extra 字段要求（见附录），场景传错将无法正常支付。
3. 下单接口必须在服务端调用，禁止在小程序端直接请求（会泄露 app_secret）。

4 接入步骤

4.1 第一步：服务端下单

POST https://papi.4pyun.com/gate/1.0/payment/trade/prepare
Content-Type: application/x-www-form-urlencoded

完整字段说明见 2.2 发起交易预请求。小程序场景只需关注以下几点：

• 必传：app_id、merchant、pay_order、subject、value、notify_url、trade_scene、sign（签名规则见签名算法）；
• 金额 value 单位为分，pay_order 在同一 app_id 下唯一；
• trade_scene / extra 按业务场景传递，见附录；
• callback_url 半屏小程序场景不传（仅历史插件场景传小程序内页路径）；
• 该接口只能由服务端发起，小程序端只拿服务端下发的 pay_id。

返回关键字段

返回示例

{
  "code": "1001",
  "seqno": "92a78431551bd293",
  "data_node": "CN-South/HS3-1",
  "pay_url": "https://app.4pyun.com/payment/trade/create?pay_id=621722601479223111111111",
  "pay_id": "621722601479223111111111"
}

下单失败时以 hint / message 为准排障：

{
  "code": "400",
  "message": "请求参数错误",
  "hint": "`merchant` Required!",
  "seqno": "94929a9b0874aa46"
}

4.2 第二步：小程序拉起半屏收银台

4.3.1 微信小程序

1. 在 app.json 声明跳转目标 appId（P云收银台小程序）：

{
  "embeddedAppIdList": ["wxa204074068ad40ef"]
}

参考微信官方文档： 配置 embeddedAppIdList wx.openEmbeddedMiniProgram

1. 在需要支付的位置调用（pay_id 由服务端下发，切勿在前端生成）：

wx.openEmbeddedMiniProgram({
  appId: 'wxa204074068ad40ef',
  path: `/external/payment/trade/create/index?pay_id=${payId}`,
  success: () => {},
  fail: (err) => {
    // 建议提示用户稍后重试，或降级走 H5 收银台 pay_url
  }
})

4.3.2 支付宝小程序

my.openEmbeddedMiniProgram({
  appId: '2021004130621008',
  path: `/external/payment/trade/create/index?pay_id=${payId}`,
})

参考支付宝官方文档：my.openEmbeddedMiniProgram

4.3.3 收银台参数说明

• pay_id 为第一步返回的平台支付 ID；
• 有效期：受下单时 expire_time 限制，默认 3 分钟，过期需重新下单；
• 一单一用：不要复用同一个 pay_id 反复拉起。

4.3 第三步：接收前端支付结果（用于页面展示）

支付结束后，收银台小程序会把结果回传给宿主小程序：

• 微信：在 App.onLaunch / App.onShow 中通过 options.referrerInfo.extraData 获取；
• 支付宝：在 App.onLaunch(options) / App.onShow(options) 中通过 options.referrerInfo?.extraData 获取。

App({
  onShow(options) {
    const data = options.referrerInfo && options.referrerInfo.extraData
    if (!data || !data.pay_order) return

    // 仅用于页面展示与跳转，业务状态以后端通知为准
    if (data.status === 1) {
      // 展示成功页
    } else if (data.status === 0) {
      // 支付中，建议轮询后端订单状态
    } else {
      // 失败 / 用户取消
    }
  }
})

回调字段

注意：用户可能直接关闭半屏小程序而不触发回调，因此该回调不可作为业务依据。

4.4 第四步：接收服务端支付结果通知（必接）

• 请求方式：HTTP POST + application/x-www-form-urlencoded 表单提交
• 通知地址：第一步下单时传的 notify_url
• 由对接方实现，平台主动调用

完整字段说明见 2.6 支付结果异步通知。接入时只需关注：

处理要求

1. 校验签名，并校验 app_id、merchant、value 与本地订单一致；
2. 按 pay_order 做幂等处理（平台会重复通知）；
3. 仅当 status == 1 时执行发货 / 业务履约；
4. 处理成功必须返回 code = 1001，否则平台将持续重投；
5. 已处理过的通知，直接返回 1001 即可停止重投。

响应：返回 code = 1001 表示接收成功，message / hint 选填。

{ "code": "1001", "message": "通知成功", "hint": "" }

4.5 第五步：主动查询（兜底）

长时间未收到通知、或前端回调丢失时，调用查询交易状态，以平台实际状态为准修正本地订单。建议配合定时任务扫描「支付中」的超时订单并做终态判定。

5 状态与错误码

交易状态 status

下单接口常见 code

6 接入自检清单

• [ ] app_id / app_secret 已开通，app_secret 仅存服务端
• [ ] 下单接口在服务端调用，未暴露给小程序端
• [ ] pay_order 全局唯一（建议：业务前缀 + 时间戳 + 序列）
• [ ] 金额单位统一为分，value 与业务金额一致
• [ ] trade_scene / extra 按场景要求正确传递
• [ ] app.json 已配置 embeddedAppIdList（微信）
• [ ] 使用 pay_id 拼接半屏 path，未使用已废弃的支付插件
• [ ] notify_url 公网可达、验签、幂等、返回 code=1001
• [ ] 前端回调仅做展示，业务状态以后端通知 / 查询为准
• [ ] 已实现超时未通知的主动查单补偿

7 相关文档

• 发起交易预请求
• 查询交易状态
• 支付结果异步通知
• 附录：交易场景 / 事项定义