pay-button 交易按钮(旧版)

收藏
我的收藏
基础库 2.43.0.0 开始支持本组件。​
本文档为旧版,后续新功能将在新版 pay-button :pay-button 交易按钮(行业sdk)上进行迭代,旧版 pay-button 不再继续维护。​
请移步文档:pay-button 交易按钮(行业sdk),注意「使用限制」处说明。​
前端模板提供了一个入口组件pay-button,该组件是小程序基础库内置组件,通过这个组件实现从小程序跳转到交易模板页面,可直接使用。​
使用此组件参考交易系统组件开发指南完成前置配置。​

属性说明​

属性名​
类型​
默认值​
必填​
说明​
最低支持版本​
mode​
number​
1​
否​
组件的使用模式​
    1:已下单​
    2:未下单​
2.43.0.0​
goods-id​
string​
无​
否(mode 为2,该属性必传)​
商品id​
    mode 为 2 时,该属性必传​
    商品库商品传 spuid,非商品库商品传开发者订单系统商品号。​
    课程库商品传product_id,注意需要将product_id从int64类型转换成string传入​
    字段长度为1~64字节,详见 Bug & Tip
2.43.0.0​
goods-type​
number​
无​
否(mode 为2时,该属性必传)​
商品类别,mode 为 2 时,该属性必传​
    1:商品库商品传​
    2:非商品库商品传​
目前只支持商品库商品,非商品库商品需要申请白名单;​
泛知识商品必须传 1​
2.43.0.0​
order-status​
number​
0​
否​
已下单场景mode = 1下,细分订单状态order-status
    0:继续支付​
    1:申请退款​
    2:退款中​
    3:退款成功​
    4:退款失败​
2.43.0.0​
order-id​
string​
无​
否​
开发者订单系统的交易订单号;​
已下单场景mode = 1下,为以下订单状态时,该属性必传:​
    继续支付(order-status 为 0)​
    申请退款(order-status 为 1)​
2.43.0.0​
refund-id​
string​
无​
否​
开发者订单系统的退款单号,用于查看退款详情;​
已下单场景mode = 1下,为以下订单状态时,该属性必传:​
    退款中(order-status 为 2)​
    退款成功(order-status 为 3)​
    退款失败(order-status 为 4)​
2.43.0.0​
refund-total-amount​
number​
无​
否​
退款金额​
    针对交易系统之前的老订单申请退款(order-status 为 1),该属性必传​
    单位:分​
    如何哪些情况下为老订单,详见 Bug & Tip
2.43.0.0​
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 时,该属性必传​
2.43.0.0​
bind:placeorder​
EventHandle​
无​
否(mode 为 2 时,该属性必传)​
跳转至提单页前的准备工作​
    mode 为 2 时,该属性必传​
    内容取决于开发者,但下单需要用户处于登录状态​
2.43.0.0​
bind:error​
EventHandle​
无​
否​
    组件传入属性异常、组件内部发生异常时触发​
2.43.0.0​
bind:applyrefund​
EventHandle​
无​
否​
透传退款参数​
    用于申请退款场景​
    开发者可以在该方法中,通过返回一个对象,定义一些透传信息。前端模板会将返回的对象通过 JSON.stringify进行序列化,序列化的字符串会作为申请退款时的 cp_extra 参数,透传给开发者服务端。​
2.43.0.0​
bind:refund​
EventHandle​
无​
否​
退款回调​
    用于申请退款场景​
    开发者可以在该方法中,根据提交退款申请的状态返回值,实现开发者自定义的逻辑​
2.43.0.0​
bind:pay​
EventHandle​
无​
否(mode 为2时,该属性必传)​
支付回调​
    用于立即抢购、继续支付场景​
    开发者可以在该方法中,根据支付状态返回值,实现开发者自定义的逻辑​
2.43.0.0​

bind:pay 说明​

    继续支付:​
// bind:pay 使用示例 handleContinutePay(event) { const { status, outOrderNo, result } = event.detail; if (status === 'success') { const { code } = result; if (code === 0) { // 继续支付成功 } } 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 { // 支付失败(超时、取消、关闭) } } else { const { errMsg } = result; } }
    事件对象的 detail 为 object 类型,属性如下:​
属性名​
类型​
说明​
最低支持版本​
status​
string​
是否成功拉起小程序收银台​
    success:成功​
    fail:失败​
2.43.0.0​
orderId​
string​
抖音交易系统内部订单号​
2.43.0.0​
outOrderNo​
string​
开发者传入的开发者系统交易订单号​
2.43.0.0​
result​
object​
根据 status 属性返回支付结果​
2.43.0.0​

result 属性说明​

object 类型,属性如下:​
    status 为 success 时:​
属性名​
类型​
说明​
最低支持版本​
code​
number​
    0:支付成功​
    1:支付超时​
    2:支付失败​
    3:支付关闭​
    4:支付取消​
    9:订单状态开发者自行获取​
