pay-button 交易按钮（行业sdk）

更新时间 2024-07-24 02:58:49

我的收藏

基础库 2.85.0 版本支持本组件。

前端模板提供了一个入口组件pay-button，该组件是行业 sdk 内置组件，通过这个组件实现从小程序跳转到交易模板页面，可直接使用。后续新功能将在新版 pay-button 上进行迭代，老的 pay-button 不再继续维护。

使用此组件参考交易系统组件开发指南完成前置配置。

使用限制

仅在行业 SDK 上才支持，需要在代码中配置行业 SDK 的权限：行业 SDK 的权限配置。

使用 pay-button 需要行业sdk支持，可以通过以下方法判断。

JavaScript复制
// 判断是否支持行业sdk 的 pay-button 组件
if (tt.canIUse("industrySDK.pay-button")) {
  // do something
}

属性说明

属性名	类型	默认值	必填	说明	最低支持版本
mode	number	1	否	组件的使用模式 •1：已下单 •2：未下单	行业 SDK
goods-id	string	无	否（mode 为2，该属性必传）	商品id •mode 为 2 时，该属性必传 •商品库商品传 spuid，非商品库商品传开发者订单系统商品号。 •课程库商品传product_id，注意需要将product_id从int64类型转换成string传入 •字段长度为1～64字节，详见 Bug & Tip	行业 SDK
goods-type	number	无	否（mode 为2时，该属性必传）	商品类别，mode 为 2 时，该属性必传 •1：商品库商品传 •2：非商品库商品传目前只支持商品库商品，非商品库商品需要申请白名单；泛知识商品必须传 1	行业 SDK
order-status	number	0	否	已下单场景mode = 1下，细分订单状态order-status •0：继续支付 •1：申请退款 •2：退款中 •3：退款成功 •4：退款失败	行业 SDK
order-id	string	无	否	开发者订单系统的交易订单号；已下单场景mode = 1下，为以下订单状态时，该属性必传： •继续支付（order-status 为 0） •申请退款（order-status 为 1）	行业 SDK
refund-id	string	无	否	开发者订单系统的退款单号，用于查看退款详情；已下单场景mode = 1下，为以下订单状态时，该属性必传： •退款中（order-status 为 2） •退款成功（order-status 为 3） •退款失败（order-status 为 4）	行业 SDK
refund-total-amount	number	无	否	退款金额 •针对交易系统之前的老订单申请退款（order-status 为 1），该属性必传 •单位：分 •如何哪些情况下为老订单，详见 Bug & Tip	行业 SDK
biz-line	number	1	否，如果是泛知识类型则必填	业务线类型 •1：团购 •2：泛知识	2.54.0.0
marketing-ready	boolean	false	否	是否配置了营销扩展点 •true：已配置营销扩展点，进行营销展现并进行营销优惠计算 •false: 未配置，不展现营销信息注意： •传 true 时，营销版本的选择参考 bind:getgoodsinfo 中 marketingVersion 字段	2.54.0.0
bind:getextensionpath	EventHandler 详见 bind:getextensionpath 说明	--	否	•特别提醒，如果需要接入积分类型营销，此方法必填，参考插件拓展使用指南部分	2.76.0.0
bind:getgoodsinfo	EventHandle	无	否（mode 为 2 时，该属性必传）	获取商品信息 •mode 为 2 时，该属性必传详见 bind:getgoodsinfo 说明	行业 SDK
bind:placeorder	EventHandle	无	否（mode 为 2 时，该属性必传）	跳转至提单页前的准备工作 •mode 为 2 时，该属性必传 •内容取决于开发者，但下单需要用户处于登录状态详见 bind:placeorder 说明	行业 SDK
bind:error	EventHandle	无	否	•组件传入属性异常、组件内部发生异常时触发 •具体报错内容见 bind:error 报错信息	行业 SDK
bind:applyrefund	EventHandle	无	否	透传退款参数 •用于申请退款场景 •开发者可以在该方法中，通过返回一个对象，定义一些透传信息。前端模板会将返回的对象通过 JSON.stringify进行序列化，序列化的字符串会作为申请退款时的 cp_extra 参数，透传给开发者服务端。详见 bind:applyrefund 说明	行业 SDK
bind:refund	EventHandle	无	否	退款回调 •用于申请退款场景 •开发者可以在该方法中，根据提交退款申请的状态返回值，实现开发者自定义的逻辑详见 bind:refund 说明	行业 SDK
bind:pay	EventHandle	无	否（mode 为2时，该属性必传）	支付回调 •用于立即抢购、继续支付场景 •开发者可以在该方法中，根据支付状态返回值，实现开发者自定义的逻辑	行业 SDK

