# 第三方支付接入文档

# 1.【对接说明】

第三方收银台对接，请阅读美团企业版收银台对接文档，可以提升对接效率。

# 1.1 第三方平台对接时序图

第三方平台对接时序图

# 1.2 接口交互时序图

接口交互时序图

美团企业版交易平台向第三方平台发起下单支付请求，第三方平台处理支付返回支付流水号和支付页面的URL，美团企业版跳转到第三方平台支付页面。
用户在第三方平台完成支付后，第三方平台向美团企业版交易平台发起支付回调通知请求，美团企业版交易平台扭转订单状态。
第三方平台需要提供支付状态查询接口，在没有回调通知美团企业版交易平台支付状态时，美团企业版会启动兜底轮训任务主动去第三方平台查询获取用户支付情况。
用户申请退款，商家确认退款后，美团企业版交易平台会向第三方平台发起退款请求，第三方平台处理退款并返回退款流水号。（在商家确认退款后，美团企业版会将钱退回企业钱包，第三方平台收到退款请求时需要保证处理成功，将退款及时退回给用户，减少用户咨询）

# 注意事项

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

名称	类型	说明
status	Integer	响应状态：0 成功；其他值均为：调用失败
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"
}

# 2.【业务接口说明】

# 2.1 下单接口

# 接口说明

名称	描述
功能	美团企业版交易平台向第三方平台发起下单，获得交易流水号和支付页面的URL，跳转到第三方平台支付页面
HTTP方法	POST, application/x-www-form-urlencoded
请求方	美团企业版平台
响应方	第三方平台
url	第三方平台提供
method	trade.third.pay

# 公共参数

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

# 业务请求参数

名称	类型	是否必填	示例	说明
tradeNo	Long	是	393033370136698	交易号，唯一标示一次下单请求
sqtBizOrderId	Long	是	345905477526402	美团企业版订单ID
tradeAmount	String	是	12.32	支付金额(不包含服务费)，单位元，两位小数
serviceFeeAmount	String	否	0.32	随单服务费（空值表示没有服务费），单位元，两位小数
goodsName	String	是	测试产品	商品名称
tradeTime	String	是	2018-10-10 12:12:34	交易时间，格式yyyy-MM-dd hh:mm:ss
notifyUrl	String	是	https://xxx/callback	第三方平台支付成功时，后台发POST通知美团企业版支付成功的地址
returnUrl	String	是	https://xxx/statusdetail	第三方平台支付成功时，前端重定向地址，通常是订单详情页。
businessType	Integer	是	1	业务类型（见下表）
extInfoMap	Map	是		员工的所有相关信息和外部企业定制额外参数，需要双方协商确定(见下表)

businessType	说明
1	买单
2	预定
3	团购
4	外卖
5	打车
10	酒店
11	门票
12	机票
13	火车票
14	电影票
15	扫码付
16	线下买单
19	优选
20	买菜
21	团好货
22	盒餐
23	现场就餐
24	跑腿
-1	其他

extInfoMap字段说明

名称	类型	是否非空	示例	说明
staffId	Long	是	397374	美团企业版员工号
entStaffNum	String	否	39WNRUYJC1Z6	第三方员工工号
phone	String	否	188****1234	员工手机号
email	String	否	12345@qq.com	员工邮箱
staffName	String	否	肯旋风	员工姓名

# 业务响应

名称	类型	是否非空	说明
thirdPayOrderId	String	是	第三方平台支付订单号
thirdPayUrl	String	是	第三方平台支付页面URL，美团企业版以GET方式重定向到该地址。必须是`https`，否则ios不能访问。

# 请求content示例

