# 第三方预算接入

# 背景

美团企业版支持在企业员工因公消费时进行预算管控：

预算充足，则允许使用企业支付
预算不足，则走个人支付或组合支付或不允许支付（取决于企业配置）

预算管控分为两类：

使用美团企业版预算中心进行预算配置
使用企业内部预算系统进行预算配置

如果企业有自己的预算系统，希望再管控环节通过内部预算对员工因公消费进行管控，则可以按照本文档完成对接流程。

# 对接流程

对接流程图示

员工下单支付时，美团企业版调用第三方提供的预算查询接口查询员工可用预算额度，如果预算额度小于订单金额，则走个人支付或组合支付或不允许支付（取决于企业配置）。如果预算额度很大（如部门预算）且企业不想在收银台展示，就需要使用预估金额。预估金额通常是订单金额，在员工承担服务费时，预估金额会比订单金额稍大。当预算额度比预估金额大时，接口返回的预算额度可以设置为预估金额。差旅、企业用车两个场景不调这个预算查询接口而是调第三方事中管控接口
预算额度大于订单金额时，美团企业版调用第三方提供的预算扣减接口进行预算扣减，扣减成功才会完成支付流程；调用失败或扣减失败，则取消支付
订单支付成功后，如果订单发生退款，美团企业版将调用第三方提供的预算恢复接口进行预算恢复

调用预算扣减或预算恢复接口时，可能因为网络原因出现美团企业版调用第三方接口超时，无法明确获知第三方状态，因此要求第三方提供预算扣减状态查询或预算恢复状态查询接口。

美团企业版调用第三方预算扣减接口超时时，为了避免重试导致响应时间过慢，影响用户体验，美团企业版会当做失败处理。美团企业版启动异步线程调用预算扣减状态查询查询 预算扣减的最终状态，如果第三方预算扣减成功，为了避免占用预算导致客诉，美团企业版会调用预算恢复接口将预算归还。

预算扣减状态查询和预算恢复状态查询接口是为了保持双方系统最终一致性，第三方必须提供接口实现。

第三方预算接入需要包含的接口：

预算查询
预算扣减
预算扣减状态查询
预算恢复
预算恢复状态查询

# 注意事项

第三方返回结果格式如下，需要对业务响应结果进行加密

名称	类型	说明
status	Integer	响应状态，0 成功；1000 参数异常；1001 budgetKey不存在；2000 系统异常
msg	String	失败时的错误描述
data	String	请求成功时的响应体，和具体业务有关，后文简称`业务响应`。注意事项 1 这是个String对象，不是`JSON对象` 2 接口实际返回的数据需要使用`秘钥`加密，为方便展示数据格式，后文示例的数据没有加密。

返回的结果如下
{
    "status": 0,
    "msg": "成功",
    "data": "TEO4UwZq-PIgY9n2fXyt_0uYviWdgQXGRiwcAyOsWPaLw3YBLslAPopgul1NHv5O_UfF2Lh4qOkqZPRZhLC2vw"
}

对data解密后得到
{
    "status": 0,
    "msg": "成功",
    "data": "{\"thirdRefundOrderId\": \"393356317696072_1547611857314\"}"
}

实际的业务响应

{
	"thirdRefundOrderId" : "393356317696072_1547611857314"
}

# 1.预算查询

# 接口说明

名称	描述
功能	根据预算标识获取企业员工预算信息
HTTP方法	POST
请求方	美团企业版平台
响应方	第三方平台
url	第三方提供
method	trade.out.budget.query

# 公共请求参数

详见：公共参数说明-公共请求参数

# 业务请求参数

名称	类型	是否必填	示例	说明
budgetKey	String	是	12345	预算标识
sqtBizOrderId	Long	否	1531811894960001	美团企业版订单ID
estimateAmount	String	是	"25.12"	预估金额，单位元，两位小数

# 业务响应

名称	类型	是否非空	说明
budgetKey	String	是	预算标识
availableBalance	String	是	预算可用余额，单位元，两位小数

