开发
API

tt.pay 1.19.4+

调起字节跳动小程序收银台支付,或者微信、支付宝 API 支付。详细接入文档见:小程序收银台接入文档

支持支付方式:

微信支付、支付宝

收银台支付支持版本:

今日头条(iOS & Android)7.2.7+版本;抖音 iOS 8.6.0+版本 / Android 7.1.0+版本

API 支付支持版本(不拉起收银台,直接拉起微信/支付宝):

今日头条(iOS & Android)7.4.3+版本;抖音 iOS 9.1.0+版本 / Android 8.7.0+版本

注意:iOS 虚拟物品暂不支持使用支付功能。有虚拟物品支付的开发者,只能在 Android 上使用支付功能

输入

object 类型,属性如下:

属性类型默认值必填说明最低支持版本
successfunction接口调用成功的回调函数1.19.0
completefunction接口调用结束的回调函数(调用成功、失败都会执行)1.19.0
failfunction接口调用失败的回调函数1.19.0
orderInfoobject调起小程序支付收银台的签名订单信息。
该对象由开发者服务端产生并经过 服务端签名 加上 sign 字段后返回;返回后小程序前端 请不要修改 orderInfo 上的字段,否则将会导致签名验证失败。
可使用 支付自助校验orderInfo 参数做初步校验。
1.19.0
servicenumber固定值:1 (拉起小程序收银台)
开发者如果不希望使用头条小程序收银台,service 设置为 3/4 时,可以直接拉起微信/支付宝进行支付:
service=3: 微信 API 支付,不拉起小程序收银台;
service=4: 支付宝 API 支付,不拉起小程序收银台。

其中 service=3、4,仅在 1.35.0.1+基础库支持
1.19.0
getOrderStatusfunction商户前端实现的查询支付订单状态方法(该方法需要返回个 Promise 对象);若开发者不需要微信支付则不用实现(仅在 service=1 时生效)1.19.0
payChannelobject支付渠道配置1.19.0
_debugnumber0仅限调试用,上线前去掉该参数。_debug=1 时,微信支付期间可以看到中间报错信息,方便调试1.19.0

orderInfo 属性如下:

属性类型必填是否参与签名说明
merchant_idstring开发者后台支付设置页的商户号

app_idstring开发者后台支付设置页的 app_id

sign_typestring固定值:MD5。商户生成签名的算法类型
timestampstring发送请求的时间戳,精确到秒
versionstring固定值:2.0
trade_typestring固定值:H5
signstring签名,具体签名方案见 服务端签名
product_codestring固定值:pay
payment_typestring固定值:direct
out_order_nostring商户订单号
uidstring用户唯一标识
total_amountnumber金额,整型,单位:分(不能有小数)
currencystring固定值: CNY。币种
subjectstring商户订单名称
bodystring商户订单详情
trade_timestring下单时间戳,精确到秒。如果两次支付(调用 tt.pay)传入的订单号(out_order_no)相同,则必须保证 trade_time 也相同。
valid_timestring订单有效时间(单位 秒)
notify_urlstring固定值:https://tp-pay.snssdk.com/paycallback
alipay_urlstring调用支付宝 App 支付所需的支付请求参数(形如 'app_id=xxx&biz_content=xxx...''alipay_sdk=xxx&app_id=xxx&biz_content=xxx...'),详见支付宝 App 支付请求参数说明
service=1 时,如不传则不展示支付宝支付;
service=4 时必传。
wx_urlstring调用微信 H5 支付统一下单接口 返回的 mweb_url 字段值(请注意不要进行 urlencode)。
service=1 时,如不传则不展示微信支付;
service=3 时必传。
wx_typestringwx_url 非空时传 'MWEB'。wx_url 为空时,该字段不传
risk_infostring支付风控参数。序列化后的 JSON 结构字符串,JSON 结构如下:{ip: '用户外网IP'}

说明:

  • service=3|4 时,merchant_id, app_id, sign_type, sign, wx_url, alipay_url, wx_type 字段值必须是真实信息;其他字段传非空、符合格式要求内容即可,不强制要求是真实订单信息
  • alipay_url:如果开发者在小程序开发者平台开通了支付宝支付,但是在实际接入中不需要使用支付宝支付,则只需要将 alipay_url 参数值传为空字符串即可;如果没开通支付宝支付,但是实际接入中需要使用支付宝支付,则只需要给 alipay_url 参数传正确的值即可。
  • wx_url:如果开发者在小程序开发者平台开通了微信支付,但是在实际接入中不需要使用微信支付,则只需要将 wx_url 参数值传为空字符串即可;如果没开通微信支付,但是实际接入中需要使用微信支付,则只需要给 wx_urlwx_type 参数传正确的值即可。

payChannel 属性如下:

属性类型必填说明
default_pay_channelstring默认勾选的支付方式(支付宝或微信),可选 'wx', 'alipay'。仅在 service=1 且此前没有申请支付商户默认支付方式时生效

getOrderStatus

小程序收银台使用的是微信 H5 支付,微信支付完成后,小程序收银台无法收到微信支付结果回调;因此需要开发者实现一个查询订单支付状态的接口 getOrderStatus