{
  "ts":1626333171,
  "method":"trade.third.pay",
  "entId":100570,
  "tradeNo":1415570032678670389,
  "sqtBizOrderId":547435397400850434,
  "tradeAmount":"17.90",
  "serviceFeeAmount":"0.32",
  "goodsName":"美团超市-自配【闪购专用】lllll-6050913679019657",
  "tradeTime":"2021-07-15 15:12:51",
  "notifyUrl":"http://inf-openapi.apigw.test.sankuai.com/api/sqt/openapi/standardThird/pay/callback",
  "returnUrl":"http://h5.waimai.test.sankuai.com/waimai/mindex/order-detail?mtOrderViewId=6050913679019657",
  "businessType":4,
  "extInfoMap":{
    "entStaffNum":"",
    "phone":"11123452345",
    "staffName":"永健",
    "staffId":646359,
    "email":""
  }
}

# 响应密文示例

{
  "status":0,
  "msg":"成功",
  "data":"USolgT6N4Ls5c1IeTZy3W2HCDWhdjvz3jg-GgE7FWD6uImH9FYn1j8eUpge6YQyado0cqidYHnKTbDCTt0s_FDlY8ux4tvSsH_SawY0gVmEsS1FXf-Hab0TeKv4GM3IAQI6iPF8_l2FUzhnU-isrzWUW_FjKDQgdJcgkbDaEfAoTIfFaPzcrtAUOuzJ22u0nN0U3JyevzAMaegWgT0SXQVj2T03C8GP9qf_o02YcInGOxSaeWnq9G_y26zuGLqBePqRtfdXR9lRCU0Yezah8iIPk-j0RxnS59n_txp0fzUz6M-W75pSAMI8DcpJTbgW-DFzjuqU5tXM_WmblEFv6PoMAS8sE-PTRlUHxdiTvd_roxf8jwK3k_ULnfQxgDq0qsWNCda9aDmSiG0xZpL-uMY9TCYXOzhx2rJUglOTzpKVxhZD5Ypky-_haPUCNacTpd6KwxNNzMG56QZaAMjEnzJH8yq5Jmn44-So-BgmdP9cAVPokkBx935YY-f0YtB-K6pdXRPJfOz-nr2aoeL07d0TmHJftzlvUkLiTTqsnaAnR-oeaz97BFxv3lLBb4hhgZ32lV4b-vYSLdV-QbEOOW-tOuvxz3PQFYDSKQTNj1jCM52OEr8Ct5kty9pFZxkFfeMxiNnik1PyAFxRgHo4k0reV0pzjwvSu1EwR8wpcHNhwp4Ak97mN2C83_vVqSbsgfDZFvZLT9nkAwPWk1tu8oX0AQrqgNV4g4Q5DTiOY7JwIfLqTQE7JWLwSGrWw_pPXtNIU5_1hjWvJBGZlz1KiNC-Ju7WnNebqTmr-660sHkB0h7yMi864vNJ30R7FqE0EtILbBy2ZTaJWFqidZOTh1tkCe82BOAEi0_fg_pXtEaLI8W2uST0BKIGItEk7C81oOmE2pRi5lhcwDTV9wsGirC32x_53AOK6vNbsQzlvzYxSAR7Tgu2GjyqxmVqWJkv6ZhkqKl4SmntCMLEG8eY7PtPfir6RdGZ_RA7OJV0KpQ5CE_nCGyQpu36R_ojfYqlufPaAmaL9jlmhn7v8Rnw9YaQ2yOPr3QRJyTosq6sBJLhRmei4oaBP9deUnhlecTYYVdvHRmQksvimqd3eabNOU0NEu9_lojdUY5xBCpGleWQ7jYqyjuycDLrT1Wu2J_cde74-ylF76mkc3O6dia20UnyeHPI8OmAzQW00swTTcrPcOOoprllWbKTuDOexv0_zygVWYUEw1da6FDqYtTmzkEa_n_hUeJugOHxbv-AGGInPCm1-ZQvYxWgOP8-FdJ6w"
}

# 响应明文示例

