新版自定义交易组件接入指引（更新售后流程相关内容）_自定义交易组件4.0

自定义交易组件

本文主要介绍新版自定义交易组件的业务流程及各流程的注意事项，文档篇幅较长，如无需查看完整文档可以使用浏览器自带页面搜索功能进行关键字搜索（快捷键Ctrl+F ）。

在开始开发前应确认以下必要前置条件是否完成：

1、开通场景经营商户号；

2、部分接口强制校验来源IP白名单，白名单配置方式：

1）服务商配置方式"点我查看"

2）普通小程序：登录小程序管理后台->开发管理->开发设置->“开发者ID”下的“IP白名单”

3、因视频号场景受控订单无微信支付回调，支付结果等事件是通过小程序消息推送进行下发的，需要登录小程序管理后台后，在「开发」-「开发设置」-「消息推送」中启用并设置消息推送配置，开发者接收到的消息需要解密， 消息加解密说明可在开发文档查询。

1、业务流程图

1.1 关键流程逻辑

1.2 售后流程

1.3 主要业务变动

2、接入流程详细说明

整体接入流程

注：本文2.1-2.2为前置必做流程，完成后才可以进行接口调试

2.1 开通自定义交易组件

2.1.1 公众平台后台开通

登录公众平台,点击功能下方的“交易组件”，点击“开通”阅读并同意开通协议后即可进行下一步操作。

开通后页面如图所示

2.1.2 接口申请开通

调用接口 “shop/register/apply” 申请开通自定义版交易组件，请求成功后将发送“法务协议确认”到管理员微信，管理员需要在“24小时内”点击该模板消息，并确认服务协议。服务协议签署成功后，开发者可以通过“获取接入状态接口（可点击跳转）”或“”事件回调“进行开通状态判断，若状态为“已开通”，开发者才可以继续调用后续接口进行调试接入。

2.1.3 自定义交易组件“升级版”跟升级前的自定义交易组件有什么区别，哪些接口需要进行升级？

1.新支付接口，必须走新商户号。

2.取消订单， 小程序(小程序内以及发现-小程序我的订单)和视频号双向可取消，之前只可以在小程序上取消，然后同步给视频号状态。

3.申请退款，小程序和视频号双向可申请退款。

4.申请退货退款,小程序和视频号双向可申请退货退款，之前只有小程序上操作。

5.未付款订单，小程序和视频号 可在各自订单中心重新支付，同步状态。

6.确认收货，小程序和视频号双向可确认收货。

7.同步发货状态接口更新。

2.2 开通场景经营所需商户号

视频号场景下，会通过开通商户号、补齐资料，获得一个新的电商收付通的商户号。商家在视频号内的交易资金流，需要使用这个新商户号。

• 准备事项：需准备营业执照、法人身份证、商户号超级管理员手机号、邮箱信息

• 注意事项：小程序超管将作为微信支付商户号的超级管理员，如管理员已离职、管理员曾变更过姓名未在小程序后台更新等情况，将影响商户号的签约，请确认无误后再进行商户号申请。

2.2.1 通过公众平台后台申请

在小程序官方后台自定义交易组件页面，点击商户号申请所对应的“去开通”按钮进入商户号申请页面，共计三部分（不想开商户号了，暂时不放图）：

2.2.1.1 填写基础信息

此部分主要为上传营业执照、法人身份证、填写商户号超管信息

2.2.1.2验证账户小额打款/法人验证

此部分会有两种情况，如为“小额打款”验证方式，在页面输入收到的打款金额即可；如为法人验证，需要使用实名认证为法人同名微信扫码进行验证。

2.2.1.3确认账户真实性。

点击“去签署”按钮会展示签约二维码，使用超管微信进行扫码，用于确认经营意愿并签署协议，完成商户号注册。

2.2.2 通过API接口申请

调用“提交支付资质”接口，提交场景经营所需商户号申请，提交成功后，商户申请是没有事件回调的，需要服务商主动调用“状态查询接口”查询申请单进度，申请单状态同“电商收付通二级商户进件申请单状态查询”。此处不做过多描述，有问题可以留言，后续视情况补充更新。

2.2.3 开通场景经营商户常见问题

2.2.3.1 Q：新版交易组件需要重新申请商户号吗？是否可以使用原有商户号？

A：不可以，新版交易组件必须要申请开通场景专用商户号

