跳转至

生鲜应用对接

1. 阅读对象

本文档的阅读对象为合作方的产品研发人员。

2. 统一语言

名词 说明
合作方 提供生鲜服务的平台。

3. 业务描述

本文档使用生鲜应用对接项目。

用户从关爱通侧跳转到合作方的应用里完成交易。

交易中扣减用户在关爱通侧的资产（技术对接完成）。

合作方需要将交易相关明细通过本文档描述的接口推送关爱通。

4. 通用协议

4.1. 对接准备

​ ● 关爱通给合作方开通测试环境的 appid 和 appsecret

​ ● 关爱通协助合作方完成开发者授权

​ ● 文档中涉及的金额单位统一为元，并保留2为小数

4.2. 基本信息

对接都是基于关爱通的开放平台完成，因此可了解关爱通开放平台的一些内容：

● 对接说明&通用协议

4.3. 接口协议

除了标准支付（跳关爱通收银台），其他接口基于 JSON 数据格式，https 安全加密传输协议。

公共入参请查看：公共参数 - 关爱通开放平台

公共返回参数如下：

参数名称 是否必须 参数类型 长度限制 描述
code 是 Integer [1,10] 错误码，为 0 则表示成功。
msg 是 String [0, 128] 具有可读性的请求结果信息。
data 是 Object 具体业务返回内容，以 JSON 格式组织。

下文接口说明里只描述业务有关的入参数据和返回内容里 data 数据。

有些接口需要额外申请开通。

5. 业务接口

5.1. 标准支付

接口路径:

/seller/v3/pay/excashier

ContentType:

application/json

HTTP请求方式:

POST

接口说明: 当用户在合作方侧下单后，到支付环节时，合作方通过该接口唤起关爱通的收银台。

请求入参：

  • 公有参数

    发送请求是必须传入公共参数，详见公共参数

  • 私有参数

参数名称 是否必须 参数类型 长度限制 描述
outerTradeNo 是 String [2,50] 外部交易号，请以appid开头
timeOrdered 是 string 50 下单时间，格式（yyyy-MM-dd HH:mm:ss）
buyerOpenId 是 String 32 下单员工唯一标识
reason 否 String [0,245] 买家备注
totalAmount 是 BigDecimal (10, 2) 订单总金额（含运费），支付的总金额
tradeInfo 否 Object 订单信息
attach 否 string [0,100] 附加信息,原样返回,复杂参数建议urlencode
tradeType 否 int 1 交易类型 1即时交易 2非即时交易 默认为即时交易
returnUrl 是 string [1,254] 支付完成后，跳转的商家订单显示URL
notifyUrl 是 string [1,254] 商家提供的notifyUrl。订单完成后，关爱通会对此URL进行请求，通知商家订单成功
expireTime 否 string [0,50] 订单支付超时时间,格式（yyyy-MM-dd HH:mm:ss）
provinceCode 否 string [0,50] 消费省会编码
provinceName 否 String [0,50] 消费省会
cityCode 否 string [0,50] 消费城市编码
cityName 否 String [0,50] 消费城市
locationCode 否 string [0,50] 消费地区编码
locationName 否 String [0,50] 消费地区
shopName 否 String [0,100] 商家名称
shopPhone 否 String [0,50] 商家电话
shopAddress 否 String [0,500] 商家地址
poiCateCode 否 String [0,100] 商家一级品类code
poiCateDesc 否 String [0,100] 商家一级品类名称
poi2ndCateCode 否 String [0,100] 商家二级品类code
poi2ndCateDesc 否 String [0,100] 商家二级品类名称
poi3rdCateCode 否 String [0,100] 商家三级品类code
poi3rdCateDesc 否 String [0,100] 商家三级品类名称
recipientName 否 String [0,50] 收货人名称
recipientPhone 否 String [0,50] 收货人电话
recipientAddress 否 String [0,500] 收货人地址

TradeInfo对象