# 示例

业务请求参数
{
    "method":"trade.out.budget.query",
    "ts":1512963578,
    "entId":1,
	"budgetKey" : "123", 
    "sqtBizOrderId" : 1531811894960001,
    "estimateAmount"： "123.12"
}

业务响应

{
	"budgetKey" : "123",
	"availableBalance" : "123.12"
}

# 2.预算扣减

# 接口说明

名称	描述
功能	用户使用企业支付时，美团企业版平台通过本接口请求第三方平台扣减员工预算额度
HTTP方法	POST
请求方	美团企业版平台
响应方	第三方平台
url	第三方提供
method	trade.budget.pay

# 公共请求参数

详见：公共参数说明-公共请求参数

# 业务请求参数

名称	类型	是否必填	示例	说明
sqtOrderId	Long	是	1531811894960001	美团企业版交易平台订单号
serialNum	String	是	3TOSSCUR3H	美团企业版支付序列号
budgetKey	String	是	"111290"	第三方系统预算标识
sqtBudgetPayFlowNo	String	是	"554823186753411"	美团企业版预算扣减流水号，根据此字段支持幂等
~~payAmount~~	String	是	"25.12"	订单支付金额(已弃用，建议使用entPayAmount)
entPayAmount	String	是	"25.12"	企业支付金额(不包含随单服务费)
serviceFeeAmount	String	否	"0.12"	随单服务费（空值表示无服务费）
payTime	String	是	"2018-10-12 12:12:12"	支付发起时间 yyyy-MM-dd HH:mm:ss
sqtBizOrderId	Long	是	1531811894960001	美团企业版订单ID
payId	String	是	"790824824555390"	美团企业版交易平台支付流水号

# 业务响应

名称	类型	是否必填	示例	说明
outBudgetPayFlowNo	String	是	"202004160000000007"	三方预算扣减流水号

# 示例

业务请求
{
  "method":"trade.budget.pay",
  "ts":1512963578,
  "entId":1,
  "sqtOrderId": 1531811894960001,
  "serialNum": "3TOSSCUR3H",
  "budgetKey":"111290",
  "sqtBudgetPayFlowNo":"554823186753411",
  "payAmount": "25.12",
  "entPayAmount": "25.12",
  "serviceFeeAmount": "0.12",
  "payTime": "2018-10-12 12:12:12",
  "sqtBizOrderId": 1531811894960001,
  "payId": "790824824555390"
}

业务响应

{
	"outBudgetPayFlowNo" : "202004160000000007"
}

# 3.预算扣减状态查询

# 接口说明

名称	描述
功能	根据美团企业版预算扣减流水号查询第三方预算扣减状态
HTTP方法	POST
请求方	美团企业版平台
响应方	第三方平台
url	第三方提供
method	trade.budget.pay.query

# 公共请求参数

详见：公共参数说明-公共请求参数

# 业务请求参数

名称	类型	是否必填	示例	说明
sqtBudgetPayFlowNo	String	是	"554823186753411"	美团企业版预算扣减流水号

# 业务响应

名称	类型	是否必填	示例	说明
sqtBudgetPayFlowNo	String	是	"554823186753411"	美团企业版预算扣减流水号
outBudgetPayFlowNo	String	是	"202004160000000006"	三方预算扣减流水号
payStatus	Integer	是	2	扣减状态 0: 未扣减 1:扣减中 2:扣减成功 3:扣减失败
~~payAmount~~	String	是	"25.12"	订单支付金额(已弃用，建议使用entPayAmount)
entPayAmount	String	是	"25.12"	企业支付金额(不包含随单服务费)
serviceFeeAmount	String	否	"0.12"	随单服务费（空值表示无服务费）

# 示例

业务请求
{
    "method":"trade.budget.pay.query",
    "ts":1512963578,
    "entId":1,
	"sqtBudgetPayFlowNo": "554823186753411"
}