2.2.3.2 Q:新版场景专用商户号费率是多少，是否有优惠，结算周期是多久？

A：商户号费率为0.6%，无费率优惠，结算周期为7+7日，即用户收货后7天后结算。

2.2.3.3 Q：申请新商户号时，最后一步签约遇到“微信实名信息与管理员信息不一致”是什么原因？

A：申请新的场景专用商户号时，“超级管理员”这一项不支持修改，默认为小程序“超级管理员”实名信息，如需修改，需要为该用户前往成员管理为小程序绑定超级管理员。

2.2.3.4 Q：申请新的商户号时，为什么不能修改主体信息?

A：“当前主体”这一项不支持修改，因为商户号主体必须和该小程序注册主体保持一致。

2.2.3.5 Q：通过新版自定义交易组件申请的场景专用商户号是否对跨境类小程序（自助报关）有影响？

A：会，二级商户当前暂不支持自助清关接口调用，留意后续更新通知

2.2.3.6 Q：新商户号是否支持分账功能？

A：即将支持，敬请期待。

2.3 上传商品并通过审核，完成商品接口调用（仅有API接入方式）

基础流程，不做过多说明，只写流程、常见错误和注意事项

2.3.1 添加商品流程：

（1）首先去“获取类目详情”，与自己的系统商品类目相匹配

（2）查看对应类目是否需要行业资质，如果需要，请上传相关资质

（3）“上传相关类目资质”获得对应类目的使用权限

（4）如果商品有品牌，“上传品牌信息”获得品牌的使用权限

（5）调用“添加商品”接口将商品进行上传

2.3.2 SPU接口常见错误及注意事项

2.3.2.1 Q：自定义交易组件提交上传类目资质时报错{“errcode”: 1000009, “errmsg”: “调用的类目id不存在”}

A: 调用获取类目详情，看对应““qualification_type"与"product_qualification_type"参数是否为"0”，为"0"无需上传类目资质

