小程序虚拟支付接入（iOS）

说明

本文面向使用「小鹅通小程序 SDK」接入自有小程序的商家，说明如何接入微信小程序 iOS 虚拟支付能力，并在支付完成后通过服务端回调将订单状态同步给小鹅通。

流程总览

正向流程

三方职责如下：

参与方	主要职责
商家小程序	集成小鹅通小程序支付 SDK，进入支付页后调用 SDK 拉起微信虚拟支付。
微信	提供虚拟支付能力；支付完成、道具发货、退款等事件通过消息推送通知商家服务端。
商家服务端	提供微信消息推送 URL；完成微信验签/解密；将支付、发货、退款结果同步给小鹅通。
小鹅通	生成支付参数；接收商家服务端回调；更新支付订单、业务订单和退款状态。

逆向流程

iOS 虚拟支付退款由用户在微信侧发起，微信再通过消息推送将退款结果通知商家服务端。商家服务端收到退款事件后，调用小鹅通退款通知接口同步退款结果。

关于应答退款问询相关逻辑，商家侧自行选择是否接入。微信小程序虚拟支付-iOS用户退款

一、接入前准备

1. 微信后台开通虚拟支付

微信小程序虚拟支付

商家需要先在自己的小程序账号下完成微信虚拟支付开通和配置。通常包括：

1. 小程序主体认证完成，且满足微信虚拟支付接入要求。
2. 在微信公众平台开通虚拟支付能力和收款商户号。

2. 获取或配置以下参数：

• 小程序 AppID
• App Secret
• OfferID（支付应用 ID）
• 现网 AppKey
• ProductId（道具 ID）

3. 在微信后台创建虚拟支付道具，获取对应的 ProductId（道具 ID）。

4. 在微信后台配置消息推送服务器，用于接收支付、道具发货、退款等通知。

2. 小鹅通管理台配置虚拟支付参数

微信后台准备完成后，商家需要进入小鹅通店铺管理台配置小程序 SDK 虚拟支付参数。

入口：店铺管理台 -> 交易/支付设置 -> Apple Pay / 虚拟支付配置

选择接入渠道时，请选择 小程序 SDK。需要填写的核心参数如下：

参数	说明	是否必填	获取位置
AppID（小程序 ID）	商家自有小程序的 AppID	是	微信公众平台
OfferID（支付应用 ID）	微信虚拟支付分配的支付应用 ID	是	微信虚拟支付后台
现网 AppKey	微信虚拟支付现网 AppKey	是	微信虚拟支付后台
App Secret（小程序密钥）	商家小程序 App Secret	是	微信公众平台
ProductId（道具 ID）	微信后台创建道具后生成的道具 ID	是	微信虚拟支付道具配置
是否开启	开启后 iOS 端符合条件的订单走虚拟支付	是	小鹅通管理台

3. 商家服务端准备

商家需要准备一个公网可访问的 HTTPS 服务，用于接收微信消息推送。

服务端需要满足以下要求：

1. 支持微信后台 URL 验证请求：GET。
2. 支持接收微信消息推送：POST。
3. 按微信消息推送规则校验签名，验证通过后才处理消息。
4. 如果开启消息加密，需要按 Token、EncodingAESKey、AppID 完成消息解密。
5. 解析虚拟支付事件后，调用小鹅通回调接口。
6. 做好日志记录和幂等处理，避免微信重试导致重复处理。

二、小程序端接入

详见 小程序支付接入

三、微信消息推送配置

微信小程序消息推送

需要重点关注的事件：

事件	说明	商家侧处理
xpay_goods_deliver_notify	道具发货/支付完成相关通知	调用小鹅通道具发货回调接口，完成支付订单和业务订单状态扭转。
xpay_refund_notify	退款结果通知	调用小鹅通退款通知接口，同步退款结果。

四、商家服务端调用小鹅通接口

商家服务端完成微信消息验签和解密后，需要将解析后的结果同步给小鹅通。

接口调用说明：

1. 请求发起方必须是商家服务端，不要在小程序前端直接调用。
2. 请求体使用 JSON 对象。
3. 请求体中必须包含 app_id，表示小鹅通店铺 AppID。
4. 小鹅通返回 code = 0 表示处理成功；非 0 表示处理失败。
5. 商家服务端应根据小鹅通处理结果决定返回微信 success 或 failed。
6. 微信可能重复推送消息，商家服务端和小鹅通侧均应按订单号/交易单号做幂等处理。

1. 道具发货（支付完成）通知

该接口用于商家服务端收到微信 xpay_goods_deliver_notify 事件后，通知小鹅通完成虚拟支付订单处理。

POST https://api.xiaoe-tech.com/xe.sdk.wx.virtual.goods_deliver.callback/1.0.0
Content-Type: application/json

请求参数示例：

