通用交易系统接入指引
收藏一、接入前准备
- 1.完成交易能力的权限申请，路径：控制台-小程序-能力-解决方案，选择「交易类小程序通用」，依次开通下表中的各类能力权限（申请后自动审核通过）。
- ◦通用交易系统 OpenAPI 接口能力（调用交易系统 API 的必需条件）
- ◦通用交易系统退款扩展点（用于接收退款申请回调）
- ◦通用交易系统支付消息（用于接收支付成功回调）
- ◦通用交易系统退款消息（用于接收退款结果回调）
- ◦通用交易系统分账消息（用于接收分账结果回调）
- 2.等待 5 分钟后在「控制台-小程序-开发-解决方案配置」下配置回调地址。
- 3.回到上一级页面点击「发布上线」。
二、关键节点
关键节点 | 说明 |
| 该环节是使用交易能力的前提，进件是开通支付账户的过程。 说明 之前已接入过担保支付或行业交易系统的开发者/服务商，无需再做进件。 |
| 可通过此接口，完成交易下单及支付，留存订单相关信息。 |
|
|
| 开发者可对接平台提供的发起退款 API，用户也可以通过平台统一入口发起退款，因此均需对接回调扩展点及审核接口，接受用户多端退款请求。
综合确定订单的后续处理流程。 |
|
|
| 开发者发起分账后，如果发生退款，可以从已分账方退回分账到商户可提现账户。 只支持外部分账方的退分账，不支持平台抽佣、手续费等退分账 |
| 当开发者发起提现后，资金从「可提现账户」到商户的银行账户。 |
8 获取对账单 | 开发者可定期获取平台提供的对账单进行对账。 |
三、各环节说明
3.1 商户进件
若已接入过担保支付或行业交易系统， 则可跳过“进件”环节。
如需要开发测试阶段与生产环境数据隔离，可以新增商户号，新商户号作为测试商户号，正式使用的商户号不会受到测试数据影响。
3.2 交易下单
3.2.1开发步骤
仅需两步：
- 1.使用 tt.requestOrder 发起下单。
- 2.使用 tt.getOrderPayment 拉起收银台进行支付。
3.2.2收款模式（可选阅读）
模式 | 说明 |
默认收款模式 | 每个小程序开通的第一个商户号（即最后一位为 0 的商户号）为小程序的默认收款商户号。 开发者在调用预下单接口时，无需传入收款商户号，商户系统会根据小程序 appid 默认匹配尾号为 0 的商户号进行收款。 |
多门店模式 | 随着小程序业务发展，默认收款模式无法满足部分小程序的需求，一个小程序下的不同商品可能需要通过不同商户号收款，于是衍生出多门店收款模式。 如果有多门店收款需求，请联系客服提供小程序 appid 添加多门店白名单。加入白名单后，开发者可以在下单环节在 merchantUid 字段将本单要使用的商户号传入，以实现不同商品/不同订单收款到不同商户号的诉求。注意 如果小程序 appid 不在白名单内，则 无法使用多门店模式。 |
3.2.3调用时序
- 1.开发者/服务商需先调用 tt.requestOrder，下单及获取拉起收银台的相关参数，可通过查询标签组信息服务，查询可传入的标签组ID（tag_group_id）
- 2.开发者/服务商调用 tt.getOrderPayment 拉起收银台，用户可在收银台上选择支付方式并确认支付，收银台上展示的支付工具与商户开通的支付 方式一致。
3.3 履约同步
3.3.1背景说明
- 1.请先参考接入规范，确认所接的商品类型是否需要接入履约，如不需要可跳过此环节。
- 2.通用交易系统梳理了不同行业的各关键业务节点，将其映射为抽象的履约状态，同时规定了这些状态 之间的流转规则。
- 3.开发者需参考这套规则，使用通用交易系统提供的履约同步模式，将订单的履约状态同步给平台。
注意
平台会根据履约状态，判断订单退款时的可退金额，以及订单的可结算时间。
3.3.2履约同步模式
- •模式一：tt.confirmFulfillment，拉起平台统一服务确认弹窗
- ◦作用：拉起平台提供的服务确认组件，引导用户确认关键服务交付节点（如'履约完成')，从而驱动平台订单的状态推进。
- ◦接入：根据接入规范，查看是否需要接入、以及在哪个业务流程引入tt.confirmFulfillment。
- •模式二：通过推送履约状态，由开发者同步
- ◦作用：将履约状态同步给平台，驱动平台订单的状态推进，达到关键节点（如’履约中‘）。
- ◦接入：根据接入规范，查看是否需要接入、以及在哪个业务流程调用履约同步 OpenAPI。
3.3.3调用时序
3.4 交易退款
3.4.1退款入口
- •选择一：用户直接向开发者发起退款。用户在小程序内发起退款申请。
- •选择二：用户直接向平台发起退款。用户从小程序右上角「反馈」入口，选择进入「申请退款」页面（注：抖音 App 最低支持版本为 27.0.0）。退款订单列表页将根据订单所属退款规则标签与订单履约状态，判断用户是否可发起此笔订单退款，及退款是否需要开发者发起审核。
3.4.2调用时序
场景1：用户提交申请，向开发者发起退款
注意
由开发者向平台发起的退款，平台不判断订单履约状态及标签规则，均直接受理退款申请，且异步执行退款。
- •开发者需调用发起退款接口，该接口会同步响应退款申请的受理结果。
- •平台处理渠道退款结果后，返回最终退款结果。
场景2: 用户提交申请，由平台直接发起退款
- 1.用户在平台统一入口发起退款（详见交易退款入口）。
- 2.平台收到退款申请后，根据订单的履约状态及标签规则，判定是否允许退款，若不允许退款则拒绝申请。
- 3.退款申请受理后，平台将向开发者发起退款申请回调，开发者收到回调后，同步返回相关信息（若 72 小时后开发者仍未成功响应，系统会自动通过）。
- ◦若此笔订单对应的规则为需要商家审核，开发者需要接入同步审核结果接口告知平 台退款审核结果。平台接收到审核结果为审核通过后，开始执行退款操作，并通知最终的退款结果。
- ◦若此笔订单对应的规则为无需审核，平台将直接执行退款，并通知最终的退款结果。
5. 交易结算及之后环节
四、开始开发
关键环节 | 接口类型 | 接口地址 | 接口描述 |
进件 | OPENAPI | 提交商户资料，开通商户号以收款或接收分账 | |
发起进件请求需要上传商户证件等图片，需要先调用图片上传接口获 取image_id | |||
开发者/服务商可以通过接口主动查询进件结果 | |||
下单 | JSAPI | 提交平台下单 | |
根据返回单号，拉起收银台 | |||
OPENAPI | 可以查询所属行业及商品对应的交易标签 | ||
将用户支付成功的消息通知给开发者/服务商 | |||
开发者/服务商可以通过接口主动查询查询订单状态 | |||
履约 | JSAPI | 可通过该接口拉起平台统一服务确认弹窗 | |
OPENAPI | 开发者/服务商可以通过接口同步服务交付状态 | ||
退款 | OPENAPI | •发起退款 | 提交平台退款 |
通过该扩展点，告知开发者退款必要的信息 | |||
通过该接口同步商户的退款审核结果注意：如果商品支持退款但未接入“同步退款审核结果”接口，则会导致用户发起退款后直接退款（未经开发者审核）导致资损 | |||
开发者/服务商可以通过接口主动查询退款 结果 | |||
将退款结果通知给开发者/服务商 | |||
结算及分账 | OPENAPI | •发起分账 | 通过该接口发起此笔订单结算及分给其他分账方 |
•查询分账 | 开发者/服务商可以通过接口主动查询分账结果 | ||
将分账结果通知给开发者/服务商 | |||
提现 | OPENAPI | 查询商户各渠道账户余额 | |
•商户提现 | 对可提现账户余额发起提现 | ||
开发者/服务商可以通过接口主动查询提现订单状态 | |||
获取对账单 | OPENAPI | 开发者/服务商可以通过对账单查询接口查询支付、退款、分账、退分账的账单。 | |
开发者/服务商可以通过获取资金账单接口查询商户账户资 金变动情况 |
