结算中心一期API文档

编制 日期 版本
姜鹏 2023.04.12 V1.0
2023.10.30 V2.0

1 文档范围

​ 电子发票开票能力(查看、修改、开票、冲红)、银联POS机二维码支付及退款能力、银联资金提现、转帐凭证截图上传及查看、支付流水查询、门店配置、POS机终端配置、费率配置、结算帐号配置、支付收银台、支付回调、统一认证鉴权等。

2 相关逻辑交互

2.1 POS机支付交互时序

2.2 对公转帐收银台加载时序交互

3 全局约定

3.1 返回码

返回码 说明
200 正确返回
401 没有权限
403 拒绝访问
4031034 请求速度过快。限流标识
4031021 access_token过期
4031023 Refresh_token过期

3.2 字典

3.2.1 订单业务类型

字段 业务说明
business_type community 社区业务
tiance 天策代客下单

3.2.2 POS交易类型

字段 业务说明
fund_type pay 支付
refund 退款

3.2.3 支付通道

字段 业务说明
pay_channel pos POS机支付
offline 对公转帐
pos_c2b 银联C扫B
wechat 微信
alipay 支付宝

3.2.4 提现状态

字段 业务说明
withdrawal_status 1 申请失败
2 提现中
3 提现成功
4 提现失败

3.2.5 金融交易类型

字段 业务说明
trans_type_no 01 消费
02 撤销
03 退款

3.2.6 银联POS机退货/款状态

POS机支付09 代表处理成功 。

字段 业务说明
return_status 10 待提交
00 待处理
01 处理中
02 处理失败
04 已撤销
09 处理成功
21 审核不通过
12 匹配失败
13 流水检查失败
14 重复提交
15 无此交易
16 超额退款
90 非ssl访问
91 用户或密码错误
92 无此权限
93 格式错误
94 提交非法商户编号
95 不能处理该交易日退货
96 商户未开通退货
98 会话错误
99 系统异常

3.2.6 银联POS机支付方式

字段 业务说明
pos_payway 01 现金
02 刷卡(银行卡)
03 预付卡
04 抵用券
05 支票
07 无卡支付
10 组合支付
88 POS通
94 银联二维码
96 账户余额
97 微信
98 支付宝
99 其他

3.2.7 支付状态

字段 业务说明
pay_status 1 未支付
2 支付成功
5 订单关闭

3.2.8 退款状态

字段 业务说明
refund_status 1 退款中
2 退款成功
3 退款失败

3.2.9 支付/退款类型

字段 业务说明
type/authen_type wechat 微信公众号
mini 微信小程序
alipay_life 支付宝生活号
alipay_app 支付宝APP
alipay_mini 支付宝小程序
alipay_web 支付宝H5
pos 银联POS。注意:这儿是支付/退款类型,非支付通道。
pos_c2b 银联C扫B

3.2.10 订单类型

字段 业务说明
sale_order_type goods_sale 销售订单
goods_return 退货订单

4 安全规范

业务访问中台的所有接口均需要使用remacToken/ bizToken 作为HTTP头部标识。详见:

https://confluence.mideazy.com/pages/viewpage.action?pageId=451739700

其中:remacToken 为统一登录后生成的 access_token ; bizToken为业务应用根据中台分配的client_id, client_secret 生成的Token。 详细见: https://confluence.mideazy.com/pages/viewpage.action?pageId=451739700

5 天选中台接口API

5.1 开票能力

5.1.1 开具电子发票

描述: 开具电子发票与红冲电子发票均使用该接口。

注: 一个业务单号仅可开具一次蓝字发票或红字发票。

URL: /tx/platform-biz/remac-poly-pay/invoice/make

方法: POST

HTTP头: bizToken

方法:POST

请求参数:

其中开票申请对象字段属性如下:(说明:仅发票平台的协议要求使用首写字母大写,请谅解)

字段 类型 是否必 传 说明
BusinessOrderType 业务方订单类型或平台标识 中台区分对接的业务方的平台标识,同一平台的BusinessOrderNo应该唯一。默认为 tiance
BusinessOrderNo 字符串 业务方开票流水号。
DocumentNo 字符串 开票单据ID,初次开票由平台生成,最大长度20位。发起开票请求后无论成功与否会返回此值给业务方。业务方传入此值时,进行查询操作。
InvType 字符串 业务方区分开票还是冲红。 1: 开蓝字发票; 2: 冲红(开红字发票)
InvSort 字符串 发票类型: InvSort=0 增值税专票 InvSort = 4 : 增值税普票
PriceWay 字符串 价格方式 0:不含税,1:含税;建议传不含税
CustName 字符串 购方名称
CustTaxNo 字符串 购方税号,专票必填
CustAddress 字符串 购方地址、电话
CustBankAccount 字符串 购方银行、账号
SellerTaxNo 字符串 销方税号,为空时取 paraJson 参数中 TaxCode
Remark 字符串 备注 航天信息盘备注长度限制230字节。百望盘或UKey专用发票的备注长度限制184字节,百望盘或UKey普通发票的备注长度限制138字节,百望盘或UKey普通电子发票的备注长度限制130字节。
Printer 字符串 开票人,用于校验是否一致
Review 字符串 复核人
Remittee 字符串 收款人
IsInventory 字符串 是否强制开清单,0:否 1:是
IsPrint 字符串 是否自动打印,0:否 1:是
ResBillNo 字符串 红字通知单号,专票开红字票必填
InvoiceCode 字符串 原发票代码,普票开红字票必填
InvoiceNo 字符串 原发票号码,普票开红字票必填
InvoiceDate 字符串 原开票日期,格式“yyyy-MM-dd”
Amount 数字 发票金额; 发票方规则:根据价格方式 PriceWay 确定是含税还是不含税,红字票为负数,为空时由明细金额汇总。
TaxRate 数字 发票税率,多税率为-1,为空时取明细税率
TaxAmount 数字 发票税额,红字票为负数,为空时由明细税额汇总
Telephone 字符串 购方手机号码
Email 字符串 购方邮箱
Specs JSONArray 商品明细集合
call_back_url 字符串 开票成功后按此地址异步回调。协议见:https://confluence.mideazy.com/pages/viewpage.action?pageId=491323439 。 当前开票采用异步回调,此字段必传。
extra JSON 实际请求开票方后的结果按此地址异步回调,extra 作为业务方透传JSON对象。

