API技术集成
Webhooks概述
Midasbuy 提供 Webhooks 和订单 API 给开发者集成。
事件示例
- 用户验证
- 支付结果通知
在用户输 入用户 ID,并选择了server_id后，Midasbuy 会发起用户验证。Webhook 中会包含user_id和server_id。开发者可以根据user_id和server_id判断用户是否满足充值的条件，如果不满足则返回对应的错误。如果开发者期望Midasbuy根据用户信息来做进一步的判断，可以将需要校验的条件也回传到 Midasbuy，Midasbuy 来做进一步的校验。参考风控锁区
当Midasbuy从Paypal等支付渠道获取到支付结果后，会给开发者的服务器发送支付订单支付成功的通知。开发者收到这个通知后并校验完签名后，可以给用户提供对应的商品。如果因为用户离线等原因导致商品暂时无法提供，可以给 Midasbuy返回对应的错误，Midasbuy 会继续推送。参见通知。
在订单状态发生变化的时候，会有对应的支付订单状态变化通知,状态 以“order_status”字段来表示:
| 订单状态 | 描述 | 开发者处理 |
|---|---|---|
| Created | 用户创建订单 | 记录订单创建 |
| Paid | 订单支付成功 | 将用户购买的商品计入账户 |
| Finished | 商户发货成功 | 记录订单发货成功，用于对账和客服等用途 |
| Refunded | 用户退款成功 | 将用户的商品移除 |
下图展示的主要的事件变化流程。
如果在用户购买商品的时候，有对应的营销赠送的行为发生，会有单独的营销订单通知。参见 promotion-notification。
另外Midasbuy也提供的订单查询的 API，用于在真正提供商品前，校验订单的真实性。参见 order query
Webhooks 分类
从是否会导致用户界面流程中断的角度，Midasbuy将事件分为同步事件和异步事件
-
同步事件
用户会等待事件的应答， 如果应答失败，则流程中断，用户无法继续流程。同步事件系统超时后，系统不会主动发起重试。比如用户验证，扩展功能中描述的商品验证事件。
-
异步事件
支付订单结果通知和营销订单结果通知，用户不需要等待事件的应答。如果调用您的服务器超时，Midasbuy会自动发起重试
| 名称 | 类型 | 必选/ 可选 |
|---|---|---|
| PaymentNotification | 异步 | 必选 |
| ProductValidate | 同步 | 可选 |
| PromotionNotification | 异步 | 可选 |
| UserValidate | 同步 | 必选 |
获取Webhooks联调参数
获取到到联调用的 app_id,以及 Webhooks key。另外您需要准备好接受 Webhooks 通知的URL 地址（Midasbuy提供统一的 Webhooks URL 来发送各个事件，因此您只需要准备一个地址即可）.请开发者严格区分沙箱和
参数获取/设置步骤
- 打开店铺
- 点击 "服务集成与分区配置" 标签并选择 "Webhook" 标签
- 再 "Webhook服务器" 中指定服务器地址，格式如 https://example.com . 沙箱和现网的地址需要分别配置.
- 用于验证 webhook 的密钥会自动生成，沙箱和现网的密钥也是独立的
Webhooks API模拟
您可以使用 Webhooks API 模拟页面直 接给您的服务器模拟发送各种Webhooks 事件。为了减少您切换密钥的成本，Midasbuy不提供在模拟页面输入webhooks私钥。Midasbuy会使用开发者应用的的沙箱私钥对请求进行签名，开发者需要使用到从商户平台获取到到webhooks 的沙箱公钥进行签名的验证
处理 Webhooks
Midasbuy们提供了如何正确处理Webhooks 的 DEMO，您可以参考这个 DEMO 来处理Webhooks。参见 buy-api-library