开发
API

接口定义

支付下单

服务端预下单

接口地址:

POST   https://developer.toutiao.com/api/apps/ecpay/v1/create_order

输入

字段名类型是否必传字段描述
app_idstring小程序 AppID
out_order_nostring开发者侧的订单号, 同一小程序下不可重复
total_amountnumber支付价格; 接口中参数支付金额单位为[分]
subjectstring商品描述; 长度限制 128 字节,不超过 42 个汉字
bodystring商品详情
valid_timenumber订单过期时间(秒); 最小 15 分钟,最大两天
signstring开发者对核心字段签名, 签名方式见文档附录, 防止传输过程中出现意外
cp_extrastring开发者自定义字段,回调原样回传
notify_urlstring商户自定义回调地址
thirdparty_idstring否,服务商模式接入必传第三方平台服务商 id,非服务商模式留空
disable_msgnumber是否屏蔽担保支付的推送消息,1-屏蔽 0-非屏蔽,接入 POI 必传
msg_pagestring担保支付消息跳转页
store_uidstring否,多门店模式下必传多门店模式下,门店 uid

输出

返回值为 JSON 形式,其中包括如下字段:

FieldTypeDescription
err_nonumber状态码 0-业务处理成功
err_tipsstring错误提示信息,常见错误处理可参考附录常见问题章节
dataorderInfo拉起收银台的 orderInfo

orderInfo 典型值如下(仅供参考):

{
  "order_id": "6819903302604491021",
  "order_token": "CgsIARCABRgBIAQoARJOCkx+WgXqCUIwTel2V3siEGZ0++poigIM+SMMxtMx798Vj0ZYzoTYBqeNslodUC9X5KAOHkR1YbSBz6I6pXATh5faIGy7R72A9vwm0OczGgA="
}

支付回调

回调信息包含如下字段:

字段名类型内容
timestampnumberUnix 时间戳,10 位,整型数
noncestring随机数
msgstring订单信息的 json 字符串
typestring回调类型标记,支付成功回调为"payment"
msg_signatureString签名

当订单成功支付之后,服务端会通过 post 方式回调开发者提供的 http 接口,使用 token 进行校验。回调信息包括 msg 信息为以下内容序列化得到的 json 字符串:

字段名类型内容
appidstring小程序 id
cp_ordernostring开发者传入订单号
waystringway 字段中标识了支付渠道:2-支付宝,1-微信
cp_extrastring预下单时开发者传入字段

以上信息转换为 json 字符串后,会作为 msg 字段回传。典型值如下:

{
  "timestamp": 1602507471,
  "nonce": 13323123,
  "msg": "{\"appid\":\"tt12345678910\",\"cporderno\":\"order-12345678910\",\"cpextra\":\"extrainfo\"}",
  "msg_signature": "20ebbed4c561cc290af7c6851b324e892d946e919b8f00fc163b76b59e7a929b",
  "type": "payment"
}

回调详细策略与响应要求参考 附录:回调响应

订单查询

接口地址:

POST   https://developer.toutiao.com/api/apps/ecpay/v1/query_order

输入:

字段名类型是否必传字段描述
app_idstring小程序 AppID
out_order_nostring开发者侧的订单号, 不可重复
signstring开发者对核心字段签名, 签名方式见文档, 防止传输过程中出现意外
thirdparty_idstring否,服务商模式接入必传第三方平台服务商 id,非服务商模式留空

输出:

返回值为 JSON 形式,其中包括 payment_info 字段:

way 字段中标识了支付渠道:2-支付宝,1-微信,3-银行卡

payment_info 返回值结构如下:
{
   "total_fee": 1200,
   "order_status": "PROCESSING-处理中|SUCCESS-成功|FAIL-失败|TIMEOUT-超时",
   "pay_time": "支付时间",
   "way": 1,
   "channel_no": "渠道单号",
   "channel_gateway_no": "渠道网关号"
}

退款

退款请求