商品明细集合 Specs 中各对象属性字段如下:

字段 类型 是否必传 说明
TaxClassificationCode 字符串 商品税收分类编码
GoodsName 字符串 商品名称
Spec 字符串 规格型号
Unit 字符串 计量单位
Price 数字 单价,根据价格方式 PriceWay 确定是含税还是不含税
Quantity 数字 数量,红字票为负数
Amount 数字 金额,根据价格方式PriceWay确定是含税还是不含税,红字票为负数
TaxRate 数字 税率
TaxAmount 数字 税额,红字票为负数
DiscountLineCount 数字 是否折扣行,0:否 1:是,开折扣行只需要当前明细行设置该值为 1 以及设置折扣金额即可
DiscountAmount 数字 折扣金额,根据价格方式PriceWay确定是含税还是不含税,负数,不得大于金额,含折扣时必传
DiscountTaxAmount 数字 折扣税额,负数,不得大于金额;含折扣时必传
Isyhzc 字符串 是否显示优惠政策,,0:否 1:是
ZeroFlag 数字 空:非零税率, 0税率填对应数值(1:免税,2:不征收,3:普通零税率)。0税率明细必填
Yhzcmc 字符串 非零税率传优化政策类型,0税率要填对应值 免税,不征收,

请求示例:

{"InvSort": 0,"PriceWay":0, "BusinessOrderNo": "2023041815450093", "InvType": 1,
"CustName":"佛山市花梵花艺设计有限公司",
"CustTaxNo":"91440606MA56MHG50K","CustAddress":"","CustBankAccount":"",
"SellerTaxNo":"91440606MA4UK1HYXR","Remark":"","Printer":"陆美群","Review":"崔静静","Remittee":"崔静静",
"IsInventory":0,"IsPrint":0,"ResBillNo":"","InvoiceCode":"","InvoiceNo":"","InvoiceDate":"","Amount":"5","TaxRate":"0.06","TaxAmount":"0.30","Telephone":"13926003676","Email":"pengjiang_2020@126.com",
"Specs":[{"GoodsName":"支架",
"Spec":"","TaxClassificationCode":"304020199","Unit":"件",
"Price":2.5,"Quantity":2,"Amount":5,"TaxRate":0.06,
"TaxAmount": 0.30,"DiscountLineCount":0,
"DiscountAmount":0,"DiscountTaxAmount":0,"Isyhzc":0,"Yhzcmc":""}]
}

返回结果:

{
  "code": "200",
  "message": "success",
  "data": {
    "id": 7,
    "BusinessOrderNo": "2023041815450092",
    "DocumentNo": "202304191550191256554463587",
    "InvType": 1,
    "InvSort": 4,
    "PriceWay": "0",
    "CustName": "佛山市花梵花艺设计有限公司",
    "CustTaxNo": "91440606MA56MHG50K",
    "CustAddress": "",
    "CustBankAccount": "",
    "SellerTaxNo": "91440606MA4UK1HYXR",
    "Remark": "",
    "Printer": "陆美群",
    "Review": "崔静静",
    "Remittee": "崔静静",
    "IsInventory": "0",
    "IsPrint": "0",
    "ResBillNo": "",
    "InvoiceCode": "234420000000",
    "InvoiceNo": "51139471",
    "InvoiceDate": "2023-04-19 03:50:39",
    "Amount": 5,
    "TaxRate": 0.06,
    "Telephone": "13926003676",
    "Email": "pengjiang_2020@126.com",
    "UpdateTime": "2023-04-19 15:50:19",
    "Details": [
      {
        "TaxClassificationCode": "304020199",
        "GoodsName": "支架",
        "Spec": "",
        "Unit": "件",
        "Price": 2.5,
        "Quantity": 2,
        "Amount": 5,
        "TaxRate": 0.06,
        "TaxAmount": 0.3,
        "DiscountLineCount": 0,
        "DiscountAmount": 0,
        "DiscountTaxAmount": 0,
        "Isyhzc": "0",
        "Yhzcmc": ""
      }
    ],
    "Specs": "[{\"DiscountTaxAmount\":0,\"Amount\":5,\"Quantity\":2,\"Unit\":\"件\",\"GoodsName\":\"支架\",\"DiscountAmount\":0,\"TaxAmount\":0.30,\"Price\":2.5,\"DiscountLineCount\":0,\"TaxClassificationCode\":\"304020199\",\"TaxRate\":0.06,\"Spec\":\"\",\"Isyhzc\":0,\"Yhzcmc\":\"\"}]",
    "Status": "success",
    "SendEmail": "0",
    "SendMessage": "0",
    "PdfUrl": "http://cs.ruizhi.com/d/a1bd635730ba442284fb",
    "FailReason": ""
  }
}

关键返回属性说明

属性 类型 说明
Status String success: 成功。fail: 开票中或者开票失败。
SendEmail Int 发送邮箱状态 0:失败,1:成功
SendMessage Int 短信状态 0:失败,1:成功
PdfUrl String 开票成功后返回的URL。仅成功有值
FailReason String 开票失败原因
DocumentNo String 中台生成的唯一开票流水号。请业务方自行处理。

5.1.2 查询电子发票

描述: 业务方根据业务订单号来查询电子发票的详情及记录,含正常的开票及红冲开票。

URL: /tx/platform-biz/remac-poly-pay/invoice/query

方法: POST

HTTP头: bizToken

方法:POST

字段 类型 是否必 传 说明
BusinessOrderType 业务方订单类型或平台标识 中台区分对接的业务方的平台标识,同一平台的BusinessOrderNo应该唯一。默认为 tiance
BusinessOrderNo 字符串 业务方开票流水号/订单号
InvType 数字 发票类型: InvSort=0 增值税专票 InvSort = 4 : 增值税普票

请求示例:

{"BusinessOrderNo":"2023041815450092", "InvType": 1 }

返回示例:

{
  "code": "200",
  "message": "success",
  "data": {
    "id": 7,
    "BusinessOrderNo": "2023041815450092",
    "DocumentNo": "202304191550191256554463587",
    "InvType": 1,
    "InvSort": 4,
    "PriceWay": "0",
    "CustName": "佛山市花梵花艺设计有限公司",
    "CustTaxNo": "91440606MA56MHG50K",
    "CustAddress": "",
    "CustBankAccount": "",
    "SellerTaxNo": "91440606MA4UK1HYXR",
    "Remark": "",
    "Printer": "陆美群",
    "Review": "崔静静",
    "Remittee": "崔静静",
    "IsInventory": "0",
    "IsPrint": "0",
    "ResBillNo": "",
    "InvoiceCode": "234420000000",
    "InvoiceNo": "51139471",
    "InvoiceDate": "2023-04-19 03:50:39",
    "Amount": 5,
    "TaxRate": 0.06,
    "Telephone": "13926003676",
    "Email": "pengjiang_2020@126.com",
    "UpdateTime": "2023-04-19 15:50:19",
    "Details": [
      {
        "TaxClassificationCode": "304020199",
        "GoodsName": "支架",
        "Spec": "",
        "Unit": "件",
        "Price": 2.5,
        "Quantity": 2,
        "Amount": 5,
        "TaxRate": 0.06,
        "TaxAmount": 0.3,
        "DiscountLineCount": 0,
        "DiscountAmount": 0,
        "DiscountTaxAmount": 0,
        "Isyhzc": "0",
        "Yhzcmc": ""
      }
    ],
    "Specs": "[{\"DiscountTaxAmount\":0,\"Amount\":5,\"Quantity\":2,\"Unit\":\"件\",\"GoodsName\":\"支架\",\"DiscountAmount\":0,\"TaxAmount\":0.30,\"Price\":2.5,\"DiscountLineCount\":0,\"TaxClassificationCode\":\"304020199\",\"TaxRate\":0.06,\"Spec\":\"\",\"Isyhzc\":0,\"Yhzcmc\":\"\"}]",
    "Status": "success",
    "SendEmail": "0",
    "SendMessage": "0",
    "PdfUrl": "http://cs.ruizhi.com/d/a1bd635730ba442284fb",
    "FailReason": ""
  }
}

5.1.3 将电子发票发送到用户手机

描述: 将发票PDF发送到用户的手机。 仅提供蓝字头发票的PDF短信发送。

URL: /tx/platform-biz/remac-poly-pay/invoice/send

方法: POST

HTTP头: bizToken

方法:POST

字段 类型 是否必 传 说明
BusinessOrderType 业务方订单类型或平台标识 中台区分对接的业务方的平台标识,同一平台的BusinessOrderNo应该唯一。默认为 tiance
BusinessOrderNo 字符串 业务方开票流水号/订单号
InvType 数字 发票类型: InvSort=0 增值税专票 InvSort = 4 : 增值税普票
Telephone 字符串 不传此参数将默认向原发票记录对应的用户用机号发送发票信息。
Amount 字符串, 小数点后两位。 发票金额,若开票时未提供,则调用此接口必须提供。如果开票时提供,取开票时的发票金额(不含税),即用户实付的金额。

5.2 支付相关

5.2.1 请求收银台

描述:业务方向中台请求收银台,中台存储预下单信息并返回当前的业务系统支持的支付方式。

当前V0.1版本由天策后端调用中台收银台。

URL: /tx/platform-biz/remac-pay-mid/readyorder/save

方法: POST

HTTP头: remacToken

注: 这个接口使用的是H5 传的remacToken 。

方法:POST

字段 类型 是否必 传 说明
business_id 字符串 业务ID,由中台分配。生产和测试环境不一样,不同的业务类型也不一样,请业务端不要写死 。
business_type 字符串 http://arch.smartmideazy.com/docs/tx/pay.html《3.2.1 订单业务类型》
business_order_no 字符串 业务订单号
business_name 字符串 商户名称
goods_name 字符串 商品名称; 32个长度。商品名称不可含有“#”符号。
goods_content 字符串 商品详情
goods_count 数字 商品数量
unit_price 数字 商品单价
total_fee 数字 订单总价
call_back_url 字符串 业务方的回调地址, 在支付/退款完成后,中台回调业务方的服务器接口URL,POST方法。业务方根据回调的协议做好支付/退款的兼容逻辑。注: 中台统一回调的协议规范参见:《https://confluence.mideazy.com/pages/viewpage.action?pageId=491323439》注意:业务系统接收推送通知的URL必须可以外网访问,须加白名单,中台可以访问。
extra JSON字符串 业务方的服务器接口call_back_urlr所对应的额外的HTTP body 。 JSON格式。中台在向业务推送时会在BODY中透传这个extra字段属性。
{
"business_id": "1101", "business_type": "tiance", "business_order_no": "1234567890","goods_content":"test", "goods_name": "test",  "goods_count": 1,  

"unit_price": 1.2 , "total_fee": 1.2,  
"call_back_url": "https://ruizhu.com/api/callback", "extra" : "{\"type\": \"save\"} " }

返回示例:

{
  "code": "200",
  "data": {
    "out_trade_no": "20230508180845JL6503JBOM",
    "pay_channel_list": [
      {
        "pay_channel_ch": "POS机支付",
        "enable": true,
        "pay_channel": "pos"
      },
      {
        "pay_channel_ch": "对公转帐",
        "enable": true,
        "pay_channel": "offline"
      },
      {
                    "pay_channel_ch": "银联C扫B",
                    "enable": true,
                    "pay_channel": "pos_c2b"
       },
      {
        "pay_channel_ch": "微信",
        "enable": false,
        "pay_channel": "wechat"
      },
      {
        "pay_channel_ch": "支付宝",
        "enable": false,
        "pay_channel": "alipay"
      }
    ]
  },
  "message": "success"
字段 类型 是否必 返回 说明
out_trade_no 字符串 中台订单编号。全局唯一。
pay_channel_list JSONArray 当前业务系统所支持的支付方式。仅当 enable=true代表支持的支付方式。

5.2.1A 中台H5请求收银台

描述:中台H5 向中台请求收银台,中台存储预下单信息并返回当前的业务系统支持的支付方式。

注:此接口仅为中台H5提供。

URL: /tx/platform-biz/remac-pay-mid/readyorder/get

方法: POST

HTTP头: remacToken

方法:POST

字段 类型 是否必 传 说明
business_type 字符串 http://arch.smartmideazy.com/docs/tx/pay.html《3.2.1 订单业务类型》
business_order_no 字符串 业务订单号
{
 "business_type": "tiance", "business_order_no": "1234567890","goods_content":"test" }

返回示例:

{
  "code": "200",
  "data": {
    "out_trade_no": "20230508180845JL6503JBOM",
    "pay_channel_list": [
      {
        "pay_channel_ch": "POS机支付",
        "enable": true,
        "pay_channel": "pos"
      },
      {
        "pay_channel_ch": "对公转帐",
        "enable": true,
        "pay_channel": "offline"
      },
      {
        "pay_channel_ch": "微信",
        "enable": false,
        "pay_channel": "wechat"
      },
      {
        "pay_channel_ch": "支付宝",
        "enable": false,
        "pay_channel": "alipay"
      },
      {
        "pay_channel_ch": "银联C扫B",
        "enable": true,
        "pay_channel": "pos_c2b"
      }
    ]
  },
  "message": "success"

5.2.2 请求收银台二维码或跳转链接

描述:业务方向中台请求生成二维码还是直接跳转页面。

入参新增: pos_c2b_return_url、expire_time 两个字段 。

URL: /tx/platform-biz/remac-pay-mid/readyorder/jump

方法: POST

HTTP头: remacToken

注: 这个接口使用的是H5 传的remacToken 。

方法:POST

字段 类型 是否必 传 说明
out_trade_no 字符串 业务中台的订单号。
pay_channel 字符串 支付通道;见全局字典《3.2.3 支付通道 》
barcode_gen 整型 是否生成二维码。1: 生成二维码, 由用户手机主扫,适用于PC端; 2: 在移动端直接跳转页面
pos_c2b_return_url 字符串 业务端C扫B完成支付后,期待跳转的url,当 pay_channel = pos_c2b为必填.
expire_time 字符串 当pay_channel=pos_c2b时,必填。一次性二维码的默认过期时间为30分钟,最长时间为90天,超过90天按90天处理)格式yyyy-MM-dd HH:mm:ss
redirect_url 字符串 业务端扫二维码后跳转的页面地址。除pay_channel=pos和pos_c2b外,其他支付通道均需传此参数。中台返回中台订单号并将订单号和临时鉴权access_token拼接到业务方的 barcode_url参数后面。 https://ploypay-sit.remacsmart.com?out_trade_no=202302280910120556&remacToken=XXX&expire_in=7200
amount 数字 订单金额,保留两位小数,当pay_channel=pos 和pay_channel=pos_c2b 必传。单位:元。保留两位小数。
fund_type 字符串 交易类型。见:《3.2.2 POS交易类型》, 当pay_channel=pos 必传。
goods_name 字符串 商品名称。见:《3.2.2 POS交易类型》, 当pay_channel=pos和 pos_c2b 必传。商品名称不可含有“#”符号。
{
    "out_trade_no": "20230508180845JL6503JBOM", "redirect_url": "https://ploypay-sit.remacsmart.com/index.html", "pay_channel": "pos", "goods_name":"test","barcode_gen": 1, "fund_type": "pay"
 }

返回示例:

(1)当 pay_channel = pos, 仅返回一个二维码的图片链接地址。供POS机扫码,故无跳转URL。

请求示例:

{
    "out_trade_no": "20230508180845JL6503JBOM", "redirect_url": "https://ploypay-sit.remacsmart.com/index.html", "pay_channel": "pos","barcode_gen": 1, "goods_name": "XXX", "fund_type": "pay", "amount": 1.2
 }

返回示例:

{
  "code": "200",
  "data": {
    "barcode_url": "https://remac-tx.oss-cn-hangzhou.aliyuncs.com/tmp/2023-05-10/pay23d97ea77f2a49eab3ab85ce93b068d8.png?Expires=1683700879&OSSAccessKeyId=LTAItmXhp8umFYah&Signature=unWsiZTtiiwB%2BIY47IH51qI4Bjk%3D",
    "out_trade_no": "20230508180845JL6503JBOM"
  },
  "message": "success"
}

(2)当 pay_channel = offline(对公转帐) 返回一个带跳转链接的图片二维码地址,用户手机扫码时,跳转二维码中的链接。 其中返回的二维码的URL链接规则:

redirect_url?out_trade_no=$out_trade_no&remacToken=$remacToken&expires_in=7200

其中: out_trade_no为中台订单号;remacToken为中台重新生成的鉴权token。 当用户扫二维码时,页面跳转至 barcode_url?out_trade_no=$out_trade_no&remacToken=$remacToken, 开发人员在页面 barcode_url中获取out_trade_no和remacToken,remacToken值携带在HTTP头部用于网关鉴权,使用out_trade_no订单号去请求中台加载收银台详情接口。expires_in为remacToken过期时间。 redirect_url由业务方传的跳转H5链接地址。

{
  "code": "200",
  "data": {
    "barcode_url": "https://remac-tx.oss-cn-hangzhou.aliyuncs.com/tmp33eae68d47c848f8ba14bac1b08ad196.png?Expires=1683541334&OSSAccessKeyId=LTAItmXhp8umFYah&Signature=F9MYiofsDsRK4LT8fyqfCV8EyBk%3D",
    "out_trade_no": "20230508180845JL6503JBOM"
  },
  "message": "success"
}
字段 类型 是否必 返回 说明
out_trade_no 字符串 中台订单编号。全局唯一。
barcode_url 字符串 barcode_gen = 1时有返回
jump_url 字符串 barcode_gen = 2 时有返回。

(3) pay_channel = pos_c2b (银联C扫B)

返回结果如下:

{ "code": "200", "data": { "barcode_url": "银联二维码地址", "out_trade_no": "20230508180845JL6503JBOM" }, "message": "success" }

注意:

返回字段说明:

字段 是否必返回 说明 备注
barcode_url 银联C扫B二维码 仅下单成功才有返回

5.2.3 收银台数据加载

描述:业务方向中台请求数据加载,主要是展现订单的基本信息和对公帐号信息。

URL: /tx/platform-biz/remac-pay-mid/readyorder/load?out_trade_no=中台订单号

HTTP头: remacToken / bizToken

方法:GET

参数:out_trade_no: 中台订单号

返回结果示例:

{
  "code": "200",
  "data": {
    "id": 200043,
    "business_id": "1101",
    "business_name": null,
    "goods_name": "test",
    "goods_content": "test",
    "goods_count": 1,
    "unit_price": 1.2,
    "total_fee": 1.2,
    "business_order_no": "123456789",
    "business_type": "tiance",
    "create_time": 1683167509000,
    "original": null,
    "account_name": "广东睿住智能科技有限公司",
    "account_number": "44050166733600002087",
    "account_bank": "中国建设银行股份有限公司顺德北滘支行",
    "req_type": "barcode",
    "call_back_url": "https://ruizhu.com/api/callback",
    "extra": "{\"type\": \"save\"}",
    "out_trade_no": "202305041011468PEN4GYCQ8",
    "barcode_bucket_url": "https://remac-tx.oss-cn-hangzhou.aliyuncs.com/tmp9634d3325a6741efbc20d42374f1c07c.png",
    "barcode_url": null,
    "h5_url": null,
    "mini_page_path": null,
    "token": null

  },
  "message": "success"
}

5.2.4 打款凭证上传

描述: 一个中台订单号可以上传多个打款凭证。

通过数组形式批量上传对公转账凭证

HTTP协议:

HTTP,HTTPS

URL:

/tx/platform-biz/remac-pay-mid/fundprof/submit

HTTP头:

bizToken/remacToken

方法:

POST

路径参数:

名称 类型 必填 描述
outTradeNo String 中台订单编号
payResultUrl String 凭证图片url

注:以数组形式传递参数,如:

[
   {
      "outTradeNo":"1",
      "payResultUrl":"https://www.baidu.com"
   },
   {
      "outTradeNo":"1",
      "payResultUrl":"https://www.goole.com"
   }
]

返回:

{
"code": "200",
"message": "请求成功",
"data": [
    {
        "id": 21,
        "outTradeNo": "1",
        "payResultUrl": "https://www.baidu.com",
        "createTime": "2023-05-11 08:43:30"
    },
    {
        "id": 22,
        "outTradeNo": "1",
        "payResultUrl": "https://www.goole.com",
        "createTime": "2023-05-11 08:43:30"
    }
]
}

5.2.5 打款凭证查询

描述:

分页查询对公转账凭证

HTTP协议:

HTTP,HTTPS

URL:

/tx/platform-biz/remac-pay-mid/fundprof/list

HTTP头:

bizToken/remacToken

方法:

POST

路径参数:

名称 类型 必填 描述
outTradeNo string 中单订单编号
endTime String yyyy-MM-dd
pageNo Integer 当前页(从0开始)
pageSize Integer 每页数量

返回:

{
"code": "200",
"message": "请求成功",
"data": {
    "content": [
        {
            "id": 19,
            "outTradeNo": "1",
            "payResultUrl": "https://www.baidu.com",
            "createTime": "2023-05-11 08:25:53"
        },
        {
            "id": 20,
            "outTradeNo": "1",
            "payResultUrl": "https://www.goole.com",
            "createTime": "2023-05-11 08:25:53"
        }
    ],
    "pageable": {
        "sort": {
            "sorted": false,
            "unsorted": true,
            "empty": true
        },
        "offset": 0,
        "pageSize": 10,
        "pageNumber": 0,
        "paged": true,
        "unpaged": false
    },
    "last": true,
    "totalPages": 1,
    "totalElements": 2,
    "sort": {
        "sorted": false,
        "unsorted": true,
        "empty": true
    },
    "size": 10,
    "number": 0,
    "first": true,
    "numberOfElements": 2,
    "empty": false
}
}

5.2.5A 打款凭证详情

描述:一个中台订单号对应多个上传凭证。

分页查询对公转账凭证

HTTP协议:

HTTP,HTTPS

URL:

/tx/platform-biz/remac-pay-mid/fundprof/detail?out_trade_no=XX

HTTP头:

bizToken/remacToken

方法:

Get

参数:

out_trade_no: 中台订单编号

返回结果:

{
  "code": "200",
  "message": "请求成功",
  "data": [
    {
      "id": 23,
      "outTradeNo": "20230530152419NBB47WG6CR",
      "payResultUrl": "https://remac-tx.oss-cn-hangzhou.aliyuncs.com/%E9%BB%98%E8%AE%A4/20230530152507424317883.png",
      "createTime": "2023-05-30 07:25:08"
    }
  ]
}

5.2.6 银联 POS机相关接口

5.2.6.1 生成付款/退款二维码

注: 生成的二维码为存储桶链接,48小时后过期。

描述: 支付和退款二维码均使用此接口。依据 fund_type决定是支付还是退款二维码。

URL: /tx/platform-biz/remac-pay-mid/pos/genPosBarcode

方法: PUT

HTTP头: remacToken / bizToken

请求参数(body)

名称 类型 必填 描述
out_trade_no string 中台订单编号
amount BigDecimal 实际金额,单位:元
fund_type String 见《3.2.2 POS交易类型》

生成付款二维码请求示例:

{
    "out_trade_no": "20230508180845JL6503JBOM",   "amount": "1.20",  "fund_type": "pay"
 }

返回示例:

{
  "code": "200",
  "data": "https://remac-tx.oss-cn-hangzhou.aliyuncs.com/tmp/2023-05-16/pay44072df826c447e2b36b544608ff882e.png?Expires=1684219878&OSSAccessKeyId=LTAItmXhp8umFYah&Signature=A6Wn1hXq4AtIx1%2FJOTWTenwaDEQ%3D",
  "message": "success"
}

生成付款二维码请求示例:

{
    "out_trade_no": "20230508180845JL6503JBOM",   "amount": "1.20",  "fund_type": "refund"
 }

5.2.6.2 银联POS机支付结果查询

描述: POS发起支付后,业务方查询订单支付状态。 由于银联方用时间字段作了分库分表,故除中台订单号外,还需要传入起始时间范围。 依据中台订单号实时查询一笔订单支付状态。

如果订单是 C扫B, 不需要传入start_time和end_time。

URL: /tx/platform-biz/remac-pay-mid/pos/order/query

方法: PUT

HTTP头: remacToken / bizToken

请求参数(body)

名称 类型 必填 描述
out_trade_no string 中台订单编号
pay_channel String 支付通道;见全局字典《3.2.3 支付通道 》。默认pay_channel=pos
start_time String yyyyMMdd,除 pay_channel = pos_c2b 外,其他必传。
end_time String yyyyMMdd, 除 pay_channel = pos_c2b 外,其他必传。

返回:

{
  "code": "200",
  "data": {
    "id": 200071,
    "out_trade_no": "20230517170108H2JADCVHWY",
    "submit_time": "2023-05-17 17:01:08",
    "update_time": null,
    "nick_name": null,
    "real_name": null,
    "mobile": null,
    "openid": null,
    "type": null,
    "transaction_id": null,
    "shop_id": 200030,
    "much_root_id": 200025,
    "total_fee": 0.01,
    "currency_unit": "yuan",
    "actual_total_fee": 0.01,
    "order_type": null,
    "plate": null,
    "item_price": "0.01",
    "quantity": "1",
    "status": 1,
    "business_order_id": null,
    "pay_callbak_url": "https://ruizhu.com/api/callback",
    "extra": "{\"type\": \"save\"} ",
    "recordId": null,
    "business_order_no": "1234567893",
    "business_order_type": "tiance",
    "goods_name": "test",
    "trans_date": "20230517",
    "pos_employno": "01",
    "pos_shopid": "898773209106664",
    "pos_termid": "68091034",
    "pos_latitude": "",
    "pos_longitude": "",
    "pos_cardtype": "",
    "pos_signer": null,
    "pos_banktrace": "190031580325",
    "pos_cardid": "",
    "pos_trace": "408178",
    "pos_signflag": "0",
    "pos_payway": "01",
    "pos_tracetime": "20230517170452"
  },
  "message": "success"
}

返回字段说明:

字段 类型 是否必 返回 说明
id long Y
submit_time string Y 提交时间
update_time string Y 更新时间
status int Y 见全局字典《3.2.7 支付状态》
nick_name string 买家昵称
real_name string 买家姓名
mobile string 买家手机号
openid string C端买家标识
type string Y 支付类型: 见全局字典《3.2.9 支付/退款类型》
shop_id long 门店ID
much_root_id long 服务主体ID
order_type string Y
plate string
item_price string 商品单价
total_fee decimal Y 商品总价
currency_unit string Y 人民币单位, fen/yuan
actual_total_fee decimal 实付金额
quantity string 商品数量
transaction_id string 交易ID
out_trade_no string 交易号
business_order_id string 业务订单号
pay_callbak_url string 业务方支付成功回调URL
extra string 业务方透传参数JSON
business_order_no string 业务订单号
business_order_type string 业务订单类型
以下是银联POS机支付结果返回
pos_employno string 员工号
pos_shopid string 商户号
pos_termid string 终端号
pos_latitude string
pos_longitude string
pos_cardtype string 卡类型
pos_signer string 实际的签收人姓名
pos_banktrace string 参考号
pos_signflag string 0:本人签收1:他人签收
pos_cardid string 银行卡号
pos_trace string pos流水号
goods_name string 商品名称
trans_date string 原交易日期, 格式yyyyMMdd
pos_payway string 银联支付方式。见全局字典《3.2.6 银联POS机支付方式》
pos_tracetime string 银行交易时间

5.2.6.3 银联POS机退款结果查询

描述: POS发起支付后,业务方查询订单退款状态。 由于银联方用时间字段作了分库分表,故除中台订单号外,还需要传入起始时间范围。

由于一个中台订单编号(中台支付流水号)对应多笔退款,以满足一笔订单发起多次退款场景。

out_refund_no为中台退款流水号,是唯一的。

URL: /tx/platform-biz/remac-pay-mid/pos/refund/query

方法: PUT

HTTP头: remacToken / bizToken

请求参数(body)

名称 类型 必填 描述
out_trade_no string 中台订单编号
start_time String yyyyMMdd
end_time String yyyyMMdd

退款记录对象属性如下:

字段 类型 是否必 返回 说明
id long Y
out_trade_no string Y 中台订单号
transaction_id string 微信或支付宝的交易ID
operate_time string
total_fee string Y 原订单金额
send_back_fee string 实际退款金额
refund_amount string Y 申请退款金额
openid string 微信或支付宝用户的ID
authen_type string 退款类型: 见全局字典《3.2.9 支付/退款类型》
currency_unit string Y 人民币单位, fen/yuan
trans_date string 交易日期
pos_mer_id string 商户号
pos_bank_trace string 交易检索参考号
pos_refund_cardno string 退货交易卡号后4位
pos_refund_bankname string 银行卡名称
pos_refund_trace string 退货流水号
status int Y 字典详见 3.2.8 退款状态
business_order_type string 业务订单类型
business_order_no string 业务订单号
out_refund_no string Y 中台退款号, 退货交易唯一标识。由于支持部分退货交易,所以商户要防止重复退货
refund_time string 退款时间
pos_shopid string 商户号
pos_refund_status string 字典详见 3.2.6 银联pos退货/款状态
refund_status_msg string 退款状态说明

5.2.6.4 业务方主动发起退款请求

描述: 由业务方主动向中台发起退款请求。由于银联方有对帐数据后才可发起退款。由中台来判断此笔订单是否存在对帐数据。

退款接口是异步的,请求成功不代表退款成功。

https://confluence.mideazy.com/pages/viewpage.action?pageId=491323439#id-%E4%B8%AD%E5%8F%B0%E7%BB%9F%E4%B8%80%E6%8E%A8%E9%80%81%E5%8D%8F%E8%AE%AE%E8%A7%84%E8%8C%83-4.2%E8%AE%A2%E5%8D%95%E9%80%80%E6%AC%BE%E6%88%90%E5%8A%9F%E7%9A%84%E6%8E%A8%E9%80%81%E5%8D%8F%E8%AE%AE

out_refund_no为中台退款流水号,是唯一的。

URL: /tx/platform-biz/remac-pay-mid/pos/api/refund

方法: PUT

HTTP头: remacToken / bizToken

请求参数(body)

名称 类型 必填 描述
out_trade_no string 中台订单编号
out_refund_no String 中台退款流水编号。业务方如果需要重复请求,需要传这个参数 ,若不传此参数,中台将按新的退款请求,一条中台订单编号可以对应多条退款流水。
refund_amount string 退货金额(单位:元)
pay_channel String 默认 pay_channel=pos 。pay_channel=pos_c2b C扫B退款请求必传。
refund_desc String 退款描述。不填写默认为“用户取消订单”

返回字段说明:

名称 类型 是否必 返回 描述
out_trade_no string Y 中台订单编号。
out_refund_no string N 中台退款号, 退货交易唯一标识。仅退款请求成功才返回此字段。

注: 仅pay_channel=pos 返回码为 403000 代表银联方提示重复退款或其他错误, 中台会返回此订单所对应的退款集合。

返回示例:

{
  "code": "403000",
  "message":"超额退款,请确认是否已提交过退货申请!",
  "data": [

     {refund对象列表}, .... 
  ]
}

注意 :退款操作成功返回 , 不是退款成功发了。 退款是异步,建议业务系统间隔一几秒或者等待业务中台的异步通知结果来更新退款状态。操作成功返回当前的这一笔退款记录,为保持返回格式一致,也以集合的结果提供:

{
    "code": "200",
    "message": "success",
     data: [

        {out_refund_no: XX,out_trade_no:XX, status: 1 }
     ]

 }

5.2.6.5 业务方查询订单退款状态

描述: 由业务方向中台查询订单退款状态

out_refund_no为中台退款流水号,是唯一的。

同时支持POS和C扫B退款查询

URL: /tx/platform-biz/remac-pay-mid/pos/api/refund/query

方法: PUT

HTTP头: remacToken / bizToken

请求参数(body)

名称 类型 必填 描述
out_refund_no string 中台退款号
pay_channel string 支付通道。默认 pay_channel=pos 。pay_channel=pos_c2b C扫B退款请求必传。

返回

{"code":"200", "message":"success", "data":{退款记录对象JSON}}

退款记录对象返回字段说明:

字段 类型 是否必 返回 说明
id long Y
out_trade_no string Y 中台订单号
transaction_id string 微信或支付宝的交易ID
operate_time string
total_fee string Y 原订单金额
send_back_fee string 实际退款金额
refund_amount string Y 申请退款金额
openid string 微信或支付宝用户的ID
authen_type string
currency_unit string Y 人民币单位, fen/yuan
trans_date string 交易日期
pos_mer_id string 商户号
pos_bank_trace string 交易检索参考号
pos_refund_cardno string 退货交易卡号后4位
pos_refund_bankname string 银行卡名称
pos_refund_trace string 退货流水号
status int Y 字典详见 3.2.8 退款状态
business_order_type string 业务订单类型
business_order_no string 业务订单号
out_refund_no string Y 中台退款号, 退货交易唯一标识
refund_time string 退款时间
pos_shopid string 商户号
pos_refund_status string 字典详见 3.2.6 银联pos退货/款状态
refund_status_msg string 退款状态说明

5.3 财务相关

5.3.1 订单、退款、对帐查询接口

描述: 业务方提供中台支付流水号集合,中台一并将订单、退款、对帐记录返回。

支付流水号集合最大尺寸为100, 所有的记录均按交易时间排倒序。

URL: /tx/platform-biz/remac-pay-mid/financial/records

方法:POST

HTTP头: remacToken / bizToken

请求参数(body)

名称 类型 必填 描述
out_trade_nos List 中台交易流水号集合

返回

{"code":"200", "message":"success", "data":{"orders":[{支付流水记录},..], "refunds":[{退款流水记录},..], "checkBills":[对帐流水记录},..]}}