参数名称 是否必须 参数类型 长度限制 描述
thirdTradeNo 是 string [1,50] 第三方订单号
thirdTotalAmount 是 decimal [0.01,99999999.99] 订单总金额
thirdPayAmount 是 decimal [0.01,99999999.99] 支付总金额
thirdCostAmount 是 decimal [0.00,99999999.99] 结算总成本价
thirdDeliveryFee 否 decimal [0.00,99999999.99] 有运费必填 运费
isThirdOrders 是 int 1 是否有子订单 1有 2无
thirdOrders 否 object 无 有子订单必填。子订单信息列表，List 请按照商家拆分子订单
goodsDetail 否 object 无 无子订单必填。商品信息列表，List

注意 在返点模式下： thirdPayAmount与thirdCostAmount金额要保持一致

ThirdOrder对象

参数名称 是否必须 参数类型 长度限制 描述
outerTradeNo 是 String [2,50] 子订单的外部交易号，请以appid开头，不能与主订单一致
thirdSubTradeNo 是 string [1,50] 第三方子订单编号
thirdSubDeliveryFee 否 decimal [0.00,99999999.99] 有运费必填 运费
thirdSubTotalAmount 是 decimal [0.01,99999999.99] 子订单原金额
thirdSubPayAmount 是 decimal [0.01,99999999.99] 子订单原支付金额
thirdSubCostAmount 是 decimal [0.00,99999999.99] 子订单原结算成本价
goodsDetail 是 object 无 商品信息列表，List

GoodsDetail数据：

参数名称 是否必须 参数类型 长度限制 描述 示例
skuCode 是 String [1, 50] 商品编码 100013952938
skuName 是 String [1, 50] 商品名称 蒙牛 特仑苏脱脂纯牛奶 每100ml含3.6g乳蛋白 送礼推荐 250ml×16 礼盒装
skuCateCode 否 String [0,100] 商品一级品类code
skuCateDesc 否 String [0,100] 商品一级品类名称
sku2ndCateCode 否 String [0,100] 商品二级品类code
sku2ndCateDesc 否 String [0,100] 商品二级品类名称
sku3rdCateCode 否 String [0,100] 商品三级品类code
sku3rdCateDesc 否 String [0,100] 商品三级品类名称
quantity 是 Integer 32 数量 1
price 是 BigDecimal (10, 2) 商品单价 115.35
taxRate 否 BigDecimal (10, 2) 税率 13
taxCode 否 String [1, 50] 税收分类编码 1060406010000000000
taxUnit 否 String [1, 20] 开票单位 件
invoiceType 否 Integer 32 发票类型 (1:普票 2:专票) 2
amount 是 BigDecimal (10, 2) 商品金额（price * quantity） 115.35
gatAmount 是 BigDecimal (10, 2) 关爱通资产支付金额 115.35
costAmount 是 BigDecimal (10, 2) 关爱通结算价 115.35
freight 否 BigDecimal (10, 2) 运费（非单个商品的运费） 8

5.1.1. 返回示例

{
    "code": 0,
    "msg": "OK",
    "data": {
        "outerTradeNo":"200913220230728003450944707739",
        "redirectUrl":"https://excashier.guanaitong.com/entry?reason=%E5%8F%AE%E5%92%9A%E4%B9%B0%E8%8F%9C-2307281159271857739&outer_trade_no=200913220230728003450944707739&owner_id=xxx&sign=8810E9B3888D5923763DF8C648F4FEA771D7DA74&source_appid=20091322&signtype=SHA1&notify_url=https%3A%2F%2Fopenapi.guanaitong.com%2Fseller%2Fpay%2FnotifyUrl&encoding=UTF-8&output=JSON&point_payer_id=xxx&total=44.00&issync=2&apiname=gat.account.pay&v=3.0&appid=20091322&return_url=https%3A%2F%2Fopenapi.guanaitong.com%2Fseller%2Fpay%2FreturnUrl&point_payee_id=%E5%8F%AE%E5%92%9A%E4%B9%B0%E8%8F%9C%E7%9B%B4%E8%BF%9E&timestamp=20230728112919"
    }
}
说明

合作方拿到回调地址，进行302跳转

5.1.2. 跳回商家（return_url）

从关爱通收银台，跳回商家页面

请求URL

调用支付接口时,填写的return_url