{
  "status":0,
  "msg":"成功",
  "data":"{\"thirdPayOrderId\": \"1626333171\",\"thirdPayUrl\": \"https://sqt-api.test.meituan.com/thirdPay/standard/third/mock/payCallback?content=ABqq3WA5ujGjIPuyYKLOZd4L16Nn3Fwj5loWgNRFPtQcTgUCnIuQO233-Gh5u0h8k9NxAmhVXkQDTrVUVA9deZ1_tk8w9IMfrORWlBVk1xAKVyLo67FmG4WcERL2A24OIkr59RmNxm0K--W5ijfZg2pLkkmgOatDxgPu5SCZID9a2opkvI3LkIlv7nLanzrBl879SZmaj4E2HHHFU5UTUw-1P9oQmqfqslnHSNNVsdNonkOSjTcJQ0wiKqhe5sVB25gv3loFXLFS65YuN4EWWfyljnfsOUxzFImQb8Ps4ulXf7q6fzjk3ULhJSDQ1-y49QhWz9VI2rPTciDcQERP9GED3Wpn3FZPBjhxEKeVcTZtYkW6b_Gxo9qweRDR3lwehwbh6iMGEQdM1ZYAkoHarhq3Tbib_ZReQ7SyqdJipYkXKMiuX8Y35jlVSPzkJMNluXecyXwZhhMSSWUR1srju9WVODgrrOik94MQ3bt37vuS1o4we-5-QUgJhjMMpr-z5IAz5Hb-voXzok581T8-vExtc0vu0axzi7HY6VqQm_3rNW2MoLrOoPeLA1J4MpHdpLO7WszFp7HBDl5tVEhHFKcsgDoS1yM27HV-5PEK6eZRE3x2U_dtRaXaMjWcQ9NWJPTh7hIpmBBKR0DRGhPVtRDeS7FgdRj5RBfVlaNqSFmAg3gH6HFanGfLwnEY5NDVOgNDvgxUd1IDfdQPowfw_Q_QqQHTXKmIJdqkIWC5xCDQDrmAviNB-bUGRx6KNjEsJI80wm_bseFRJgTK3lPSiQ&thirdPayOrderId=1626333171"
}

# 2.2 支付成功通知

# 接口说明

名称	描述
功能	用户支付完成时，第三方平台通知美团企业版交易平台
HTTP方法	POST, application/x-www-form-urlencoded
请求方	第三方渠道
响应方	美团企业版平台
url	下单参数中的notifyUrl
method	trade.third.pay.callback

# 公共参数

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

# 业务请求参数

名称	类型	是否必填	示例	说明
tradeNo	Long	是	393033370136698	交易号，唯一标示一次下单请求
thirdPayOrderId	String	是	393073139773549_3VBZB2KN71	第三方平台支付订单号
payAmount	String	是	12.32	支付金额(不包含服务费)，单位元，两位小数
serviceFeeAmount	String	否	0.32	随单服务费（空值表示没有服务费），单位元，两位小数
payTime	String	是	2018-10-10 12:32:34	支付完成时间，格式yyyy-MM-dd hh:mm:ss

# 业务响应

公共响应体如果美团企业版响应status不为成功（0）或参数异常（300），第三方平台需要再次给美团企业版推送支付结果。每隔5秒推送一次，最多重复推送六次。重复推送的时间点（以第一次推送的实际为起点）为5/10/15/20/25/30。

# 请求content示例

{
  "ts":1626333172,
  "method":"trade.third.pay.callback",
  "entId":100570,
  "tradeNo":1415570032678670389,
  "thirdPayOrderId":"1626333171",
  "payAmount":"17.90",
  "serviceFeeAmount":"0.32",
  "payTime":"2021-07-15 15:12:52"
}

# 响应成功示例

{
  "status":0,
  "msg":"成功",
  "data":null
}

# 2.3 退款接口

# 接口说明

名称	描述
功能	美团企业版交易平台向第三方平台发起退款，第三方平台返回退款流水号
HTTP方法	POST, application/x-www-form-urlencoded
请求方	美团企业版平台
响应方	第三方平台
url	第三方平台提供
method	trade.third.refund

# 公共参数

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

# 业务请求参数