退款记录对象返回字段说明:

orders: 订单记录集合。订单记录请参见《6.2.1 支付结果通知》

refunds: 退款对象集合。退款记录请参见《6.2.2 退款结果通知》

checkBills: 对帐记录集合。 对帐记录请参见《6.2.3 对帐结果通知》

5.3.2 提现接口

描述: 按中台支付流水号进行提现。

URL: /tx/platform-biz/remac-pay-mid/cashWithdrawal/allocate

方法: PUT

HTTP头: remacToken / bizToken

请求参数(body)

名称 类型 必填 描述
out_trade_no String 中台交易流水号
withdrawal_money 实现请求提现的金额。单位:元。如果此值不为空,提现请求将以此值来发起,否则将按中台交易流水号对应的付款金额来执行提现。

成功返回:

{
  "code": "200",
  "data": {
    "id": 236098,
    "out_trade_no": "24125AAAAAAAAAAAAAAA",
    "merid": "89844115712AALB",
    "clear_date": "20231219",
    "trans_code": "202001",
    "amount": "1000000",
    "pay_amount": "997500",
    "out_withdrawal_no": "14201DIJDADFYGCFAIFU",
    "req_date": "20231228",
    "req_time": "104602",
    "status": 3,
    "fail_reason": null,
    "currency_unit": "fen",
    "card_no": null,
    "fzps": null,
    "sign": null
  },
  "message": "success"
}