业务响应
{
    "sqtBudgetPayFlowNo": "554823186753411",
    "outBudgetPayFlowNo": "202004160000000006",
    "payStatus": 2,
    "payAmount": "25.12", 
    "entPayAmount": "25.12",
    "serviceFeeAmount": "0.12",
}

# 4.预算恢复

# 接口说明

名称	描述
功能	用户使用企业退款时，美团企业版平台通过本接口请求第三方平台恢复预算额度
HTTP方法	POST
请求方	美团企业版平台
响应方	第三方平台
url	第三方提供
method	trade.budget.refund

# 公共请求参数

详见：公共参数说明-公共请求参数

# 业务请求参数

名称	类型	是否必填	示例	说明
sqtOrderId	Long	是	1531811894960001	美团企业版交易平台订单号
serialNum	String	是	3TOSSCUR3H	美团企业版支付序列号
budgetKey	String	是	"111290"	第三方系统预算标识
refundId	String	否	"12321431894960001"	美团企业版交易平台退款流水号
sqtBudgetPayFlowNo	String	是	"554823186753411"	美团企业版预算支付流水号
sqtBudgetRefundFlowNo	String	是	"554823226873750"	美团企业版预算退款流水号，根据此字段支持幂等。
refundAmount	String	是	"25.12"	本次退款金额（不包含服务费）
serviceFeeRefundAmount	String	否	"0.12"	本次退款随单服务费（空值表示无服务费）
refundTime	String	是	"2018-10-12 12:12:12"	退款发起时间 yyyy-MM-dd HH:mm:ss
sqtBizOrderId	Long	是	1531811894960001	美团企业版订单ID

# 业务响应

名称	类型	是否必填	示例	说明
outBudgetRefundFlowNo	String	是	"202004160000000006"	三方预算退款流水号

# 示例

业务请求
{
  "method":"trade.budget.refund",
  "ts":1512963578,
  "entId":1,
  "sqtOrderId": 1531811894960001,
  "serialNum": "3TOSSCUR3H",
  "budgetKey": "111290",
  "refundId": 1232143189496001,
  "sqtBudgetPayFlowNo":"554823186753411",
  "sqtBudgetRefundFlowNo": "554823226873750",
  "refundAmount": "25.12",
  "serviceFeeRefundAmount": "0.12",
  "refundTime": "2018-10-15 15:12:11",
  "sqtBizOrderId": 1531811894960001
}

业务响应
{
    "outBudgetRefundFlowNo": "202004160000000006"
}

# 5.预算恢复状态查询

# 接口说明

名称	描述
功能	根据美团企业版预算恢复流水号查询三方预算恢复状态
HTTP方法	POST
请求方	美团企业版平台
响应方	第三方平台
url	第三方提供
method	trade.budget.refund.query

# 公共请求参数

详见：公共参数说明-公共请求参数

# 业务请求参数

名称	类型	是否必填	示例	说明
sqtBudgetRefundFlowNo	String	是	"554823226873750"	美团企业版预算恢复流水号

# 业务响应

名称	类型	是否必填	示例	说明
sqtBudgetRefundFlowNo	String	是	"554823226873750"	美团企业版预算恢复流水号
outBudgetRefundFlowNo	String	是	"202004160000000006"	三方预算恢复流水号
refundStatus	Integer	是	2	恢复状态 0: 未恢复 1:恢复中 2:恢复成功 3:恢复失败
refundAmount	String	是	"25.12"	本次退款金额（不包含服务费）
serviceFeeRefundAmount	String	否	"0.12"	本次退款随单服务费（空值表示无服务费）

# 示例

业务请求
{
  "method":"trade.budget.refund.query",
  "ts":1512963578,
  "entId":1,
  "sqtBudgetRefundFlowNo": "554823226873750"
}

业务响应
{
    "sqtBudgetRefundFlowNo": "554823186753411",
    "outBudgetRefundFlowNo": "202004160000000006",
    "refundStatus": 2,
    "refundAmount": "25.12", 
    "serviceFeeRefundAmount": "0.12"
}