2.3.2.2 Q：调用自定义交易组件“添加商品”接口shop/spu/add时报错“该账号客服方式必须包含微信客服/小程序客服” {“errcode”:1040042,“errmsg”:"该账号客服方式必须包含微信客服/小程序客服”}

A11:需要在MP后台配置微信客服/小程序客服后，然后通过“更新商家信息”接口更新商家信息

调用“获取商家信息”接口应返回一下内容才为成功，“service_agent_type”字段需要同时包含0，1，2三个值

2.3.2.3 Q：类目审核成功，但是添加商品报错，{“errcode”:1000005,“errmsg”:"该商品使用了未申请通过的类目，请先申请类目且通过后再提审商品 "}

A: 检查是否取消开通过，取消开通会清空品牌类目。对于服务商，可以监听账户接入回调事件，目前只有取消开通回调。

2.3.2.4 Q：调用自定义组件上传图片接口报错{“errcode”:1070001,“errmsg”:"文件/图片为空 "}

A25:检查请求报文协议，需Content-Type: multipart/form-data

2.4 调试支付校验，完成订单接口调用

2.4.1 支付流程：

（1）按照"开发指引"修改基础库配置

（2）在小程序中调用"生成订单"接口生成一笔订单

（3）完成订单的支付（视频号场景需要调用生成支付参数后完成收银台的拉起，其他场景按照已有业务逻辑进行支付）

（4）调用"同步订单支付结果"接口同步订单的支付结果（二级商户单无需同步支付结果，系统自动流转订单状态）

注意：

• 这里两个接口都需要调用，以同步订单结果为最后确认步骤，视频号场景则以支付成功作为最终确认步骤。

• 基础库拉起收银台接口改造后需要发版才可以生效。

• 完成接口调用后，点击完成，切换状态。

2.4.2 订单接口接口常见错误及注意事项

2.4.2.1 Q：二级商户号订单支付流程与原有订单支付流程有什么区别？

A17:主要区别是：二级商户号订单调起支付所需参数是通过“生成支付参数”获取，无需同步支付结果；原流程调起支付是需要通过微信支付统一下单获取，需要同步支付结果。

2.4.2.2 Q：调用自定义交易组件“创建订单”接口shop/order/add时报错“不支持的发货方式” {“errcode”:1010036,“errmsg”:"不支持的发货方式“}

A：视频号场景当前只支持“正常快递”方式，其他请留意后续更新。

2.4.2.3 Q：自定义交易组件申请视频号专用商户号后，唤起支付报错: “商户号该产品权限未开通”

A:需要先调用“生成订单”接口，生成订单时将fund_type设为1，然后调用“生成支付参数”接口获取调取支付所需参数，不要调用微信支付统一下单接口获取调用支付参数

2.4.2.4 Q：自定义交易组件二级商户单调起支付时报错“JSAPI缺少参数total_fee”

A:生成支付参数失败，没返回正确的预支付 ID，重新调用生成支付参数接口获取新的支付参数即可

2.4.2.5 Q：自定义交易组件调用同步订单支付结果时报错 {“errcode”:990022,“errmsg”:"暂不支持操作“}

A：二级商户单无需同步支付结果，付款成功后系统自动流转订单状态并下发支付结果回调事件。

2.5 调试发货接口，完成物流相关接口调用

2.5.1 发货流程

（1）先调用获取快递公司列表接口获取快递公司信息

（2）调用"订单发货"接口，完成发货

2.5.2 发货接口常见错误及注意事项

注意事项：

• 视频号订单状态流转不可逆的，当finish_all_delivery=0时，订单状态流转到21（部分发货）， 当finish_all_delivery=1时，订单状态从20（待发货）/ 21(部分发货）流转到30（待收货），部分发货时finish_all_delivery一定要传0，最后一次发货才可以传1，切记！切记！切记！！！

2.5.2.1 Q：调用自定义交易组件“创建订单”接口shop/order/add时报错“不支持的发货方式” {“errcode”:1010036,“errmsg”:"不支持的发货方式“}

A：视频号场景当前只支持“正常快递”方式，其他请留意后续更新。

2.5.2.2 Q：当自定义交易组件订单只存在一个SKU，发货时误操作为部分发货，订单状态码流转为21时，在既不能确认收货、也不能退款的情况下应该如何处理？

A：按照截图示例传参，即可完成发货，订单状态由21转为30，订单状态变更后就可以正常流转

注：传参时order_id与out_order_id二选一传参

2.6 调试售后接口，完成售后接口调用

2.6.1 售后流程、超时时间及售后事件和API、回调的对应关系

看本文1.2 售后流程图

用户及商户处理售后超时时间

售后事件和API、回调的对应关系

2.6.2 售后接口常见错误及注意事项

注意事项

• 新旧接口不可混用，新售后接口无法处理旧接口订单，否则会出现很多意想不到的错误

2.6.2.1 枚举值定义

（1）AfterSalesReason

（2）AfterSalesState

2.6.2.2 Q：调用自定义交易组件售后相关接口：“创建售后单”、“用户取消售后单”、“用户上传物流信息”、“获取售后单列表”、“获取售后单详情”、“同意退款“、”同意退货“、“拒绝售后”、“上传退款凭证”、“更新售后单”等接口时报错{“errcode”: 48001,“errmsg”: “api unauthorized”}

A18:未开通视频号场景经营商户号，需要先开通场景经营商户号才可以调用。

2.6.2.3 Q：调用自定义交易组件创建售后接口ecaftersale/add时报错2747002，参数错误{“errcode”:2747002,“errmsg”:"参数错误 "}

A9：1.请检查“orderamt”参数，传参金额应不含邮费。

2.新旧接口不可混合调用，新接口不支持对旧接口生成的订单创建售后。

2.6.2.4 Q：调用自定义交易组件创建售后接口ecaftersale/add时报47001错误{“errcode”:47001,“errmsg”:"data format error "}

A：请检查“product_info”字段，注意对应类型为“object”。

2.6.2.5 Q：调用自定义交易组件“同意退款”接口shop/ecaftersale/acceptrefund时报错“同意退款失败” {“errcode”:9700209,“errmsg”:"同意退款失败 退款失败“}

A：1.该问题是订单流转状态不对导致，请严格按照文档流程进行操作调用；

2.新旧接口混合调用也会报此错误

3.“orderamt"传参为"0”

2.6.2.6 Q：用自定义交易组件创建售后接口ecaftersale/add时是报错“售后金额不合法，大于最大可退款金额”{“errcode”:2747014,“errmsg”:" 售后金额不合法，大于最大可退款金额"}

A：1.请确认请求创建售后时"orderamt"金额是否大于下单时"sku_real_price"金额

2.订单已进行部分退款