status: 提现状态。3 :表示请求提现成功。其他表示异常,业务侧可以重复发起提现。

out_withdrawal_no: 业务中台提现流水号

5.3.3 提现状态查询

描述: 按中台支付流水号进行提现状态查询。

URL: /tx/platform-biz/remac-pay-mid/cashWithdrawal/allocate/status/query

方法: POST

HTTP头: remacToken / bizToken

请求参数(body)

名称 类型 必填 描述
out_trade_no String 中台交易流水号

成功返回:

{
  "code": "200",
  "data": {
    "id": 236098,
    "out_trade_no": "24125AAAAAAAAAAAAAAA",
    "merid": "89844115712AALB",
    "clear_date": "20231219",
    "trans_code": "202001",
    "amount": "1000000",
    "pay_amount": "997500",
    "out_withdrawal_no": "14201DIJDADFYGCFAIFU",
    "req_date": "20231228",
    "req_time": "104602",
    "status": 3,
    "fail_reason": null,
    "currency_unit": "fen",
    "card_no": null,
    "fzps": null,
    "sign": null
  },
  "message": "success"
}

status: 提现状态。3 :表示请求提现成功。其他表示异常,业务侧可以重复发起提现。

out_withdrawal_no: 业务中台提现流水号

注: 仅将业务方向中台发起过提现请求才有 data 对象返回。