只要调起收银台成功,支付都会回调成功,开发者依据返回的 code 值,进行后续业务逻辑处理​
2.43.0.0​
orderId​
string​
抖音交易系统内部交易订单号​
2.43.0.0​
    status 为 fail 时:​
属性名​
类型​
说明​
最低支持版本​
errMsg​
string​
API 支付错误码​
    10000: 支付失败​
    10001: 调起微信失败​
    10002: 微信未安装​
2.43.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​
发起申请退款结果​
    发起成功:'success'​
    发起失败:'fail'​
2.43.0.0​
result​
object​
根据 status 属性返回支付结果​
2.43.0.0​

result 属性说明​

object 类型,属性如下:​
    status 为 success 时:​
属性名​
类型​
说明​
最低支持版本​
refundId​
string​
抖音交易系统内部退款单号​
2.43.0.0​
outRefundNo​
string​
开发者系统退款单号​
注意:融合链路不返回outRefundNo​
2.43.0.0​
orderId​
string​
抖音交易系统内部交易订单号​
2.43.0.0​
    status 为 fail 时:​
属性名​
类型​
说明​
最低支持版本​
errMsg​
string​
失败错误信息​
2.43.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); }); },
    事件对象的 detail 为 object 类型,属性如下:​
属性名​
类型​
说明​
最低支持版本​
orderId​
string​
开发者传入的开发者系统交易订单号​
2.43.0.0​

指定金额退款​

指定金额退时,需要通过 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​
// 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 函数。​
// 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: '周一至周日可用', validation: { phoneNumber: { required: true // 手机号是否必填, 为 true则必填,false选填,默认选填 } }, 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: '周一至周日可用', validation: { phoneNumber: { required: true // 手机号是否必填 } }, // 在 bind:getgoodsinfo 返回的 promise 的 resolve 函数中新增 marketingVersion 字段 marketingVersion: 2, }); }) }
    事件对象的 detail 为 object 类型,属性如下:​
属性名​
类型​
说明​
最低支持版本​
goodsId​
string​
商品 id​
2.43.0.0​
goodsType​
number​
商品类型​
2.43.0.0​
    商品信息说明如下:​
字段名​
类型​
默认值​
必传​
说明​
currentPrice​
number​
无​
否​
注意:非商品库商品必传
商品单价​
    单位:分​
    非商品库商品必传​
    价格范围是 1 - 999999999​
    必须为整型值,不能为浮点数​
goodsName​
string​
无​
否​
注意:非商品库商品必传
商品名称​
    非商品库商品必传(特别提醒 Bug & Tip )​
    字段长度为区间值 [1, 256] 字节(字节与字符串说明见下方 Bug & Tip)​
goodsPhoto​
string​
无​
否​
注意:非商品库商品必传
商品图片​
    非商品库商品必传​
    字段长度为 [1, 512] 字节(字节与字符串说明见下方 Bug & Tip )​
    图片类型支持 jpg、jpeg、gif、webp​
goodsLabels​
GoodsLabel[]​
无​
否​
商品标签​
    最多设置三个标签​
    商品库商品标​
minLimits​
number​
1​
否​
起购份数​
    范围是 1 - 99999(minLimits与maxLimits关系见 Bug & Tip )​
    必须为整型值,不能为浮点数​
maxLimits​
number​
99999​
否​
限购份数​
    范围是 1 - 99999(minLimits与maxLimits关系见 Bug & Tip)​
    必须为整型值,不能为浮点数​
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​
否​
营销版本​
注意:​
    对于融合团购商品,可以不用接入营销算价二合一接口,开发者可以在抖音来客配置商品对应的营销活动,进入提单页时会展示营销算价信息​
2.76.0.0​

GoodsLabel 类型说明​

object 类型,属性如下​
属性名​
类型​
默认值​
必传​
说明​
最低支持版本​
type​
string​
无​
是​
标签类别​
2.43.0.0​
value​
number​
无​
否​
天数​
    取值范围为 1~99​
    当 type 为 REFUNDABLE_DAYS 或者 BOOK_IN_ADVANCE 时必传​
    必须为整型值,不能为浮点数​
2.43.0.0​
type 的合法值​
值​
说明​
最低支持版本​
EXPIRED_RETURNS​
过期退​
2.43.0.0​
REFUND_ANYTIME​
随时退​
2.43.0.0​
RESERVATION_FREE​
免预约​
2.43.0.0​
REFUNDABLE_DAYS​
x 日内可退​
2.43.0.0​
BOOK_IN_ADVANCE​
提前 x 日预约​
2.43.0.0​
NON_REFUNDABLE​
不可退​
2.50.0.0​
最多设置三个标签,并且存在以下互斥关系:​
    REFUND_ANYTIMEREFUNDABLE_DAYS 互斥,即 “随时退” 与 “x 日内可退” 互斥。​
    RESERVATION_FREEBOOK_IN_ADVANCE 互斥,即 “免预约” 与 “提前 x 日预约” 互斥。​
    NON_REFUNDABLEREFUNDABLE_DAYS REFUND_ANYTIME互斥,即 “不可退”与“随时退” 、 “x 日内可退” 互斥。​
    只做展现。​

