pay-button
接口说明
- •pay-button 是交易的核心组件,可用于从小程序跳转至交易模板页面或触发退款流程。
- •若预约单处于预约中,需调用预约接单结果回调接口完成接单,完成接单后再进行退款操作
- •须严格遵照规范接入 pay-button 组件,否则小程序审核会被驳回。
- •订单核销后不支持通过pay-button组件退款。
- ◦若小程序因订单完成状态下缺少售后入口被处罚或者审核驳回,需在小程序内增加联系商家退款入口。
组件退款逻辑
- •融合链路
- ◦预约品订单
- ▪未预约退款:免审核
- ▪已预约协同退款:需审核
- ▪已预约→取消预约→再退款:免审核
- ◦团购订单
- ▪三方码订单核销前退款:需审核
- ◦其余类型订单免审
- •非融合链路
- ◦需审核
注意
microapp-trade-plugin方式引入的pay-button已不再维护。如需用到pay-button的新能力,需按照以下步骤及顺序使用生服插件中提供的pay-button
Tips
•Tip:字符串是 UTF-8 编码,一个汉字 3 个字节,一个字母 1 个字节,一个数字为 1 个字节。
•Tip:在接入该模板之前,可能开发者之前已经接入过「担保支付」或「交易模板 1.0」,并且线上已经产生过一部分订单(“老订单”)。在该场景下,想要使用模板进行老订单的退款,需要通过传入 refund-total-amount 指定退款金额。
•Tip:退款组件必须放在订单详情页的首屏。
•Tip:商品库的商品,必须按照商品 id 下单,否则影响订单同步、达人等级、佣金结算等,后期系统也会自动巡查,发现不合规的情况会做下架等处理。
•Tip:minLimits 应小于 maxLimits ,若 minLimits >= maxLimits ,组件内部会进行自动转换,minLimits 和 maxLimits 的值均转换为 maxLimits 。
•Tip:IDE 目前由于登录态原因不支持调试,调试 PayButton 请以预览扫码的小程序调试结果为准。
•Tip:组件退款原因仅支持平台预设选项,不支持自定义编辑。
使用限制
- 1.在使用生服插件中的组件和 API 前,需要对行业插件有一个基本了解,可以参考文档:行业插件介绍,然后按照以下步骤及顺序使用生服插件中的能力:
- 2.参考 申请行业插件 完成插件的申请,注意只有小程序拥有生服类目资质才可见申请入口;
- 3.参考 使用行业插件 进行能力的调用;
- 4.行业插件目前仅在抖音版本32.9.0(基础库版本3.56.0.2)及以上支持,如遇加载失败问题,详见生服插件加载失败解决方案
- 5.在使用组件时需要在页面 index.json 文件中引入
// index.json { "usingComponents": { "pay-button-sdk": "tta5a3d31e3aecfb9b11://pay-button" } }
- 6.完成组件引用后,即可像自定义组件一样使用
pay-button// index.ttml <pay-button-sdk mode="{{2}}" goods-type="{{1}}" goods-id="xxxx" bind:getgoodsinfo="getGoodsInfo" bind:placeorder="userLogin" bind:pay="onPay" />
注意
组件名引入一定要和上方示例保持一致,不能叫pay-button
属性说明
属性名 | 类型 | 默认值 | 必填 | 说明 |
mode | number | 1 | 否 | 组件的使用模式
|
goods-id | string | 无 | 否 (mode 为 2 时该属性必传) | 商品 id
发者订单系统商品号。
|
goods-type | number | 无 | 否 (mode 为 2 时该属性必传) | 商品类别,mode 为 2 时,该属性必传
目前只支持商品库商品,非商品库商品需要申请白名单; 泛知识商品必须传 1 |
order-status | number | 0 | 否 | 已下单场景 mode 为 1 时,细分订单状态 order-status
|
order-id | string | 无 | 否 | 已下单场景 mode 为 1 时,为以下订单状态时,该属性必传:
|
refund-id | string | 无 | 否 | 开发者订单系统的退款单号,用于查看退款详情; 已下单场景 mode 为 1 时,为以下订单状态时,该属性必传:
|
refund-total-amount | number | 无 | 否 | 退款金额
|
apply-refund-params | ApplyRefundParams 说明见下方 | 无 | 否 | 退款参数(仅uniapp或taro开发需要,原生抖音小程序不需要) |
biz-line | number | 1 | 否 如果是泛知识类型则必填 | 业务线类型
|
fee-details-list | FeeDetailsInfo[] FeeDetailsInfo 说明见下文 | 无 | 否(存在额外费用比如打包费、配送费、基建费、燃油费、税费时,必传) | 费用明细列表 (航司或外卖可传) |
marketing-ready | boolean | false | 否 | 是否配置了营销扩展点
注意: 传 true 时,营销版本的选择参考 bind:getgoodsinfo 中 marketingVersion 字段 |
bind:getextensionpath | EventHandler | -- | 否 | 特别提醒,如果需要接入积分类型营销,此方法必填,参考插件扩展使用指南部分 |
bind:getgoodsinfo | EventHandler | 无 | 否 (mode 为 2 时该属性必传) | 获取商品信息 mode 为 2 时,该属性必传 详见 bind:getgoodsinfo 说明 |
bind:placeorder | EventHandler | 无 | 否 (mode 为 2 时该属性必传) | 跳转至提单页前的准备工作
详见 bind:placeorder 说明 |
bind:error | EventHandler | 无 | 否 |
|
bind:applyrefund | EventHandler | 无 | 否 | 透传退款参数
详见 bind:applyrefund 说明 |
bind:refund | EventHandler | 无 | 否 | 退款回调
详见 bind:refund 说明 |
bind:pay | EventHandler | 无 | 否 (mode 为 2 时该属性必传) | 支付回调
|
FeeDetailsInfo
属性名 | 类型 | 默认值 | 是否必填 | 说明 | 最低支持版本 |
feeType | number | | 是 | 费用类型 •1: 配送费 •2: 包装费 •18:基建费 •19:燃油费 •20:税费 | 2.51.0.0 |
feeAmount | number | | 是 | 费用总金额 | 2.51.0.0 |
feeDiscountAmount | number | 0 | 否 | 费用总优惠金额 | 2.51.0.0 |
feeDesc | string | | 否 | 费用描述 | 2.51.0.0 |
bind:pay 说明
- •继续支付。
// bind:pay 使用示例 handleContinutePay(event) { const { status, outOrderNo, result } = event.detail; if (status === 'success') { const { code } = result; if (code === 0) { // 继续支付成功 } else { // 继续支付失败(超时、取消、关闭) } } else { } }
- •立即抢购。
- ◦当用户在提单页点击「立即支付」按钮后,会拉起小程序收银台,当用户实际完成了支付或选择关闭收银台取消支付,以及预下单接口报错时,前端模板会调用该方法。
- ◦开发者可以在该方法中,根据支付返回结果,完成开发者自定义的逻辑,如跳转订单列表页等。
/** * status: 支付状态,'success' | 'fail' * orderId: 抖音交易系统内部订单号,类型为 string * outOrderNo:开发者系统交易订单号,类型为 string * result: 创建订单、tt.pay 支付结果,类型为 object */ handlePay(event) { const { status , orderId , outOrderNo , result } = event.detail; if (status === 'success') { const { code } = result; if (code === 0) { // 支付成功 } } else { // 支付失败(超时、取消、关闭) const { errMsg } = result; } }
- •事件对象的 detail 为 object 类型,属性如下;
属性名 | 类型 | 说明 | 最低支持版本 |
status | string |
详细用法参考上方示例 | 2.51.0.0 |
orderId | string | 抖音交易系统内部订单号 | 2.51.0.0 |
outOrderNo | string | 开发者传入的开发者系统交易订单号 | 2.51.0.0 |
result | object | 根据 status 属性返回支付结果,详见 result 属性说明 | 2.51.0.0 |
result 属性说明
object 类型,属性如下
属性名 | 类型 | 说明 | 最低支持版本 |
code | number |
只要调起收银台成功,支付都会回调成功,开发者依据返回的 code 值,进行后续业务逻辑处理 | 2.51.0.0 |
orderId | string | 抖音交易系统内部交易订单号 | 2.51.0.0 |
errMsg | string | API 支付错误码
| 2.51.0.0 |
bind:refund 说明
// bind:refund 使用示例 handleRefund(event) { const { status, result } = event.detail; if (status === 'success') { const { refundId, outRefundNo } = result; } else { const { errMsg } = result; } }
事件对象的 detail 为
object 类型,属性如下。属性名 | 类型 | 说明 | 最低支持版本 |
status | string | 发起申请退款结果
| 2.51.0.0 |
result | object | 根据 status 属性返回支付结果,详见 result 属性说明 | 2.51.0.0 |
result 属性说明
object 类型,属性如下。- •当
status 为 success 时。属性名 | 类型 | 说明 | 最低支持版本 |
refundId | string | 抖音交易系统内部退款单号 | 2.51.0.0 |
outRefundNo | string | 开发者系统退款单号 | 2.51.0.0 |
orderId | string | 抖音交易系统内部交易订单号 | 2.51.0.0 |
- •当
status 为 fail 时。属性名 | 类型 | 说明 | 最低支持版本 |
errMsg | string | 失败错误信息 | 2.51.0.0 |
bind:applyrefund 说明
开发者需要返回 promise,可以在 promise 中做退款参数的设置,并将需要透传的退款参数作为返回值传入 resolve 函数。
- •若无需传入 extra 参数,该方法可不填。
// bind:applyrefund 使用示例 applyRefund(event) { const { orderId } = event.detail; const extra = { orderId }; // 开发者需要透传的参数,可自定义内容 return new Promise(resolve => { resolve(extra); }); },
//融合非预约品退款使用示例 applyRefund(event) { const { orderId } = event.detail; const goodsDetail = [ { itemOrderId:'8000xxxx'//商品单,可在预下单回调itemOrderlist里获取,或通过查询券状态接口获取 } ]; const extra = { orderId , goodsDetail}; // 开发者需要透传的参数,可自定义内容 console.log(extra,"退款参数打印"); return new Promise(resolve => { resolve(extra); }); },
- •事件对象的 detail 为
object 类型,属性如下。属性名 | 类型 | 说明 | 最低支持版本 |
orderId | string | 开发者传入的开发者系统交易订单号 | 2.51.0.0 |
指定金额退
- •指定金额退时,需要通过 bind:applyrefund 传入 itemOrderList。
- •itemOrderList 可和其他透传参数一同通过 bind:applyrefund 传入,可见下方代码说明。
itemOrderList 说明
itemOrderList 是一个长度至少为 1 的数组,不可传递 undefined 或 null 。
字段名 | 类型 | 是否必传 | 描述 |
itemOrderId | string | 是 | 退款的商品单号 |
refundAmount | number | 否 | 该 itemOrderId 需要退款的金额
|