6 中台统一推送

6.1 统一推送签名规则

https://confluence.mideazy.com/pages/viewpage.action?pageId=491323439

6.2 推送协议

6.2.1 支付结果通知

注: 仅支付成功才向业务推送订单支付结果。

协议: HTTP/HTTPS

URL: 业务方的支付回调URL,即《5.2.1 请求收银台 》协议中的 callback_url 字段,extra 是业务方透传JSON字段。

方法: POST

请求体Body

Body 属性字段

字段 类型 说明
type string 通知类型: pay:支付通知 refud: 退款通知
data JsonString 支付记录或退款记录数据
timestamp Long 当前时间戳
noncestr String 随机串 (32位)
mac String 中台依据推送的HTTP Body 生成签名串 《6.1 统一推送签名规则》

当 type = pay 时, data为支付记录JSON,各字段说明如下:

字段 类型 是否必 返回 说明
pay_channel String Y 支付通道;见全局字典《3.2.3 支付通道 》。 业务方根据此字段来区别pos和C扫B及其他场景。
id long Y
submit_time string Y 提交时间
update_time string Y 更新时间
status int Y 见全局字典《3.2.7 支付状态》
nick_name string 买家昵称
real_name string 买家姓名
mobile string 买家手机号
openid string C端买家标识
type string Y 支付类型: 见全局字典《3.2.9 支付/退款类型》
shop_id long 门店ID
much_root_id long 服务主体ID
order_type string Y
plate string
item_price string 商品单价
total_fee decimal Y 商品总价
currency_unit string Y 人民币单位, fen/yuan
actual_total_fee decimal 实付金额
quantity string 商品数量
transaction_id string 交易ID
out_trade_no string 交易号
business_order_id string 业务订单号
pay_callbak_url string 业务方支付成功回调URL
extra string 业务方透传参数JSON
business_order_no string 业务订单号
business_order_type string 业务订单类型
以下是银联POS机支付结果返回
pos_employno string 员工号
pos_shopid string 商户号
pos_termid string 终端号
pos_latitude string
pos_longitude string
pos_cardtype string 卡类型
pos_signer string 实际的签收人姓名
pos_banktrace string 参考号
pos_signflag string 0:本人签收1:他人签收
pos_cardid string 银行卡号
pos_trace string pos流水号
goods_name string 商品名称
trans_date string 原交易日期, 格式yyyyMMdd
pos_payway string 银联支付方式。见全局字典《3.2.6 银联POS机支付方式》
pos_tracetime string 银行交易时间