名称	类型	是否必填	示例	说明
refundTradeNo	Long	是	393033370136698	退款交易号，唯一标识一次退款请求。第三方平台需要根据此流水号判断退款幂等性。
tradeNo	Long	是	345905477525602	交易号，唯一标示一次下单请求
refundAmount	String	是	12.32	退款金额（不包含服务费），单位元，两位小数。`订单可能多次退款，单次退款金额可能小订单金额，需要第三方平台支持部分退款。`
serviceFeeRefundAmount	String	否	0.32	退款服务费金额（空值表示没有服务费），单位元，两位小数。
tradeTime	String	是	2018-10-10 14:32:34	退款请求时间，格式yyyy-MM-dd hh:mm:ss

# 业务响应

名称	类型	是否必填	示例	说明
thirdRefundOrderId	String	是	1547608646457	第三方平台退款订单号。返回此单号，表示第三方平台受理退款成功，美团企业版将会执行退款流程，所以需要第三方平台保证退款的最终一致性。

# 请求content示例

{
  "ts":1626333187,
  "method":"trade.third.refund",
  "entId":100570,
  "tradeNo":1415570032678670389,
  "refundTradeNo":1415570100693504076,
  "refundAmount":"17.90",
  "serviceFeeRefundAmount":"0.32",
  "tradeTime":"2021-07-15 15:13:07"
}

# 响应密文示例

{
  "status":0,
  "msg":"成功",
  "data":"N_TbiN4dg93io4Drs26mPVX5of_SWqjdlnus99VVDd62xQEneMZMIJgDRzxYA3uI"
}

# 响应明文示例

{
  "status":0,
  "msg":"成功",
  "data":"{\"thirdRefundOrderId\": \"1626333187\"}"
}

# 2.4 支付状态查询接口

# 接口说明

下单成功后，支付状态查询接口需要保证能查询到订单的状态（支付成功|支付失败|待支付|），禁止返回"订单不存在"的错误响应

名称	描述
功能	美团企业版交易平台查询订单的支付状态，兜底轮训，避免第三方平台没有及时通知或通知处理异常
HTTP方法	POST
请求方	美团企业版平台
响应方	第三方渠道
uri	第三方渠道提供
method	trade.third.pay.query

# 公共参数

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

# 业务请求参数

名称	类型	是否必填	示例	说明
tradeNo	Long	是	393033370136698	交易号，请求下单时传入

# 业务响应

名称	类型	是否非空	说明
tradeNo	Long	是	交易号，请求下单时传入
thirdPayOrderId	String	是	第三方交易流水号
payStatus	Integer	是	支付状态 0 待支付 1 支付成功 2 支付失败
payTime	String	是	支付完成时间，yyyy-MM-dd HH:mm:ss
payAmount	String	是	支付金额(不包含服务费)，单位元
serviceFeeAmount	String	否	随单服务费（空值表示没有服务费），单位元，两位小数

# 请求content示例

{
  "ts":1626321392,
  "method":"trade.third.pay.query",
  "entId":100570,
  "tradeNo":715527163868704
}

# 响应密文示例

{
  "status":0,
  "msg":"成功",
  "data":"pJJZpovWbXXwHgDp_Bgsva5P1U7rcFH7TBwACFGO5i8BDnuL6ziIfDSMBxkMpmh7juXksh2WN2qTs9n1TiCFYt9f_soudDk94-Twn6kkJ8XVKKPFWXjxkAkFtcGSXZHboINKIMuoexWW_rtz7KdbcCSnTWEVHwKwV0IkTxY6ulM"
}

# 响应明文示例

{
  "status":0,
  "msg":"成功",
  "data":"{\"tradeNo\": 715527163868704, \"thirdPayOrderId\": \"1626266849\", \"payStatus\": \"1\", \"payTime\": \"2021-07-14 12:47:29\", \"payAmount\": \"16.9\",\"serviceFeeAmount\": \"0.32\"}"
}

# 3.【自测流程说明】

# 3.1 自测流程时序图

第三方平台对接时序图注意:测试环境端口只支持80,443,8080,8090,8805,8380

# 3.2 测试下单接口

# 接口说明