{
  "access_token": "xe_xxxxx",
  "data": {
    "out_trade_no": "order_202608210001",
    "create_time": 1787222400,
    "msg_type": "event",
    "event": "xpay_goods_deliver_notify",
    "open_id": "oMockOpenId1234567890",
    "env": 0,
    "wechat_pay_info": {
      "mch_order_no": "mch_order_202608210001",
      "transaction_id": "wx_transaction_202608210001"
    },
    "goods_info": {
      "product_id": "product_001",
      "quantity": "1",
      "orig_price": "100",
      "actual_price": "100",
      "attach": "trade_202608210001"
    }
  }
}

字段说明：

字段	类型	是否必填	说明
access_token	string	是	小鹅云专属 token，由小鹅云网关鉴权。
data	object	是	业务参数对象，业务字段必须放在 data 内。
data.out_trade_no	string	是	商户订单号 / 小鹅通支付订单号，用于匹配支付订单。
data.create_time	int64	是	支付完成时间，Unix 秒级时间戳，需大于 0。通常可使用微信消息 CreateTime。
data.msg_type	string	否	消息类型，通常为 event。
data.event	string	是	事件类型，固定为 xpay_goods_deliver_notify。
data.open_id	string	否	用户 openid，以微信推送内容为准。
data.env	int	是	微信环境标识：0 表示正式环境，1 表示沙箱环境。
data.wechat_pay_info	object	是	微信支付信息。
data.wechat_pay_info.mch_order_no	string	否	微信支付商户单号。
data.wechat_pay_info.transaction_id	string	是	微信交易单号。
data.goods_info	object	否	道具信息。建议按微信推送内容透传。
data.goods_info.product_id	string	否	微信道具 ID。
data.goods_info.quantity	string/number	否	道具数量。
data.goods_info.orig_price	string/number	否	道具原价，单位分。
data.goods_info.actual_price	string/number	否	道具实付金额，单位分。
data.goods_info.attach	string	否	微信透传字段。小鹅通可能使用该字段中的 trade_id 辅助匹配订单。

成功响应示例：

{
  "code": 0,
  "msg": "success",
  "data": {
    "errcode": 0,
    "errmsg": ""
  }
}

2. 退款通知

该接口用于商家服务端收到微信 xpay_refund_notify 事件后，通知小鹅通更新退款状态。

POST https://api.xiaoe-tech.com/xe.sdk.wx.virtual.refund.notify/1.0.0
Content-Type: application/json

请求参数示例：

{
  "access_token": "xe_xxxxx",
  "data": {
    "wx_app_id": "wx4d356f6b38a0fa42",
    "create_time": 1787222400,
    "msg_type": "event",
    "event": "xpay_refund_notify",
    "open_id": "oMockOpenId1234567890",
    "wx_refund_id": "wx_refund_202608210001",
    "mch_refund_id": "mch_refund_202608210001",
    "wx_order_id": "wx_order_202608210001",
    "mch_order_id": "order_202608210001",
    "refund_fee": 100,
    "ret_code": 0,
    "ret_msg": "success",
    "refund_start_timestamp": 1787222400,
    "refund_succ_timestamp": 1787222460,
    "wxpay_refund_transaction_id": "wxpay_refund_transaction_202608210001",
    "retry_times": 0
  }
}

字段说明：

字段	类型	是否必填	说明
access_token	string	是	小鹅云专属 token，由小鹅云网关鉴权。
data	object	是	业务参数对象，业务字段必须放在 data 内。
data.wx_app_id	string	否	商家小程序 AppID。
data.to_user_name	string	否	小程序原始 ID，以微信推送内容为准。
data.from_user_name	string	否	微信推送方标识，以微信推送内容为准。
data.create_time	int64	否	微信消息创建时间，Unix 秒级时间戳。
data.msg_type	string	否	消息类型，通常为 event。
data.event	string	是	事件类型，固定为 xpay_refund_notify。
data.open_id	string	否	用户 openid。
data.wx_refund_id	string	否	微信退款单号。
data.mch_refund_id	string	否	商户退款单号。
data.wx_order_id	string	否	退款单对应的微信支付单号。
data.mch_order_id	string	是	退款单对应的商户订单号 / 小鹅通外部订单号，用于匹配订单。
data.refund_fee	int	是	退款金额，单位分，需大于 0。
data.ret_code	int	是	退款结果：0 表示成功，非 0 表示失败。即使成功也必须显式传 0。
data.ret_msg	string	否	退款结果说明。失败时建议传失败原因。
data.refund_start_timestamp	int64	否	开始退款时间，Unix 秒级时间戳。
data.refund_succ_timestamp	int64	否	退款成功时间，Unix 秒级时间戳。未传时小鹅通按接收时间处理。
data.wxpay_refund_transaction_id	string	否	退款对应微信支付交易单号。
data.retry_times	int	否	微信推送重试次数，以微信推送内容为准。

成功响应示例：

{
  "code": 0,
  "msg": "success",
  "data": null
}