HTTP请求方式

GET 跳转页面

输入参数说明
参数名称 参数类型 描述
appid string 应用appid
outer_trade_no string 跳转收银台时传递的外部交易号
attach string 前面附带的信息
pay_result string success成功 fail 失败
timestamp string 时间戳，其值为1970-1-01 00:00:00.000到当前时刻的时间距离，单位是秒，时区为GMT+8（东八区）。如1469691921。关爱通接口允许的时间戳偏差为5分钟，偏差超过5分钟的请求将被拒绝。
sign string 签名，见 签名机制
请求示例（浏览器URL）为：
https://test.guanaitong.com/?outer_trade_no=100000010000000001&appid=10000001&
timestamp=1537253931&sign=c9a7ede47d9f40a599d76e98a8c8a039d7ae4e2d&pay_result=success
跳转说明

（1）用户支付完成后，会跳转到商家填写的return_url地址； （2）商家根据outerTradeNo进入订单支付中的页面； （3）商家服务端等待来自关爱通的notify通知，更新订单状态后，页面改为订单成功；

5.1.3.支付回调（notify_url）

请求URL

调用支付接口时,填写的notify_url

HTTP请求方式

POST

输入参数说明
参数名称 参数类型 描述
appid string 应用appid
outer_trade_no string 外部交易号
buyer_open_id string 下单人open_id
attach string 前面附带的信息
total_amount decimal 下单金额
trade_no string 关爱通交易号
timestamp string 时间戳，其值为1970-1-01 00:00:00.000到当前时刻的时间距离，单位是秒，时区为GMT+8（东八区）。如1469691921。关爱通接口允许的时间戳偏差为5分钟，偏差超过5分钟的请求将被拒绝。
sign string 签名，见 签名机制
请求示例
POST 商家URI,如:/syncPay/notify HTTP/1.1
Host: 商家域名,如:test.guanaitong.com
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

appid=10000001&outer_trade_no=100000010000000001&total_amount=100.00&
buyer_open_id=d87797eea12a2f80ad72ed93214a0908&trade_no=2018070920000005&
timestamp=1531120153&sign=31f531d0ca40e6d7fb02688564f637f458e63ec8
返回参数说明
  1. notify只有在关爱通订单成功后才会发送；
  2. 商家在收到了请求、校验通过后，请即时更新自己的订单状态，并返回success（不要带任何其他源码内容）；
  3. 若关爱通的notify请求无响应或者接收的内容不是“success”，则认为通知失败，等一段时间后会再次请求（notify请求会在此后24小时内按递增时间间隔继续发送通知）；
  4. notify仅为通知，不论第三方返回成功或失败，都不会改变关爱通的订单状态；
正确返回示例
success
错误返回示例
fail

5.2. 标准退款

接口路径:

/seller/v3/pay/syncRefund

ContentType:

application/json

HTTP请求方式:

POST

请求入参：

  • 公有参数

    发送请求是必须传入公共参数，详见公共参数

  • 私有参数

参数名称 是否必须 参数类型 长度限制 描述
outerTradeNo 是 string [2,50] 外部交易号，请以appid开头，例如：10000001101
outerRefundNo 是 string [2,50] 外部退款号，请以appid开头，例如：10000001201
reason 是 string [1,254] 退款原因
refundAmount 是 decimal [0.01,99999999.99] 本次退款的总金额
costAmount 否 BigDecimal (10, 2) 结算价（差价结算时需要，具体咨询关爱通对接人员）
deliveryFee 否 decimal [0.01,99999999.99] 运费（结算价包含运费时，该字段不用传递）
notifyUrl 否 string [1,254] 通知url,非必填,退款完成时进行通知结果,与同步返回结果一致
tradeInfo 否 Object 订单信息
provinceCode 否 Long 64 消费省会编码
provinceName 否 String [0,50] 消费省会
cityCode 否 Long 64 消费城市编码
cityName 否 String [0,50] 消费城市
locationCode 否 Long 64 消费地区编码
locationName 否 String [0,50] 消费地区
shopName 否 String [0,100] 商家名称
shopPhone 否 String [0,50] 商家电话
shopAddress 否 String [0,500] 商家地址
poiCateCode 否 Long 64 商家一级品类code
poiCateDesc 否 String [0,100] 商家一级品类名称
poi2ndCateCode 否 Long 64 商家二级品类code
poi2ndCateDesc 否 String [0,100] 商家二级品类名称
poi3rdCateCode 否 Long 64 商家三级品类code
poi3rdCateDesc 否 String [0,100] 商家三级品类名称
recipientName 否 String [0,50] 收货人名称
recipientPhone 否 String [0,50] 收货人电话
recipientAddress 否 String [0,500] 收货人地址