6.2.2 退款结果通知

注: 仅退款成功才向业务推送订单退款结果。

协议: HTTP/HTTPS

URL: 业务方的支付回调URL,即《5.2.1 请求收银台 》协议中的 callback_url 字段,extra 是业务方透传JSON字段。

方法: POST

请求体Body

当 type = refund 时, data为退款记录JSON,各字段说明如下:

字段 类型 是否必 返回 说明
pay_channel String Y 支付通道;见全局字典《3.2.3 支付通道 》。 业务方根据此字段来区别pos和C扫B及其他场景。
id long Y
out_trade_no string Y 中台订单号
transaction_id string 微信或支付宝的交易ID
operate_time string
total_fee string Y 原订单金额
send_back_fee string 实际退款金额
refund_amount string Y 申请退款金额
openid string 微信或支付宝用户的ID
authen_type string
currency_unit string Y 人民币单位, fen/yuan
trans_date string 交易日期
pos_mer_id string 商户号
pos_bank_trace string 交易检索参考号
pos_refund_cardno string 退货交易卡号后4位
pos_refund_bankname string 银行卡名称
pos_refund_trace string 退货流水号
status int Y 字典详见 3.2.8 退款状态
business_order_type string 业务订单类型
business_order_no string 业务订单号
out_refund_no string Y 中台退款号, 退货交易唯一标识。由于支持部分退货交易,所以商户要防止重复退货
refund_time string 退款时间
pos_shopid string 商户号
pos_refund_status string 字典详见 3.2.6 银联pos退货/款状态
refund_status_msg string 退款状态说明
pay_channel string

参考原型:

https://modao.cc/app/oeCVcKb3rrcdfhR0W18V4J#screen=sleqgl3qimglf3jp25kuub0l2

6.2.3 对帐结果通知

注: 由银联向中台发起对帐通知, 中台收到通知后向业务推送对帐结果通知。

协议: HTTP/HTTPS

URL: 由中台配置业务方的通知URL

方法: POST

请求体Body

当 type = checkbill 时, data为对帐记录JSON,各字段说明如下:

对账记录JSON各字段说明:

字段 类型 是否不为空 说明
id long Y
tracedate string Y 支付交易日期,格式为YYYYMMDD
tracetime string pos支付业务发生的时间, 格式:yyyyMMddhhmmss
orderno string Y 中台交易流水号。即支付流水号out_trade_no 。
ordertype string Y 订单类型: 01普通运单, 02快速签单, 03合并签单, 04组合支付签单
txnamt string Y 交易金额, 单位(元)
cod string 支付金额, 单位(元)
fee string 运费, 单位(元)
payway string Y 支付方式: 01 现金, 02刷卡(银行卡), 03预付卡 , 04 抵用券 , 05支票 , 06 积分 , 94 银联二维码, 95 账户快捷, 96 账户余额, 97 微信, 98 支付宝, 99 其它
settledate string Y 清算日期, 格式为YYYYMMDD
settleamount string 清算金额, 为代收款交易金额-手续费
charge string Y 刷卡手续费, 单位(元)
cardid string 账号/卡号
bankname string 发卡行名称
cardtype string 卡类型: 01:借记账户,02:贷记账户,03:准贷记账户,04:借贷合一账户,05:预付费账户,06:半开放预付费账户,xn:虚拟账户,dz:电子钱包(B扫C),G:电子钱包(C扫B固定),D:电子钱包(C扫B动态),1:借记卡,3:贷记卡,5:准贷记卡
settletermid string 清算终端号
termid string Y 受理终端号
postrace string Y 凭证号
banktrace string Y 检索参考号
txntype string Y 交易类型: 消费01, 消费撤销02, 退货03, 差错-结算退单9123, 差错-二次结算退单9127, 分期消费1215, 分期交易撤销1217 当前仅01、02、03三种状态。02或03代表退款 01代表付款。
codmername string Y 商户名称
codmercode string Y 商户号
bizcomname string 配送商户名称
bizcomcode string 配送商户号
dsorderno string 物流订单号
netcode string 网点编码
netname string 网点名称, 车牌
dssn string 自有电商编码
dsname string 自有电商名称, Vin码
remark string 备注, 姓名
clearcomname string 清算商户号
clearcomcode string 清算商户号
Copyright © www.remacsmart.com/ 2021 all right reserved,powered by Gitbook该文件修订时间: 2024-06-13 17:12:46

results matching ""

    No results matching ""