bind:placeorder 说明​

由于在前端模板中进行下单需要用户登录,所以建议在此处完成登录或提醒用户打开设置给予相应权限。​
需要返回 promise,开发者可以在 promise 中完成用户登录,然后调用 resolve 函数。​
属性名​
类型​
说明​
最低支持版本​
goodsId​
string​
商品id​
2.43.0.0​
    若无法完成相关逻辑,则一定要触发 reject 方法,否则可能会导致后续跳转失败。​
userLogin(event) { const { goodsId , goodsType } = event.detail return new Promise((resolve, reject) => { tt.login({ success() { // 用户登录成功并获取信息,则调用 resolve 函数,跳转至提单页 resolve(); }, fail() { // 用户登录失败,则跳转提单页失败 reject(); } }); }); },
    事件对象的 detail 为 object 类型,属性如下:​
属性名​
类型​
说明​
最低支持版本​
goodsId​
string​
商品 id​
2.43.0.0​
goodsType​
number​
商品类型​
2.43.0.0​

bind:error 说明​

    当错误发生时触发。​
    错误原因可能是因为必填参数不合法,服务端请求错误等。​
// 错误信息含义见下文 bind:error报错信息 handleError(event) { const { errMsg ,errNo} = event.detail; }
    事件对象的detail 为 object 类型,属性如下:​
属性名​
类型​
说明​
最低支持版本​
errMsg​
string​
组件内部错误信息,如传入属性类型错误等​
2.43.0.0​
<pay-button ... //任意模式下均可使用bind:error bind:error="handleError" />

bind:error 报错信息​

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 或 不填 (组件的使用模式:已下单)​

Case​
示例​
操作效果​
order-status为 0 或不填时​
点击后拉起收银台。​
order-status 为 1 时​
点击后进入申请退款页面。​
order-status 为 2、3、4 时​
点击后进入退款详情页面。​

Case 2 :mode 为 2 (组件的使用模式:立即抢购)​

根据 goods-type 商品类别分为:​
    商品库商品:​
    库存大于 0:根据商品售卖时段,展示状态分为:即将开始立即抢购已结束。​
    库存等于 0:展示状态为已售罄。​
    非商品库商品:​
    展示状态:立即抢购。​
    操作效果:点击后进入提单页。​

Case 3 :KA 解决方案退款场景​

    常用于order-status 为 1 的情况:​
    操作效果:点击后进入申请退款页面。​

Case 4 :新版营销 marketingVersion为 2 ​

代码示例​

Case 1 :mode 为 1 或不填​

    继续支付:​
<pay-button order-status="{{0}}" order-id="xxx" bind:pay="onContinutePay" />
    申请退款:​
    使用交易系统生成的新订单:​
<pay-button order-status="{{1}}" order-id="xxx" bind:refund="onRefund" bind:applyrefund="applyRefund" />
    对于交易系统之前的老订单,需传入 refund-total-amount:​
// 示例:老订单申请退款 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}}" />
    退款中:​
<pay-button order-status="{{2}}" refund-id="xxx" />
    退款成功:​
<pay-button order-status="{{3}}" refund-id="xxx" />
    退款失败:​
<pay-button order-status="{{4}}" refund-id="xxx" />

Case 2 :mode 为 2,立即抢购​

<!-- 商品库商品 --> <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" />

Bug & Tip​

    Tip:字符串是 UTF-8 编码,一个汉字 3 个字节,一个字母 1 个字节,一个数字为 1 个字节。​
    Tip:在接入该模板之前,可能开发者之前已经接入过「担保支付」或「交易模板1.0」,并且线上已经产生过一部分订单(“老订单”)。在该场景下,想要使用模板进行老订单的退款,需要通过传入 refund-total-amount 指定退款金额。​
    Tip:退款组件必须放在订单详情页的首屏。​
    Tip:商品库的商品,必须按照传商品 id 下单,否则影响订单同步、达人等级、佣金结算等,后期系统也会自动巡查,发现不合规的情况会做下架等处理。​
    Tip:minLimits 应小于 maxLimits ,若 minLimits >= maxLimits ,组件内部会进行自动转换,minLimits 和 maxLimits 的值均转换为 maxLimits 。​
    Tip:关于支付可参考 tt.pay 的文档 。​
    Tip:对于部分开发者希望用 uniapp 或者 taro 等框架接入交易模版的情况,由于pay-button是新增组件,框架暂未适配,因此需要使用原生组件混合的方式接入,请参考以下两个demo:uniapp-demotaro-demo。​