# 6.预算账单下载

建议第三方平台下载账单进行对账

# 接口说明

名称	描述
功能	获取预算账单下载链接
HTTP方法	POST
请求方	第三方平台
响应方	美团企业版平台
uri	$API_HOST/queryBudgetBill
method	`trade.budget.bill.query`

# 公共请求参数

详见：公共参数说明-公共请求参数

# 业务请求参数

名称	类型	是否必填	示例	说明
billDate	String	是	2018-12-12	账单日期，yyyy-MM-dd。当天账单不可下载，最新可下载昨日账单。下载月账单，请填写该月第一天，例如2018-12-01
billDateType	Integer	是	0	0 日账单 1 月账单

# 业务响应

名称	类型	是否非空	说明
url	String	否	账单下载url，有效期为1分钟
desc	String	是	说明

# 示例

{
    "status": 0,
    "msg": "成功",
    "data": {
        "url": "https://api-sqt.meituan.com/trade/dailyBill/download?url=xxx",
        "desc": "成功"
    }
}

# 7.预算流水查询接口

# 接口说明

名称	描述
功能	获取美团企业版预算扣减和恢复记录
HTTP方法	POST
请求方	第三方平台
响应方	美团企业版平台
uri	$API_HOST/queryBudgetFlow
method	`trade.budget.flow.query`

# 公共请求参数

详见：公共参数说明-公共请求参数

# 业务请求参数

名称	类型	是否必填	示例	说明
sqtBudgetPayFlowNo	String	是	"554823186753411"	美团企业版预算支付流水号

# 业务响应

名称	类型	是否非空	说明
budgetPayInfo	SqtBudgetPayInfo	是	美团企业版预算支付流水信息
budgetRefundInfoList	List<SqtBudgetRefundInfo>	否	美团企业版预算恢复流水信息

SqtBudgetPayInfo字段说明

名称	类型	是否必填	示例	说明
sqtBudgetPayFlowNo	String	是	"554823186753411"	美团企业版预算扣减流水号
outBudgetPayFlowNo	String	是	"202004160000000006"	三方预算扣减流水号
payStatus	Integer	是	2	扣减状态 0: 未扣减 1:扣减中 2:扣减成功 3:扣减失败，只返回扣减成功的
~~payAmount~~	String	是	"25.12"	订单支付金额(已弃用，建议使用entPayAmount)
entPayAmount	String	是	"25.12"	企业支付金额(不包含随单服务费)
serviceFeeAmount	String	否	"0.12"	随单服务费（空值表示无服务费）

SqtBudgetRefundInfo字段说明

名称	类型	是否必填	示例	说明
sqtBudgetRefundFlowNo	String	是	"554823226873750"	美团企业版预算恢复流水号
outBudgetRefundFlowNo	String	否	"202004160000000006"	三方预算恢复流水号,三方未成功恢复时为空
refundStatus	Integer	是	2	恢复状态 0: 未恢复 1:恢复中 2:恢复成功 3:恢复失败
refundAmount	String	是	"25.12"	退款金额（不含服务费）
serviceFeeRefundAmount	String	否	"0.12"	本次退款随单服务费（空值表示无服务费）

# 示例

{
	"status": 0,
	"msg": "成功",
	"data": {
		"budgetPayInfo": {
			"sqtBudgetPayFlowNo": "554823186753411",
			"outBudgetPayFlowNo": "202004160000000006",
			"payStatus": 2,
			"payAmount": "25.12",
          "entPayAmount": "25.12",
          "serviceFeeAmount": "0.12"
		},
		"budgetRefundInfoList": [{
			"sqtBudgetRefundFlowNo": "554823186753411",
			"outBudgetRefundFlowNo": "202004160000000006",
			"refundStatus": 2,
			"refundAmount": "25.12", 
            "serviceFeeRefundAmount": "0.12"
		}]
	}
}

← 企业账户标准三方对接 →