当交易发生之后一段时间内,由于买家或者卖家的原因需要退款时,卖家可以通过退款接口将支付款退还给买家,将在收到退款请求并且验证成功之后,按照退款规则将支付款按原路退到买家帐号上。注意:

退款会与订单状态关联,目前不支持结算后的订单退款,需业务方自行处理。

避免连续频繁的发送同一订单的退款请求。

接口链接:

POST https://developer.toutiao.com/api/apps/ecpay/v1/create_refund

输入:

字段名类型是否必传字段描述
app_idstring小程序 id
out_order_nostring商户分配订单号,标识进行退款的订单
out_refund_nostring商户分配退款号
refund_amountnumber退款金额,单位[分]
reasonstring退款理由,长度上限 100
cp_extrastring开发者自定义字段,回调原样回传
notify_urlstring商户自定义回调地址
signstring开发者对核心字段签名, 签名方式见文档, 防止传输过程中出现意外
thirdparty_idstring否,服务商模式接入必传第三方平台服务商 id,非服务商模式留空
disable_msgnumber是否屏蔽担保支付消息,1-屏蔽
msg_pagestring担保支付消息跳转页
all_settlenumber是否为分账后退款,1-分账后退款;0-分账前退款。分账后退款会扣减可提现金额,请保证余额充足

输出:

FieldTypeDescription
err_nonumber状态码 0-业务处理成功
err_tipsstring错误提示信息
refund_nostring担保交易服务端退款单号

退款回调

当订单成功退款之后,服务端会通过 post 方式回调开发者提供的 http 接口,使用 token 进行校验。由于网络波动等原因,可能会产生重复的通知消息,接入方需要正确处理。

退款结构体与支付回调相同,type 枚举值为 refund 标记该回调为 refund。msg 中的 json 字符串信息包括:

  • app_id: 小程序 appid
  • cp_refundno:开发者自定义的退款单号
  • cp_extra:开发者传的额外参数
  • status:退款状态 PROCESSING-处理中|SUCCESS-成功|FAIL-失败
  • refund_amount: 退款金额

回调详细策略与响应要求参考 附录:回调响应

查询退款

接口地址:

POST https://developer.toutiao.com/api/apps/ecpay/v1/query_refund

1.输入

字段名类型是否必传字段描述
app_idstring小程序 AppID
out_refund_nostring开发者侧的退款号
signstring开发者对核心字段签名, 签名方式见文档, 防止传输过程中出现意外
thirdparty_idstring否,服务商模式接入必传第三方平台服务商 id,非服务商模式留空

2.输出

返回值为 JSON 形式,整体返回值结构如下:

FieldTypeDescription
err_nonumber状态码 0-业务处理成功
err_tipsstring错误提示信息
refundInfoobject订单退款基本信息

其中 refund_info 包含如下的字段:

FieldTypeDescription
refund_nostring担保支付侧的退款单号
refund_amountnumber退款金额,单位[分]
refund_statusstring退款状态,成功-SUCCESS;失败-FAIL

结算与分账

分账与结算用于确认一笔在途资金,将其转化为可提现资金。分账与结算行为的区别仅在于是否包含卖家之外的分账方需要获得资金,在接口调用文档中,两者是等价的。但无论是否有分账方都需要主动的调用接口才能进行资金的提现

分账请求

结算功能用于在交易发生之后一段时间后,可以根据需求分配货款,将资金从冻结户转移至可提现账户。为了保证业务正确处理, 请按担保交易设置页面的分账周期处理分账. 订单在支付后 150 天后如果仍然未进行分账,则会自动分配全部货款给卖家。在结算环节中,小程序平台会参与对整笔交易的手续费进行扣除,详情可以参考附录手续费计算规则。手续费默认由卖家承担,对于一些特殊场景,允许由接入方指定的分账方承担手续费。目前担保支付只支持单次的分账,会自动将未指定的货款分配给卖家账户。

接口链接:

POST https://developer.toutiao.com/api/apps/ecpay/v1/settle<br><br>

输入:

字段名类型是否必传字段描述
thirdparty_idstring否,服务商模式接入必传第三方平台服务商 id ,非服务商模式留空
out_settle_nostring开发者侧的结算号, 不可重复
out_order_nostring商户分配订单号,标识进行结算的订单
settle_descstring结算描述
notify_urlstring商户自定义回调地址
settle_paramsstring其他分账方信息,分账分配参数 SettleParameter 数组序列化后生成的 json 格式字符串
cp_extrastring开发者自定义字段,回调原样回传
app_idstring小程序 AppID
signstring开发者对核心字段签名, 签名方式见文档, 防止传输过程中出现意外

分账分配参数 SettleParameter

{
  "merchant_uid": "分账方商户号",
  "amount": "分账金额"
}

输出:

名称数据类型描述
err_nostring错误码
err_tipsstring错误提示信息
settle_nostring平台生成分账单号

分账回调

当订单成功分账之后,服务端会通过 post 方式回调开发者提供的 http 接口,使用 token 进行校验。回调结构体与支付相同,回调类型枚举 type 值为 settle。msg 字段的 json 转义字符串包含如下内容:

  • appid:小程序 id
  • cp_settle_no 开发者自定义的分账单号
  • cp_extra 开发者传的额外参数
  • status 分账状态,PROCESSING-处理中|SUCCESS-成功|FAIL-失败

回调详细策略与响应要求参考 附录:回调响应

查询分账

接口地址:

POST https://developer.toutiao.com/api/apps/ecpay/v1/query_settle

1.输入

字段名类型是否必传字段描述
app_idstring小程序 AppID
out_settle_nostring开发者侧的分账号
signstring开发者对核心字段签名, 签名方式见文档, 防止传输过程中出现意外
thirdparty_idstring否,服务商模式接入必传第三方平台服务商 id,非服务商模式留空

2.输出

返回值为 JSON 形式,整体返回值结构如下:

名称数据类型描述
err_nostring错误码
err_tipsstring错误提示信息
settle_infosettle_info相关分账单信息

其中 settle_info 包含如下的字段:

名称数据类型描述
settle_nostring担保支付侧的退款单号
settle_amountnumber退款金额,单位[分]
settle_statusstring退款状态,成功-SUCCESS;失败-FAIL

第三方进件

服务商进件

在服务商完成担保支付开发者授权后,该接口通过获取进件页 url 来实现服务商的自行进件。使用 component_access_token 调用接口。

接口链接:

POST https://developer.toutiao.com/api/apps/ecpay/saas/add_merchant

1.输入

名称数据类型是否必传描述
component_access_tokenstring授权码兑换接口调用凭证
thirdparty_component_idstring小程序第三方平台应用 id
url_typenumber链接类型:1-进件页面 2-账户余额页

2.输出

名称数据类型描述
err_noint错误码,成功时为 0
err_tipsstring错误信息
urlstring请求页面链接
merchant_idstring小程序平台分配商户号,用于后续分账标识分账方

分账方进件

接口用于服务商为其他关联业务方提供进件及结算能力。使用前要求服务商首先完成自身账户进件,使用第三方平台提供的服务商支付 secret 对请求进行加签。secret 可以在在第三方平台的设置->开发设置中查看。

接口链接:

POST https://developer.toutiao.com/api/apps/ecpay/saas/add_sub_merchant

3.输入

名称数据类型是否必传描述
thirdparty_idstring小程序第三方平台应用 id
sub_merchant_idstring商户 id,用于接入方自行标识并管理进件方。由服务商自行分配管理
url_typenumber链接类型:1-进件页面 2-账户余额页
signstring` | 是 | 签名,参考附录签名算法

4.输出

名称数据类型描述
err_noint错误码,成功时为 0
err_tipsstring错误信息
urlstring请求页面链接
merchant_idstring小程序平台分配商户号,用于后续分账一段描述

注:这里的 sub_merchant_id 只是为了便于服务商区分管理,在分账时用于标识接受方的商户号为 response 中的 merchant_id 字段。

点击纠错
评价此篇文档