# 小游戏支付能力发货规范

## 一、背景

1、**为了进一步提升和保障玩家的支付体验，从整个充值-发货链路进行上报，保证完成及时、准确发货。若出现发货问题，能够短时间响应和处理，降低开发者和用户的损失，也能提高开发者的口碑。**

2、**后续退款会与发货情况、用户申诉情况强关联，接入支付能力发货规范后，能够减少开发者退款申诉的处理时间，提高效率。**

- **平台和开发者系统正常情况下，及时、准确的发货——不漏不重**

  **平台**为了不漏，对于订阅消息/直购发货通知在**一定时间内**会尽量确保**至少触达一次**开发者服务器；**开发者服务器**需要有能力处理重复的通知，对于相同的订单ID/事件ID需要**做好幂等处理**。

- **平台或开发者系统故障情况下，能及时安抚用户、并确保最终补发货成功**

  故障时平台在订单投诉等场景及时同步故障情况给玩家，故障恢复后平台和开发者一起协作把受影响的订单补发货成功，同时平台通过消息触达场景及时通知玩家已补发货成功。

因此平台制定了一套发货规范，希望开发者按照如下规范完成支付能力的对接。

## 二、不同付费场景下使用平台能力的发货规范

如何区分付费场景，建议先阅读[技术手册-虚拟支付篇](guide)

游戏币模式开发者需要在发货前正确扣除游戏币余额，平台以正确扣除游戏币为统计口径。

```json
[
  {
    "付费场景": "游戏币场景",
    "使用的平台能力": "[游戏币能力](/minigame/dev/guide/open-ability/virtual-payment/coins.md)",
    "发货规范": "1）游戏币发货：平台负责，开发者无需处理\n 2）游戏币兑换道具：开发者负责",
    "备注": ""
  },
  {
    "付费场景": "道具直购场景",
    "使用的平台能力": "[道具直购能力](/minigame/dev/guide/open-ability/virtual-payment/goods.md)",
    "发货规范": "以平台接收到“发货成功”的回包为准",
    "备注": ""
  },
  {
    "付费场景": "[游戏币能力](/minigame/dev/guide/open-ability/virtual-payment/coins.md)",
    "使用的平台能力": "充值接口（[wx.requestMidasPayment](/minigame/dev/api/midas-payment/wx.requestMidasPayment.md)）的outTradeNo与扣除游戏币接口（pay）关联",
    "发货规范": "不推荐，建议使用道具直购能力代替",
    "备注": ""
  }
]
```

具体细节，见随后展开

### 1.游戏币场景使用游戏币能力

即游戏币充值后直接当成游戏内代币使用，玩家在游戏内可直接感受到游戏币余额。该场景下有2类发货行为

1. 游戏币的充值发货：游戏币托管在平台，发货由平台来负责，开发者无需处理；

2. **游戏币扣除（消耗）后兑换道具**：兑换道具的发货由开发者负责，扣除、赠送等接口需要做好**幂等处理**，以及故障后的最终补发货。此场景主要由开发者负责保障支付体验。

![](https://res8.wxqcloud.qq.com.cn/wxdoc/9dd2a58d-3589-47b3-986c-4640f123f728.png)

### 2.道具直购场景使用道具直购能力

道具直购需要正确处理发货通知，平台以发货通知回包为统计口径。
即在一定时间内，平台会多次重试，直到接收“**发货成功**”**的回包**：

```json
{"ErrCode":0,"ErrMsg":"Success"}
```

失败的情况希望明确给出失败的原因

```json
{"ErrCode":99999,"ErrMsg":"失败原因"}
```

**强制要求：**

接入道具直购的开发者，必须按照要求接入发货通知。

**建议**：
- 若开发者能较为快速处理发货，在接到平台的发货通知时，可以同步完成发货再返回发货成功的回包。
- 若发货逻辑较为复杂，耗时较长，建议先推送到可靠队列，然后返回“发货成功”给平台。异步处理需要尽量保障快速、准确的发货，避免发生客诉。

![](https://res8.wxqcloud.qq.com.cn/wxdoc/f16eb1b1-c69f-44e7-9278-4d97d06bce22.png)

更多信息，进一步阅读：[虚拟支付2.0道具直购](/minigame/dev/guide/open-ability/virtual-payment/goods.md)

### 3.道具直购场景使用游戏币能力
由于历史原因，2022年11月5日之前平台只提供了游戏币托管能力，因此开发者在道具直购场景使用了游戏币的能力，即一次“道具直购”分为3步：

1. 购买游戏币：即游戏币充值[wx.requestMidasPayment](/minigame/dev/api/midas-payment/wx.requestMidasPayment.md)
2. 游戏币扣除：即调用服务端pay接口
3. 兑换道具：扣除成功后开发者给玩家发送对应的道具

这种模式现在不推荐继续沿用，建议使用道具直购能力来实现道具直购的付费场景（即第2点）。

若短期内改造不了，请按如下规范传参，让平台把充值订单和游戏币扣除的订单一一对应。该场景的发货规范：对于充值订单的发货，以存在对应的游戏币扣除订单为准。

**以下outTradeNo参数**为充值游戏币时传入的订单号（即[wx.requestMidasPayment](/minigame/dev/api/midas-payment/wx.requestMidasPayment.md)接口中的outTradeNo）。

- [扣除游戏币](/minigame/dev/api-backend/midas-payment/game_currency/api_pay_v2.pay.md)

  remark字段按如下格式传入wx.requestMidasPayment下单支付时传入的订单号

  ```json
  "remark": "{\"outtradeno\":\"wx.requestMidasPayment下单支付时传入的outTradeNo\"}"
  ```
  payitem传入道具名称

![](https://res8.wxqcloud.qq.com.cn/wxdoc/2be230f1-9597-42ae-9705-130b61906a1d.png)