• 组件概述
  • 基础内容
  • 视图容器
  • 表单
  • 导航
  • 媒体
  • 画布
  • 地图
  • 开放能力
  • 行业开放
  • 交易系统
  • 交易系统组件开发指南
  • pay-button 交易按钮(旧版)
  • consume-card 抖音码核销
  • pay-button 交易按钮(行业 SDK)
  • 评价
  • 电商(即将废弃)
  • 原生组件
  • pay-button 交易按钮(行业 SDK)

    收藏
    我的收藏
    前端模板提供了一个入口组件pay-button,该组件是行业 sdk 内置组件,通过这个组件实现从小程序跳转到交易模板页面,可直接使用。后续新功能将在新版 pay-button 上进行迭代,老的 pay-button 不再继续维护。
    使用此组件参考 交易系统组件开发指南 完成前置配置。
    使用限制:
      1.基础库 2.85.0 版本支持本组件。
      2.仅在行业 SDK 上才支持,需要在代码中配置行业 SDK 的权限:行业 SDK 的权限配置
      3.使用 pay-button 需要行业 sdk 支持,可以通过以下方法判断。
    // 判断是否支持行业sdk 的 pay-button 组件 if (tt.canIUse("industrySDK.pay-button")) { // do something }

    属性说明

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

    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': 失败
    行业 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 说明

    // 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 函数。
      若无需传入 eextra 参数,该方法可不填。
    // 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
    退款的商品单号
    refundAmount
    number
    该 itemOrderId 需要退款的金额
      单位:分
      不能大于该 itemOrderId 实付金额,未填入该字段,则默认为对应子单最大退款金额
    // 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/c050 f399ac447daf2715e11e6976c2e2~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:不接入交易规则
    marketingVersion
    number
    1
    营销版本
      1 :旧版营销,旧版营销前端不支持用户勾选等交互行为(需要在服务端接入查询营销信息扩展点 & 算价扩展点 )
      2 :新版营销,新版营销前端支持用户勾选等交互行为(需要在服务端接入 查询营销算价二合一 拓展点 & 需要在代码中配置行业 SDK 的权限:行业 SDK 的权限配置)。
    注意:
      对于融合团购商品,可以不用接入营销算价二合一接口,开发者可以在抖音来客配置商品对应的营销活动,进入提单页时会展示营销算价信息
    relationType
    number
    商品和用户信息对应关系
      1:1 份商品对应 1 个用户信息
      2:n 份商品对应 reservationCount 个用户信息
    validation
    object
    详见 Validation 类型说明

    GoodsLabel 类型说明

    object 类型,属性如下。
    最低版本支持 行业 SDK
    属性名
    类型
    默认值
    必传
    说明
    type
    string
    标签类别,详见 type 的合法值
    value
    number
    天数
      取值范围为 1 ~ 99
      当 type 为 'REFUNDABLE_DAYS' 或者 'BOOK_IN_ADVANCE' 时必传
      必须为整型值,不能为浮点数
    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_ANYTIMEREFUNDABLE_DAYS 互斥,即 “随时退” 与 “ x 日内可退” 互斥。
      RESERVATION_FREEBOOK_IN_ADVANCE 互斥,即 “免预约” 与 “提前 x 日预约” 互斥。
      NON_REFUNDABLEREFUNDABLE_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 方法,否则可能会导致后续跳转失败。
    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 说明

      当错误发生时触发。
      错误原因可能是因为必填参数不合法,服务端请求错误等。
    // 错误信息含义见下文 bind:error报错信息 handleError(event) { const { errMsg, errNo} = event.detail; }
      事件对象的 detail 为 object 类型,属性如下。
    属性名
    类型
    说明
    最低支持版本
    errMsg
    string
    组件内部错误信息,如传入属性类型错误等
    行业 SDK
    <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
    订单数据错误,无法生成订单
    21519
    biz-line 非法
    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
    查询退款详情失败,服务端错误
    21538
    内部订单号和外部订单号均未填入 should set orderId or outOrderNo
    21539
    退款商品列表和 refundTotalAmount 均未填入
    should set refundGoodsList or refundTotalAmount
    21540
    商品价格计算结果和传入的总价 totalAmount 不同
    totalAmount doesn't match the calculation results of goodsList
    21541
    获取营销信息,服务端数据错误
    21542
    获取计价信息,服务端错误
    21543
    获取计价信息,服务端数据错误
    21545
    computePromotion:fail 扩展点: uery_and_calculate,调用失败
    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

    moede 代码示

    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" />
    <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 的文档。