bind:pay 说明

•

继续支付

JavaScript复制
// bind:pay 使用示例
handleContinutePay(event) {
    const { status, outOrderNo, result } = event.detail;
    if (status === 'success') {
        const { code } = result;
        if (code === 0) {
            // 继续支付成功
        }
    } else {
        // 继续支付失败
    }
}

•

立即抢购

◦

当用户在提单页点击「立即支付」按钮后，会拉起小程序收银台，当用户实际完成了支付或选择关闭收银台取消支付，以及预下单接口报错时，前端模板会调用该方法。

◦

开发者可以在该方法中，根据支付返回结果，完成开发者自定义的逻辑，如跳转订单列表页等。

JavaScript复制
/**
  * 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 {
            // 支付失败（超时、取消、关闭）
        }
    } else {
        const { errMsg } = result;
    }
}

•

事件对象的 detail 为 object 类型，属性如下

属性名	类型	说明	最低支持版本
status	string	是否成功拉起小程序收银台 •'success': 成功 •'fail': 失败	行业 SDK
orderId	string	抖音交易系统内部订单号	行业 SDK
outOrderNo	string	开发者传入的开发者系统交易订单号	行业 SDK
result	object	根据 `status` 属性返回支付结果，详见 result 属性说明	行业 SDK

result 属性说明

object 类型，属性如下

•

当 status 为 success 时

属性名	类型	说明	最低支持版本
code	number	•0：支付成功 •1：支付超时 •2：支付失败 •3：支付关闭 •4：支付取消 •9：订单状态开发者自行获取只要调起收银台成功，支付都会回调成功，开发者依据返回的 code 值，进行后续业务逻辑处理	行业 SDK
orderId	string	抖音交易系统内部交易订单号	行业 SDK

•

当 status 为 fail 时

属性名	类型	说明	最低支持版本
errMsg	string	API 支付错误码 •10000：支付失败 •10001：调起微信失败 •10002：微信未安装	行业 SDK

bind:refund 说明

JavaScript复制
// bind:refund 使用示例 
handleRefund(event) { 
    const { status, result } = event.detail; 
    if (status === 'success') { 
        const { refundId, outRefundNo } = result; 
    } else { 
        const { errMsg } = result; 
    } 
}

•

事件对象的 detail 为 object 类型，属性如下

属性名	类型	说明	最低支持版本
status	string	发起申请退款结果 •发起成功：'success' •发起失败：'fail'	行业 SDK
result	object	根据 `status` 属性返回支付结果，详见 result 属性说明	行业 SDK

result 属性说明

object 类型，属性如下

•

当 status 为 success 时

属性名	类型	说明	最低支持版本
refundId	string	抖音交易系统内部退款单号	行业 SDK
outRefundNo	string	开发者系统退款单号	行业 SDK
orderId	string	抖音交易系统内部交易订单号	行业 SDK

•

当 status 为 fail 时

属性名	类型	说明	最低支持版本
errMsg	string	失败错误信息	行业 SDK

bind:applyrefund 说明

需要返回 promise，开发者可以在 promise 中做退款参数的设置，并将需要透传的退款参数作为返回值传入resolve函数

•

若无需传入extra参数，该方法可不填

JavaScript复制
// bind:applyrefund 使用示例 
applyRefund(event) { 
    const { orderId } = event.detail; 
    const extra = { orderId }; // 开发者需要透传的参数，可自定义内容 
    return new Promise(resolve => { 
      resolve(extra); 
    }); 
  },

•

事件对象的 detail 为 object 类型，属性如下

属性名	类型	说明	最低支持版本
orderId	string	开发者传入的开发者系统交易订单号	行业 SDK

指定金额退

•

指定金额退时，需要通过 bind:applyrefund 传入 itemOrderList

•

itemOrderList 可和其他透传参数一同通过 bind:applyrefund 传入，可见下方代码说明

itemOrderList 说明

itemOrderList是一个长度最少为1的数组，不可传递 undefined 或 null

字段名	类型	是否必传	描述	最低支持版本
itemOrderId	string	是	退款的商品单号	2.59.0.3
refundAmount	number	否	该 itemOrderId 需要退款的金额 •单位：分 •不能大于该 itemOrderId 实付金额，未填入该字段，则默认为对应子单最大退款金额	2.59.0.3

JavaScript复制
// bind:applyrefund 指定金额退使用示例 
applyRefund(event) { 
    const { orderId } = event.detail; 
    const itemOrderList = [ 
            {itemOrderId:'ot423412',refundAmount:100}, 
            {itemOrderId:'ot423413'}, 
        ] 
    const extra = { orderId , itemOrderList }; 
    return new Promise(resolve => { 
      resolve(extra);// extra 透传至服务端时，当中的 itemOrderList 会被删除 
    }); 
  },

bind:getgoodsinfo 说明

•

需要返回 promise，开发者可以在 promise 中获取相关商品信息，并将商品信息作为返回值传入resolve函数

JavaScript复制
// bind:getgoodsinfo 使用示例 
// 非商品库商品 
getGoodsInfo(event) { 
    const { goodsId } = event.detail; 
    return new Promise(resolve => { 
      // 在此处开发者可以进行商品数据请求，获取商品信息 
      // 然后将商品信息传入 resolve 函数 
      resolve({ 
        currentPrice: 9900, 
        goodsName: '循礼门M+丨【释集烤肉】99元  原价206.4元超值套餐', 
        goodsPhoto: 
          'https://p11.douyinpic.com/img/aweme-poi/product/spu/c050f399ac447daf2715e11e6976c2e2~noop.jpeg?from=3303174740', 
        goodsLabels: [ 
            {type: 'EXPIRED_RETURNS'}, // 过期退 
            {type: 'REFUND_ANYTIME'}, // 随时退 
            {type: 'BOOK_IN_ADVANCE', value: 2} // 提前2日预约 
        ], 
        minLimits: 1, 
        maxLimits: 2, 
        dateRule: '周一至周日可用',
        relationType: 1,
        validation: { 
            phoneNumber: { 
                required: true  // 手机号是否必填, 为 true则必填，false选填，默认选填 
            },
            reservationType: 1,
            reservationCount: 2,
        }, 
        extra: {}, 
        tradeOption:{ 
            life_trade_flag :1 // 0：非融合链路（默认值）  1：走融合链路（标准融合/完全融合）
            is_use_tag :true // 泛知识是否接入交易规则，true：接入 false：不接入（默认值） 
        }, 
        // 在 bind:getgoodsinfo 返回的 promise 的 resolve 函数中新增 marketingVersion 字段 
        marketingVersion: 2, 
      }); 
    }); 
} 
 
// 商品库商品 
getGoodsInfo(event) { 
    return new Promise(resolve => { 
        // 在此处开发者可以进行商品数据请求，获取商品信息 
        // 然后将商品信息传入 resolve 函数 
        resolve({ 
            minLimits: 1, 
            maxLimits: 2, 
            dateRule: '周一至周日可用', 
            relationType: 1,
            validation: { 
                phoneNumber: { 
                    required: true  // 手机号是否必填 
                },
                reservationType: 1,
                reservationCount: 2,
            }, 
            // 在 bind:getgoodsinfo 返回的 promise 的 resolve 函数中新增 marketingVersion 字段 
            marketingVersion: 2, 
        }); 
    }) 
}

•

事件对象的 detail 为 object 类型，属性如下

属性名	类型	说明	最低支持版本
goodsId	string	商品id	行业 SDK
goodsType	number	商品类型	行业 SDK

•

商品信息说明如下

字段名	类型	默认值	必传	说明	最低支持版本
currentPrice	number	无	否注意：非商品库商品必传	商品单价 •单位：分 •非商品库商品必传 •价格范围是 1 - 999999999 •必须为整型值，不能为浮点数
goodsName	string	无	否注意：非商品库商品必传	商品名称 •非商品库商品必传（特别提醒 Bug & Tip ） •字段长度为区间值 [1, 256] 字节（字节与字符串说明见下方 Bug & Tip）
goodsPhoto	string	无	否注意：非商品库商品必传	商品图片 •非商品库商品必传 •字段长度为 [1, 512] 字节（字节与字符串说明见下方 Bug & Tip ） •图片类型支持 jpg、jpeg、gif、webp
goodsLabels	GoodsLabel[]	无	否	商品标签 •最多设置三个标签 •商品库商品标 •详见 GoodsLabel 类型说明
minLimits	number	1	否	起购份数 •范围是 1 - 99999（minLimits与maxLimits关系见 Bug & Tip ) •必须为整型值，不能为浮点数
maxLimits	number	50	否	限购份数 •范围是 1 - 99999（minLimits与maxLimits关系见 Bug & Tip) •必须为整型值，不能为浮点数 •融合链路中，maxLimits最大为50
dateRule	string	周一至周日可用	否	使用规则 •如 “周一至周日可用”、“周一至周五可用”、“非节假日可用” •字段长度最大长度为128字节（字节与字符串说明见下方 Bug & Tip ）
extra	object	无	否	开发者透传参数 •上传服务端时会对extra进行JSON.stringify处理 •字段长度应小于或等于2048字节（字节与字符串说明见下方 Bug & Tip ）
tradeOption	object	无	否	开发者透传参数 •上传服务端时会对extra进行JSON.stringify处理 •字段长度应小于或等于2048字节（字节与字符串说明见下方 Bug & Tip ） •life_trade_flag（默认值为0） ◦0：非融合链路 ◦1：走融合链路（标准融合/完全融合） •is_use_tag（默认值false，泛知识接入交易规则必传） ◦true：接入交易规则 ◦false：不接入交易规则	2.76.0.0
marketingVersion	number	1	否	营销版本 •1 ：旧版营销，旧版营销前端不支持用户勾选等交互行为（需要在服务端接入查询营销信息扩展点 & 算价扩展点） •2 ：新版营销，新版营销前端支持用户勾选等交互行为（需要在服务端接入查询营销算价二合一拓展点 & 需要在代码中配置行业 SDK 的权限：行业 SDK 的权限配置）。注意： •对于融合团购商品，可以不用接入营销算价二合一接口，开发者可以在抖音来客配置商品对应的营销活动，进入提单页时会展示营销算价信息	2.76.0.0
relationType	number		否	商品和用户信息对应关系 •1：1份商品对应1个用户信息 •2：n份商品对应reservationCount个用户信息
validation	object		否	详见 Validation 类型说明

GoodsLabel 类型说明

object 类型，属性如下

属性名	类型	默认值	必传	说明	最低支持版本
type	string	无	是	标签类别，详见type的合法值	行业 SDK
value	number	无	否	天数 •取值范围为 1 ～ 99 •当 type 为 'REFUNDABLE_DAYS' 或者 'BOOK_IN_ADVANCE' 时必传 •必须为整型值，不能为浮点数	行业 SDK

type 的合法值

值	说明	最低支持版本
EXPIRED_RETURNS	过期退	行业 SDK
REFUND_ANYTIME	随时退	行业 SDK
RESERVATION_FREE	免预约	行业 SDK
REFUNDABLE_DAYS	x日内可退	行业 SDK
BOOK_IN_ADVANCE	提前x日预约	行业 SDK
NON_REFUNDABLE	不可退	2.50.0.0

最多设置三个标签，并且存在以下互斥关系

•

REFUND_ANYTIME 与 REFUNDABLE_DAYS 互斥，即 “随时退” 与 “x日内可退” 互斥

•

RESERVATION_FREE 与 BOOK_IN_ADVANCE 互斥，即 “免预约” 与 “提前x日预约” 互斥

•

NON_REFUNDABLE 与 REFUNDABLE_DAYS REFUND_ANYTIME互斥，即 “不可退”与“随时退” 、 “x日内可退” 互斥

•

只做展现

Validation 类型说明

属性	类型	是否必填	默认值	说明
reservationType	number	否		•1：需填写姓名+手机号+身份证 •2：需填写姓名+手机号
reservationCount	number	否		需填写的留资信息数，若relationType为1时，不用传入
phoneNumber	PhoneNumber	否		提单页手机号是否必填

PhoneNumber 说明

属性	类型	是否必填	默认值	说明
required	boolean	否	false	提单页手机号是否必填

bind:placeorder 说明

•

由于在前端模板中进行下单需要用户登录，所以建议在此处完成登录或提醒用户打开设置给予相应权限

•

需要返回 promise，开发者可以在 promise 中完成用户登录，然后调用 resolve 函数

属性名	类型	说明	最低支持版本
goodsId	string	商品id	行业 SDK

•

若无法完成相关逻辑，则一定要触发reject方法，否则可能会导致后续跳转失败

JavaScript复制
userLogin(event) {
const { goodsId , goodsType } = event.detail
    return new Promise((resolve, reject) => {
        tt.login({
            success() {
                // 用户登录成功并获取信息，则调用 resolve 函数，跳转至提单页
                resolve();
            },
            fail() {
                // 用户登录失败，则跳转提单页失败
                reject();
            }
        });
    });
  },

•

事件对象的 detail 为 object 类型，属性如下

属性名	类型	说明	最低支持版本
goodsId	string	商品id	行业 SDK
goodsType	number	商品类型	行业 SDK

bind:error说明

•

当错误发生时触发

•

错误原因可能是因为必填参数不合法，服务端请求错误等

JavaScript复制
// 错误信息含义见下文 bind:error报错信息
handleError(event) {
    const { errMsg ，errNo} = event.detail;
}

•

事件对象的detail 为 object 类型，属性如下

属性名	类型	说明	最低支持版本
errMsg	string	组件内部错误信息，如传入属性类型错误等	行业 SDK

HTML复制
<pay-button 
    ... //任意模式下均可使用bind:error
    bind:error="handleError"
/>

bind:error报错信息

JavaScript复制
errorHandler(event){
    const { errNo , errMsg } = event.detail
    // do something
    // errNo（错误码，对应某种具体报错原因）
    // errMsg（报错信息）
}

errNo（错误码）	含义
21500	mode 非法
21501	goods-id 非法
21502	goods-type 非法
21503	无 bind:getgoodsinfo
21504	无 bind:placeorder
21505	商品库商品获取商品信息，服务端内部错误
21506	商品库商品获取商品信息，服务端校验参数不通过
21507	支付能力查询，服务端内部错误
21508	支付能力查询，服务端校验参数不通过
21509	开发者 bind:getgoodsinfo 调用失败
21510	开发者 bind:placeorder 调用失败
21511	非商品库商品，商品标签校验不通过
21512	bind:getgoodsinfo 传入数据类型错误
21513	点击按钮后触发，获取商品信息中
21514	点击按钮后触发，获取商品信息失败
21515	点击按钮后触发，无支付能力
21516	无 bind:pay 方法
21517	创建订单（预下单），服务端错误
21518	订单数据错误，无法生成订单

21521	order-status 非法
21522	order-id 非法
21523	refund-id 非法
21524	订单为 1.0 版本，但缺少 refund-total-amount
21526	继续支付获取订单信息失败，服务端内部错误
21527	继续支付获取订单信息失败，服务端参数校验不通过
21528	申请退款获取订单信息失败，服务端内部错误
21529	申请退款获取订单信息失败，服务端参数校验不通过
21530	申请退款获取订单信息失败，服务端返回数据缺少商品信息
21531	申请退款获取订单信息失败，订单无可退款订单，订单可退份数等于0
21532	查看退款详情获取退款详情失败
21533	bind:applyrefund 调用失败
21534	bind:applyrefund 返回类型错误
21535	申请退款失败，服务端错误
21536	获取小程序主体名称失败，服务端错误
21537	查询退款详情失败，服务端错误

21546	直跳提单页userLogin调用失败
21547	直跳提单页getExtraInfo调用失败

10000	支付失败
10001	调起微信失败
10002	微信未安装

效果示例

Case 1 ：mode 为 1 或不填（组件的使用模式：已下单）

•

order-status为 0 或不填时

操作效果：点击后拉起收银台

•

order-status 为 1 时

操作效果：点击后进入申请退款页面

•

order-status 为2、3、4时，pay-button展示文字状态

操作效果：点击后进入退款详情页面

Case 2 ：mode 为 2 （组件的使用模式：立即抢购）

根据 goods-type 商品类别分为：

•

商品库商品：

◦

库存大于 0：根据商品售卖时段，展示状态分为：即将开始、立即抢购和已结束。

◦

库存等于 0：展示状态为已售罄。

•

非商品库商品：

◦

展示状态：立即抢购。

操作效果：点击后进入提单页

Case 3 ：KA 解决方案退款场景

•

常用于order-status 为 1 的情况

操作效果：点击后进入申请退款页面

Case 4 ：新版营销 marketingVersion为 2

代码示例

Case 1 ：mode 为 1 或不填

•

继续支付

HTML复制
<pay-button 
    order-status="{{0}}" 
    order-id="xxx" 
    bind:pay="onContinutePay" 
/>

•

申请退款

◦

使用交易系统生成的新订单

HTML复制
<pay-button 
  order-status="{{1}}" 
  order-id="xxx" 
  bind:refund="onRefund" 
  bind:applyrefund="applyRefund"
/>

◦

对于交易系统之前的老订单，需传入 refund-total-amount

HTML复制
// 示例：老订单申请退款 200 元 
<!-- 
    使用交易模板 1.0 生成的老订单，申请退款需要 refudnrefund-total-amount 
    若无需传入 extra 参数，则无需 bind:applyrefund 方法 
--> 
<pay-button 
  order-status="{{1}}" 
  order-id="xxx" 
  bind:refund="onRefund" 
  bind:applyrefund="applyRefund" 
  refund-total-amount="{{20000}}" 
/>

•

退款中

HTML复制
<pay-button 
    order-status="{{2}}" 
    refund-id="xxx" 
/>

•

退款成功

HTML复制
<pay-button 
    order-status="{{3}}" 
    refund-id="xxx" 
/>

•

退款失败

HTML复制
<pay-button 
    order-status="{{4}}" 
    refund-id="xxx" 
/>

Case 2 ：mode 为 2

•

立即抢购

HTML复制
<!-- 商品库商品 --> 
<pay-button 
  mode="{{2}}" 
  goods-type="{{1}}" 
  goods-id="xxxx" 
  bind:getgoodsinfo="getGoodsInfo" 
  bind:placeorder="userLogin" 
  bind:pay="onPay" 
/> 
 
<!-- 非商品库商品 --> 
<pay-button 
  mode="{{2}}" 
  goods-type="{{2}}" 
  goods-id="xxxx" 
  bind:getgoodsinfo="getGoodsInfo" 
  bind:placeorder="userLogin" 
  bind:pay="onPay" 
/>