名称	描述
功能	第三方平台测试下单接口
HTTP方法	POST
请求方	第三方渠道
响应方	美团企业版平台
uri	$API_HOST/trade/standardThird/mock/test
method	trade.third.standard.mock

# 公共参数

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

# 业务请求参数

名称	类型	是否必填	示例	说明
amount	String	是	13.14	下单金额
action	String	是	create	下单接口必填create
extInfoMap	Map<String,Object>	否		标准三方定制额外参数和 2.1 下单接口 extInfoMap一致

# 业务响应

名称	类型	是否非空	说明
tradeNo	Long	是	美团企业版交易号
thirdPayUrl	String	是	第三方平台返回的支付页面url

# 请求content示例

{
  "amount":"1.0",
  "method":"trade.third.standard.mock",
  "entId":100570,
  "action":"create",
  "ts":1626421323,
  "extInfoMap":{
    "staffId":121
  }
}

# 响应示例

{
  "data": "{\"tradeNo\":1471391389072756785,\"thirdPayUrl\":\"https://xxxx\"}",
  "status": 0,
  "message": null
}

# 3.3 测试退款接口

# 接口说明

名称	描述
功能	第三方平台测试退款接口
HTTP方法	POST
请求方	第三方渠道
响应方	美团企业版平台
uri	$API_HOST/trade/standardThird/mock/test
method	trade.third.standard.mock

# 公共参数

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

# 业务请求参数

名称	类型	是否必填	示例	说明
amount	String	是	13.14	下单金额
action	String	是	refund	退款接口必填refund
tradeNo	Long	是	520131415926	美团企业版交易号

# 业务响应

名称	类型	是否非空	说明
tradeNo	Long	是	美团企业版交易号
refundTradeNo	Long	是	美团企业版退款交易号

# 请求content示例

{
  "method":"trade.third.standard.mock",
  "entId":100570,
  "action":"refund",
  "amount":"1.0",
  "tradeNo":"1415939859368906838",
  "ts":1626422333
}

# 响应示例

{
  "data": "{\"tradeNo\":1471391389072756785,\"refundTradeNo\":1415939859368906838}",
  "status": 0,
  "message": null
}

# 3.4 测试查询支付状态接口

# 接口说明

名称	描述
功能	第三方平台测试查询支付状态接口
HTTP方法	POST
请求方	第三方渠道
响应方	美团企业版平台
uri	$API_HOST/trade/standardThird/mock/test
method	trade.third.standard.mock

# 公共参数

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

# 业务请求参数

名称	类型	是否必填	示例	说明
tradeNo	Long	是	134	测试下单接口返回的美团企业版支付流水ID
action	String	是	query	查询接口必填query

# 业务响应

名称	类型	是否非空	说明
tradeNo	Long	是	交易号，请求下单时传入
thirdPayOrderId	String	是	第三方交易流水号
payStatus	Integer	是	支付状态 0 待支付 1 支付成功 2 支付失败
payTime	String	是	支付完成时间，yyyy-MM-dd HH:mm:ss
payAmount	String	是	支付金额，单位元

# 请求content示例

{
  "method":"trade.third.standard.mock",
  "entId":100570,
  "action":"query",
  "tradeNo":"1415939859368906838",
  "ts":1626421821
}

# 响应示例

{
  "data": "{\\\"tradeNo\\\":\\\"716130128561706\\\",\\\"thirdPayOrderId\\\":\\\"1626414057\\\",\\\"payStatus\\\":1,\\\"payTime\\\":\\\"2021-07-16 05:40:57\\\",\\\"payAmount\\\":\\\"27.3\\\",\\\"sqtChannelPayStatus\\\":\\\"SUCCESS\\\"}\"}",
  "status": 0,
  "message": null
}

# 3.5 自测结果验证

第三方平台企业自测完成后，提供以下测试场景的美团企业版支付流水ID给美团企业版研发人员进行验证：

下单成功未支付订单
支付成功订单
一次部分退款订单
二次部分退款订单
全额退款订单

← 第三方预算接入企业结算账单 →