TradeInfo对象

参数名称 是否必须 参数类型 长度限制 描述
thirdTradeNo 是 string [1,50] 第三方订单号
thirdRefundNo 是 string [1,50] 第三方退款单号
thirdRefundAmount 是 decimal [0.01,99999999.99] 退款总金额
thirdCostAmount 是 decimal [0.00,99999999.99] 结算总成本价
thirdDeliveryFee 否 decimal [0.00,99999999.99] 有运费必填 运费
isThirdOrders 是 int 1 是否有子订单 1有 2无
thirdOrders 否 object 无 有子订单必填。子订单信息列表，List 请按照商家拆分子订单
goodsDetail 否 object 无 无子订单必填。商品信息列表，List

注意 在返点模式下： thirdPayAmount与thirdCostAmount金额要保持一致

ThirdOrder对象：

参数名称 是否必须 参数类型 长度限制 描述
outerTradeNo 是 String [2,50] 子订单的外部交易号，请以appid开头
thirdSubTradeNo 是 string [1,50] 第三方子订单编号
thirdSubRefundNo 是 string [1,50] 第三方子订单退款单号
thirdSubDeliveryFee 否 decimal [0.00,99999999.99] 有运费必填 运费
thirdSubRefundAmount 是 decimal [0.01,99999999.99] 子订单退款金额
thirdSubCostAmount 是 decimal [0.00,99999999.99] 子订单原结算成本价
goodsDetail 是 object 无 商品信息列表，List

GoodsDetail数据：

参数名称 是否必须 参数类型 长度限制 描述 示例
skuCode 是 String [1, 50] 商品编码 100013952938
skuName 是 String [1, 50] 商品名称 蒙牛 特仑苏脱脂纯牛奶 每100ml含3.6g乳蛋白 送礼推荐 250ml×16 礼盒装
skuCateCode 否 Long 64 商品一级品类code
skuCateDesc 否 String [0,100] 商品一级品类名称
sku2ndCateCode 否 Long 64 商品二级品类code
sku2ndCateDesc 否 String [0,100] 商品二级品类名称
sku3rdCateCode 否 Long 64 商品三级品类code
sku3rdCateDesc 否 String [0,100] 商品三级品类名称
quantity 是 Integer 32 数量 1
price 是 BigDecimal (10, 2) 商品单价 115.35
taxRate 否 BigDecimal (10, 2) 税率 13
taxCode 否 String [1, 50] 税收分类编码 1060406010000000000
taxUnit 否 String [1, 20] 开票单位 件
invoiceType 否 Integer 32 发票类型 (1:普票 2:专票) 2
amount 是 BigDecimal (10, 2) 商品金额（price * quantity） 115.35
gatAmount 是 BigDecimal (10, 2) 关爱通资产支付金额 115.35
costAmount 是 BigDecimal (10, 2) 关爱通结算价 115.35
freight 否 BigDecimal (10, 2) 运费（非单个商品的运费） 8

5.3. 完成订单

接口路径:

/seller/v3/pay/complete

ContentType:

application/json

HTTP请求方式:

POST

请求入参：

  • 公有参数

    发送请求是必须传入公共参数，详见公共参数

  • 私有参数

参数名称 是否必须 参数类型 长度限制 描述
outerTradeNo 是 string [2,50] 外部交易号，请以appid开头，例如：10000001101
completeTime 是 string [1,50] 完成时间，格式（yyyy-MM-dd HH:mm:ss）

6. 测试场景

请查看测试场景

回到页面顶部