该接口实现的功能是:开发者前端通过商户订单号(out_order_no),向开发者后端查询该订单的支付状态,将该支付状态返回给小程序收银台。

该接口需要返回 Promise 对象,实现方案参考 代码示例

  • 入参 {out_order_no: <商户订单号>},其中,out_order_no 为商户系统内部订单号,必传
  • 出参 {code},其中 code 是一个 Int 类型:

    • 0:支付成功
    • 1:支付超时
    • 2:支付失败
    • 3:支付关闭
    • 9:订单状态未知/未支付

请注意:只有商户后端查询到微信支付订单明确的终态(0,1,2,3)时才传这几个订单状态,收银台在接收到这几个状态后,会自动跳转到支付结果页;如果订单状态未明确(例如跳转微信未支付返回)则传 9,收银台接收到这个状态后会停留在收银台,用户可以继续发起确认支付操作。

success 返回参数说明

属性类型说明
codenumber0:支付成功 1:支付超时 2:支付失败 3:支付关闭 4:支付取消 9:订单状态开发者自行获取。只要调起收银台成功,支付状态都会回调success返回,开发者依据返回的 code 值,进行后续业务逻辑处理

fail 返回参数说明

object 类型,属性如下:

属性类型说明
errMsgstringAPI 支付错误码:10000- 支付失败,10001- 调起微信失败,10002- 微信未安装

扫码体验

请使用字节宿主APP扫码

代码示例

开发者工具中预览

tt.pay({
  orderInfo: {
    app_id: "800000040005",
    sign_type: "MD5",
    out_order_no: "MicroApp7075638135",
    merchant_id: "1300000004",
    timestamp: "1566720681",
    product_code: "pay",
    payment_type: "direct",
    total_amount: 1,
    trade_type: "H5",
    uid: "800000040005",
    version: "2.0",
    currency: "CNY",
    subject: "microapp test",
    body: "microapp test",
    trade_time: "1566720681",
    valid_time: "300",
    notify_url: "https://tp-pay.snssdk.com/paycallback",
    wx_url:
      "https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx25161122572189727ea14cfd1832451500&package=2746219290",
    wx_type: "MWEB",
    alipay_url:
      "alipay_sdk=alipay-sdk-java-3.4.27.ALL&app_id=2018061460417275&biz_content=%7B%22body%22%3A%22%E6%B5%8B%E8%AF%95%E8%AE%A2%E5%8D%95%22%2C%22extend_params%22%3A%7B%7D%2C%22out_trade_no%22%3A%2211908250000028453790%22%2C%22product_code%22%3A%22QUICK_MSECURITY_PAY%22%2C%22seller_id%22%3A%222088721387102560%22%2C%22subject%22%3A%22%E6%B5%8B%E8%AF%95%E8%AE%A2%E5%8D%95%22%2C%22timeout_express%22%3A%22599m%22%2C%22total_amount%22%3A%220.01%22%7D&charset=utf-8&format=json&method=alipay.trade.app.pay&notify_url=http%3A%2F%2Fapi-test-pcs.snssdk.com%2Fgateway%2Fpayment%2Fcallback%2Falipay%2Fnotify%2Fpay&sign=D2A6ua51os2aIzIH907ppK7Bd9Q2Kk5h7AtKPdudP%2Be%2BNTtAkp0Lfojtgl4BMOIQ3Z7cWyYMx6nk4qbntSx7aZnBhWAcImLbVVr1cmaYAedmrmJG%2B3f8G5TfAZu53ESzUgk02%2FhU1XV0iXRyE8TdEJ97ufmxwsUEc7K0EvwEFDIBCJg73meQtyCRFgCqYRWvmxetQgL7pwfKXpFXjAYsvFrRBas2YGYt689XpBS321g%2BZ8SZ0JOtLPWqhROzEs3dnAtWBW15y3NzRiSNi5rPzah4cWd4SgT0LZHmNf3eDQEHEcPmofoWfnA4ao75JmP95aLUxerMumzo9OwqhiYOUw%3D%3D&sign_type=RSA2&timestamp=2019-08-25+16%3A11%3A22&version=1.0",
    sign: "15aa99cd80878661a4d442b7540bdf96",
    risk_info: '{"ip":"127.0.0.1"}',
  },
  service: 1,
  payChannel: {
    default_pay_channel: "alipay", // wx || alipay
  },
  getOrderStatus(res) {
    let { out_order_no } = res;
    return new Promise(function (resolve, reject) {
      // 商户前端根据 out_order_no 请求商户后端查询微信支付订单状态
      tt.request({
        url: "<your-backend-url>",
        success(res) {
          // 商户后端查询的微信支付状态,通知收银台支付结果
          resolve({ code: 0 | 1 | 2 | 3 | 9 });
        },
        fail(err) {
          reject(err);
        },
      });
    });
  },
  success(res) {
    if (res.code == 0) {
      // 支付成功处理逻辑,只有res.code=0时,才表示支付成功
      // 但是最终状态要以商户后端结果为准
    }
  },
  fail(res) {
    // 调起收银台失败处理逻辑
  },
});
点击纠错
评价此篇文档