# 六、支付分功能文档
# 阅读对象
对接刷脸+支付分业务的研发、产品、运营，需要有一定的API开发技术理解能力。
# 背景说明
支付分全称“微信支付分”，是一款以微信委托代扣为基础支付能力、以微信支付分为主要业务指标的支付服务产品。
支付分目前主要应用在免押租借、先享后付、智慧零售、免押速住等场景。当用户支付分达到商户设置的分数门栏时，即有机会获得先享受服务，后付款的权益。
刷脸支付分业务作为一种全新的体验模式，可以让用户在不用手机的情况下也能体验先享受、后付款的服务，真正做到了用户与手机全程“0接触”的目标。
# 接入指引
刷脸支付分业务，是通过刷脸的方式获取用户面容信息，并识别到用户身份，从而为用户开通并使用支付分的业务。商户只需在客户端安装我们指定的SDK即可通过刷脸的方式获取用户的支付分授权信息，然后从后台发起创建订单、查询订单、完结订单请求，从而完成交易过程。
刷脸支付分接入整体流程：
# 申请接入支付分
1. 申请接入
商户向wechatpay_scoreBD@tencent.com发送邮件接入申请，微信侧在3-5个工作日内进行评估并回复审核结果。申请需包含以下信息：
1）商户基本信息
2）商户简介
3）需要使用微信支付分的产品方案或业务场景描述（请标注“需人脸能力”)
4）商户联系方式
2. 签署协议
商户信息及业务场景审核通过后，微信侧向商户邮件发送协议模板，并完成协议的签署。
# 对接刷脸支付分
业务时序图：
sequenceDiagram
participant A as 商户 APP
participant B as 刷脸支付 SDK
participant D as 商户后台
participant C as 微信支付后台
note over A, C: Step 1 初始化刷脸支付 SDK
activate A
A ->> B: 初始化刷脸支付 SDK: initWxpayface()
activate B
B -->> A: 返回初始化结果
deactivate B
note over A, C: Step 2 获取刷脸支付调用凭证
A ->> B: 准备数据 getWxpayfaceRawdata()
activate B
B -->> A: 返回 Rawdata
deactivate B
A ->> D: 获取 authinfo，即刷脸支付调用凭证
activate D
D ->> C: get_wxpayface_authinfo(rawdata)
activate C
C -->> D: 返回 authinfo
deactivate C
D -->> A: 返回 authinfo
deactivate D
note over A,C: Step 3 发起刷脸，获取用户支付分状态与服务授权状态
A ->> B: 4. 刷脸查询支付分 getUserPayScoreStatus(订单号，service_id)
activate B
B ->> B: 人脸识别
B ->> C: 查询用户支付分状态与服务授权状态
activate C
C -->> B: 返回用户支付分状态与授权状态
deactivate C
alt 用户已开通支付分，且授权商户服务
B -->> A: 返回 open_id, 商户可创建支付分订单
else 用户未开通支付分，或未授权商户服务
B ->> B: 弹窗等待用户开通支付分或授权商户服务
B -->> C: 开通支付分或授权商户服务
activate C
C -->> B: 返回用户支付分状态与授权状态
deactivate C
alt 开通且授权成功
B -->> A: 返回 open_id, 商户可创建支付分订单
else 开通或授权失败
B -->> A: 失败，引导用户扫码支付
deactivate B
end
end
deactivate A
note over A,C: Step 5 商户创建支付分订单
activate A
A ->> D: 创建支付分订单
activate D
D ->> C: 创建支付分订单
activate C
C -->> D: 返回订单创建结果
deactivate C
D -->> A: 返回订单创建结果
deactivate D
note over A,C: Step 6 用户免押金使用商户服务
note over A,C: Step 7 服务完成, 商户完结支付分订单
A ->> D: 结算支付分订单
activate D
D ->> C: 结算支付分订单
activate C
C -->> D: 返回订单结算结果
deactivate C
D -->> A: 返回订单结算结果
deactivate D
deactivate A
# 1. 接入刷脸SDK
1.1 初始化刷脸支付 SDK：initWxpayface()
接口作用：对人脸SDK进行初始化
请求参数
除公共参数外，下方参数的代理设置可用于配置刷脸走商户内部代理。若不需要，则不用填写。
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| ip | 否 | string | HTTP代理IP或域名 |
| port | 否 | string | HTTP代理端口, 须为数字 |
| user | 否 | string | HTTP代理的用户名 |
| passwd | 否 | string | HTTP代理的密码 |
| proxy_type | 否 | int | 0:none; 1:HttpTunnel; 2:Socks5; 3:Http 2.12及以上 |
| tcp_port | 否 | string | TCP的代理端口，如果TCP代理与IP代理同一端口，则无需设置v2.12及以上 |
| perform_mode | 否 | string | NORMAL_PRFORM : 正常性能表现;LOW_PERFORM : 低性能表现默认为正常性能表现 v2.13及以上 |
返回参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| return_code | 是 | string | 错误码。公共定义见 公共错误码 |
| return_msg | 是 | string(128) | 对错误码的描述 |
请求示例
/**
* 初始化
*
*/
Map<String, String> m1 = new HashMap<>();
// m1.put("ip", "192.168.1.1"); //若没有代理,则不需要此行
// m1.put("port", "8888");//若没有代理,则不需要此行
// m1.put("user", mEtnUser.getText().toString());//若没有代理,则不需要此行
// m1.put("passwd", mEtnPassword.getText().toString());//若没有代理,则不需要此行
// m1.put("proxy_type", 1 ); //若没有代理,则不需要此行
// m1.put("perform_mode", "LOW_PERFORM");//低性能表现，默认关闭美颜等
WxPayFace.getInstance().initWxpayface(this, m1, new IWxPayfaceCallback() {
@Override
public void response(Map info) throws RemoteException {
if (info == null) {
showToast("调用返回为空, 请查看日志");
new RuntimeException("调用返回为空").printStackTrace();
return false;
}
String code = (String) info.get("return_code");
String msg = (String) info.get("return_msg");
showToast("初始化完成");
}
});
建议：
- 您可以自定义一个Application，然后在自定义Application的onCreate()中调用initPayFace()完成人脸识别模块的初始化 ；
- 您可以只在被调用人脸识别模块的activity的onCreate()中完成initPayFace()的调用。
注意：目前我们没有在initPayFace()中做app保活的自启措施，所以当您的应用在启动过程中遇到重启/更新的问题，您必须重新调用initPayFace()，相信我们会在下一个最新的版本中对initPayFace()做进一步的完善。
1.2 数据准备：getWxpayfaceRawdata()
接口作用：获取rawdata数据
返回参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| return_code | 是 | string | 错误码。公共定义见 公共错误码 |
| err_code | 否 | Integer | 可为空，二级错误码，公共定义见 二级错误码 |
| return_msg | 是 | string(128) | 对错误码的描述 |
| rawdata | 是 | string(2048) | 初始化数据。用于接口调用, 参见: get_wxpayface_authinfo: rawdata |
请求示例
/**
* 获取rawdata
*
*/
WxPayFace.getInstance().getWxpayfaceRawdata(new IWxPayfaceCallback() {
@Override
public void response(final Map info) throws RemoteException {
if (info == null) {
showToast("调用返回为空, 请查看日志");
new RuntimeException("调用返回为空").printStackTrace();
return false;
}
String code = (String) info.get("return_code");
String msg = (String) info.get("return_msg");
String rawdata = info.get("rawdata");
}
});
注意：请在初始化(initWxpayface)成功后获取数据(getWxpayfaceRawdata)
1.3 获取刷脸支付调用凭证
接口作用：获取调用凭证
接口地址：https://payapp.weixin.qq.com/face/get_wxpayface_authinfo
请求参数
除公共参数外，下方参数的代理设置可用于配置刷脸走商户内部代理。若不需要，则不用填写。
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| store_id | 是 | string(32) | 门店编号， 由商户定义， 各门店唯一。 |
| store_name | 是 | string(128) | 门店名称，由商户定义。（可用于展示） |
| device_id | 是 | string(32) | 终端设备编号，由商户定义。 |
| attach | 否 | string | 附加字段。字段格式使用Json |
| rawdata | 是 | string(2048) | 初始化数据。由微信人脸SDK的接口返回。获取方式参见：[获取数据 getWxpayfaceRawdata](#获取数据 getWxpayfaceRawdata)[获取数据 getWxpayfaceRawdata](#获取数据 getWxpayfaceRawdata) |
| appid | 是 | string(32) | 商户号绑定的公众号/小程序 appid |
| mch_id | 是 | string(32) | 商户号 |
| sub_appid | 否 | string(32) | 子商户绑定的公众号/小程序 appid(服务商模式) |
| sub_mch_id | 否 | string(32) | 子商户号(服务商模式) |
| now | 是 | int | 取当前时间，10位unix时间戳。 例如：1239878956 |
| version | 是 | string | 版本号。固定为1 |
| sign_type | 是 | string | 签名类型，目前支持HMAC-SHA256和MD5，默认为MD5 |
| nonce_str | 是 | string(32) | 随机字符串，不长于32位 |
| sign | 是 | string | 参数签名。详见微信支付签名算法 |
返回参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| return_code | 是 | string(16) | 错误码。公共定义见 公共错误码 |
| return_msg | 是 | string(128) | 对错误码的描述 |
| authinfo | 是 | string(4096) | SDK调用凭证。用于调用SDK的人脸识别接口。参见[人脸识别 getWxpayfaceCode](#人脸识别 getWxpayfaceCode) |
| expires_in | 否 | int | authinfo的有效时间, 单位秒。 例如: 3600在有效时间内, 对于同一台终端设备，相同的参数的前提下(如：相同的公众号、商户号、 门店编号等），可以用同一个authinfo，多次调用SDK的getWxpayfaceCode接口。 |
| nonce_str | 是 | string(32) | 随机字符串 |
| sign | 是 | string(32) | 响应结果签名 |
| appid | 是 | string(32) | 公众号 |
| mch_id | 否 | string(32) | 商户号 |
| sub_appid | 否 | string(32) | 子商户公众账号ID(服务商模式) |
| sub_mch_id | 是 | string(32) | 子商户号(服务商模式) |
请求示例
<return_code>SUCCESS</return_code>
<return_msg>请求成功</return_msg>
<nonce_str>Tivppi4UXAbgLxk8e1Sij76YdowOFFii</nonce_str>
<sign>PL0EUID6A7ICWNKHCSMQC0UIXOYNSE5B</sign>
<appid>wx31fdaErqR31</appid>
<mch_id>12345689</mch_id>
<authinfo>q3OPhFtQBf6KZGqmZhejKCRy5K/ch0kwS11YSsEj9XmUGqcsT2QPHt0Oa7xaCMCoSZTWMmShCo4dOiO5tU+OJEsvSxXzn5m3Nkh747tinNlbpJmVq1zOPj+FJNndkzanxoiAddO8p1EfrmUhJs/aNf0pDfrPoVfkAapK+ZY6blwyaDQ9bB7+KkZq29kObsXOZ3thg+bxP4RAqC0oxNS4JiyP0uA1Euzxtkc9lCTebloFied8stILrMehUKukeMGkZ1SzTyc8/HFHApzHahNPX6yD8ttzYnhe+IRMFJgpuTlIvEOYZUxenPXE1A5clrPvOBeJDszX/OvZl4fpYWPpXAcVQlw+gfYhblt+rT6ALMsD73w/rT4NRriQEEraC4Pfb5yua4qAqv4TVo04</authinfo>
<expires_in>7200</expires_in>
建议：
返回的接口凭证authinfo，可以在expires_in指定的有效期内，同一台机具上重复使用。
注意：这是一个后端调用接口,请在获取数据(getWxpayfaceRewdata)成功后获取调用凭证get_wxpayface_authinfo(rawdata)
# 2. 对接刷脸支付分
刷脸查询用户支付分状态：getUserPayScoreStatus()
请求参数
| 字段名 | 变量名 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
| 公众账号ID | appid | string（32） | 是 | 商户号绑定的公众号/小程序appid**示例值：**wx8888888888888888 |
| 商户号 | mch_id | string（32） | 是 | 微信支付分配给商户的商户号**示例值：**1900000109 |
| 商户订单号 | out_trade_no | string（32） | 是 | 商户系统内部服务订单号，要求此参数只能由数字、大小写字母_-|*组成，且在同一个商户号下唯一。必须与创建支付分订单时的 out_order_no **参数一致，否则影响笔数计算。****示例值：**2304203423948239423 |
| 接口调用凭证 | authinfo | string | 是 | 调用凭证。获取方式参见: 《get_wxpayface_authinfo》 |
| 商户签约单号 | payscore_out_request_no | string（64） | 是 | 商户签约单号，用于刷脸支付 SDK 调用支付分授权接口。在用户授权/解除授权成功时，支付分会携带此参数回调商户。支付分回调通知接口见支付分文档。**示例值：**1234323JKHDFE1243252 |
| 支付分服务ID | payscore_service_id | string（32） | 是 | 支付分 service_id，接入微信支付分时由微信支付分配。**示例值：**500001 |
| 是否请求 UnionId | ask_unionid | int | 否 | 是否需要生成用户的 UnionId；传入 1 为获取，不传或者传入 0 为不获取。只有传入 1，后续在使用 face_sid 请求后台接口时才能成功得到用户的 UnionId. |
返回参数
| 字段名 | 变量名 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
| 返回状态码 | return_code | string（16） | 是 | 错误码，枚举值：SUCCESS：用户已开通支付分并授权服务ERROR：人脸识别成功，但用户开通支付分失败，或授权服务失败USER_CANCEL：用户取消了识别或授权流程SCAN_PAYMENT：用户选择了扫码使用服务示例值：SUCCESS |
| 错误码 | err_code | int | 否 | 二级错误码 |
| 返回信息 | return_msg | string（128） | 否 | 对错误码的描述示例值： 如调用接口时必填的参数为空 |
| 用户标识 | openid | string（128） | 否 | 微信用户在商户对应appid下的唯一标识。openid（相当于用户身份），商户可凭此创建支付分订单。**示例值：**oUpF8uMuAJO_M2pxb1Q9zNjWeS6o |
| 用户子标识 | sub_openid | string（128） | 否 | 子商户号下的 openid （服务商模式）。**示例值：**oUpF8uMuAJO_M2pxb1Q9zNjWeS6o |
| 接口调用凭证 | face_sid | string | 是 | 终端设备识别用户成功后返回的凭证，商户可凭此获取用户 UnionId |
2.1 创建支付分订单
接口说明
适用对象：直连商户
请求URL：https://api.mch.weixin.qq.com/v3/payscore/serviceorder
请求方式：POST
接口规则：https://wechatpay-api.gitbook.io/wechatpay-api-v3
path 指该参数为路径参数
query 指该参数需在请求URL传参
body 指该参数需在请求JSON传参
请求参数
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 商户服务订单号 | out_order_no | string[1,32] | 是 | body 商户系统内部服务订单号（不是交易单号），要求此参数只能由数字、大小写字母_-|*组成，且在同一个商户号下唯一。详见[商户订单号]。 示例值：1234323JKHDFE1243252 |
| 公众账号ID | appid | string[1,32] | 是 | body微信公众平台分配的与传入的商户号建立了支付绑定关系的appid，可在公众平台查看绑定关系，此参数需在本系统先进行配置。 示例值：wxd678efh567hg6787 |
| 服务ID | service_id | string[1,32] | 是 | body该服务ID有本接口对应产品的权限。 示例值：500001 |
| 服务信息 | service_introduction | string[1,20] | 是 | body 服务信息，用于介绍本订单所提供的服务 ，当参数长度超过20个字符时，报错处理。 示例值：某某酒店 |
| 后付费项目 | post_payments | array | 否 | body后付费项目列表，最多包含100条付费项目。 如果传入，用户侧则显示此参数。 |
| 后付费商户优惠 | post_discounts | array | 否 | body后付费商户优惠列表，最多包含30条商户优惠。 如果传入，用户侧则显示此参数。 |
| 服务时间段 | time_range | object | 是 | body服务时间范围 |
| 服务位置 | location | object | 否 | body服务位置信息 如果传入，用户侧则显示此参数。 |
| 订单风险金 | risk_fund | object | 是 | body订单风险金信息 |
| 商户数据包 | attach | string[1,256] | 否 | body商户数据包可存放本订单所需信息，需要先urlencode后传入。 当商户数据包总长度超出256字符时，报错处理。 示例值：Easdfowealsdkjfnlaksjdlfkwqoi&wl3l2sald |
| 商户回调地址 | notify_url | string[1,255] | 是 | body商户接收用户确认订单和付款成功回调通知的地址。 示例值：https://api.test.com |
| 用户标识 | openid | string[1,128] | 条件选填 | body微信用户在商户对应appid下的唯一标识。 免确认订单：必填 需确认订单：不填 示例值：oUpF8uMuAJO_M2pxb1Q9zNjWeS6o |
| 是否需要用户确认 | need_user_confirm | bool | 是 | body枚举值： false：免确认订单 true：需确认订单 示例值：true |
请求示例
{
"out_order_no": "1234323JKHDFE1243252",
"appid": "wxd678efh567hg6787",
"service_id": "500001",
"service_introduction": "某某酒店",
"post_payments": [
{
"name": "就餐费用服务费",
"amount": 4000,
"description": "就餐人均100元服务费：100/小时",
"count": 1
}
],
"post_discounts": [
{
"name": "满20减1元",
"description": "不与其他优惠叠加"
}
],
"time_range": {
"start_time": "20091225091010",
"end_time": "20091225121010"
},
"location": {
"start_location": "嗨客时尚主题展餐厅",
"end_location": "嗨客时尚主题展餐厅"
},
"risk_fund": {
"name": "ESTIMATE_ORDER_COST",
"amount": 10000,
"description": "就餐的预估费用"
},
"attach": "Easdfowealsdkjfnlaksjdlfkwqoi&wl3l2sald",
"notify_url": "https://api.test.com",
"openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
"need_user_confirm": true,
}
返回参数
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 公众账号ID | appid | string[1,32] | 是 | 调用接口提交的公众账号ID。 示例值：wxd678efh567hg6787 |
| 商户号 | mchid | string[1,32] | 是 | 调用接口提交的商户号。 示例值：1230000109 |
| 商户服务订单号 | out_order_no | string[1,32] | 是 | 调用接口提交的商户服务订单号。 示例值：1234323JKHDFE1243252 |
| 服务ID | service_id | string[1,32] | 是 | 调用该接口提交的服务ID。 示例值：500001 |
| 服务信息 | service_introduction | string[1,20] | 是 | 服务信息，用于介绍本订单所提供的服务。 示例值：某某酒店 |
| 服务订单状态 | state | string[1,32] | 是 | 表示当前单据状态。枚举值： 1、CREATED：商户已创建服务订单 2、DOING：服务订单进行中 3、DONE：服务订单完成 4、REVOKED：商户取消服务订单 5、EXPIRED：服务订单已失效 示例值：CREATED |
| 订单状态说明 | state_description | string (32) | 否 | 对服务订单"进行中"状态的附加说明。 1、USER_CONFIRM：用户确认 2、MCH_COMPLETE：商户完结 示例值：MCH_COMPLETE |
| 后付费项目 | post_payments | array | 否 | 后付费项目列表，最多包含100条付费项目。 如果传入，用户侧则显示此参数。 |
| 后付费商户优惠 | post_discounts | array | 否 | 后付费商户优惠，最多包含30条付费项目。 如果传入，用户侧则显示此参数。 |
| 订单风险金 | risk_fund | object | 是 | 订单风险金信息 |
| 服务时间段 | time_range | object | 是 | 服务时间范围 |
| 服务位置 | location | object | 否 | 服务使用信息。 如果传入，用户侧则显示此参数。 |
| 商户数据包 | attach | string[1,256] | 否 | 商户数据包,可存放本订单所需信息，需要先urlencode后传入，总长度不大于256字符,超出报错处理。 示例值：Easdfowealsdkjfnlaksjdlfkwqoi&wl3l2sald |
| 商户回调地址 | notify_url | string[1,255] | 否 | 商户接收用户确认订单或扣款成功回调通知的地址。 示例值：https://api.test.com |
| 微信支付服务订单号 | order_id | string[1,64] | 是 | 微信支付服务订单号，每个微信支付服务订单号与商户号下对应的商户服务订单号一一对应。 示例值：15646546545165651651 |
| 跳转微信侧小程序订单数据 | package | string[1,300] | 是 | 用于跳转到微信侧小程序订单数据,跳转到微信侧小程序传入。该数据1小时内有效。 示例值：DJIOSQPYWDxsjdldeuwhdodwxasd_dDiodnwjh9we |
返回示例
{
"appid": "wxd678efh567hg6787",
"mchid": "1230000109",
"out_order_no": "1234323JKHDFE1243252",
"service_id": "500001",
"service_introduction": "某某酒店",
"state": "CREATED",
"state_description": "MCH_COMPLETE",
"post_payments": [
{
"name": "就餐费用服务费",
"amount": 4000,
"description": "就餐人均100元服务费：100/小时",
"count": 1
}
],
"post_discounts": [
{
"name": "满20减1元",
"description": "不与其他优惠叠加"
}
],
"risk_fund": {
"name": " ESTIMATE_ORDER_COST",
"amount": 10000,
"description": "就餐的预估费用"
},
"time_range": {
"start_time": "20091225091010",
"end_time": "20091225121010"
},
"location": {
"start_location": "嗨客时尚主题展餐厅",
"end_location": "嗨客时尚主题展餐厅"
},
"attach": "Easdfowealsdkjfnlaksjdlfkwqoi&wl3l2sald",
"notify_url": "https://api.test.com",
"order_id": "15646546545165651651",
"package": " DJIOSQPYWDxsjdldeuwhdodwxasd_dDiodnwjh9we "
}
错误码
| 状态码 | 错误码 | 描述 | 解决方案 |
|---|---|---|---|
| 500 | SYSTEM_ERROR | 系统错误 | 5开头的状态码都为系统问题，请使用相同参数稍后重新调用 |
| 400 | PARAM_ERROR | 参数错误 | 根据错误提示，传入正确参数 |
| 403 | NO_AUTH | 商户信息不合法 | 登录商户平台核对，传入正确信息 |
| 429 | FREQUENCY_LIMITED | 频率超限 | 请求量不要超过接口调用频率限制 |
| 400 | INVALID_REQUEST | 请求参数符合参数格式，但不符合业务规则 | 请确认相同单号是否使用了不同的参数 |
| 404 | ORDER_NOT_ EXIST | 订单不存在 | 确认入参，传入正确单据 |
| 400 | INVALID_ORDER_STATE | 单据状态错误 | 确认操作是否符合流程 |
| 400 | ORDER_CANCELED | 单据已取消 | 当前状态无需操作 |
| 400 | ORDER_DONE | 订单已完成 | 当前状态无需操作 |
2.2 完结支付分订单
完结微信支付分订单。用户使用完服务完成后，商户可通过此接口完结订单。
特别说明
完结接口调用成功后，微信支付将自动发起免密代扣。 若扣款失败，微信支付将自动再次发起免密代扣（按照一定频次），直到扣成功为止。
接口说明
适用对象：直连商户
请求URL：https://api.mch.weixin.qq.com/v3/payscore/serviceorder/{out_order_no}/complete
请求方式：POST
前置条件：服务订单状态为“进行中”且订单状态说明需为[USER_CONFIRM:用户确认]
接口规则：https://wechatpay-api.gitbook.io/wechatpay-api-v3
path 指该参数为路径参数
query 指该参数需在请求URL传参
body 指该参数需在请求JSON传参
请求参数
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 商户服务订单号 | out_order_no | string[1,32] | 是 | path 商户系统内部服务订单号（不是交易单号），与创建订单时一致 示例值：1234323JKHDFE1243252 |
| 公众账号ID | appid | string[1,32] | 是 | body 微信公众平台分配的与传入的商户号建立了支付绑定关系的appid，可在公众平台查看绑定关系，此参数需在本系统先进行配置。 示例值：wxd678efh567hg6787 |
| 服务ID | service_id | string[1,32] | 是 | body 服务订单的主键，唯一定义此资源的标识 示例值：500001 |
| 后付费项目 | post_payments | array | 是 | body 后付费项目列表，最多包含100条付费项目 |
| 后付费商户优惠 | post_discounts | array | 否 | body 后付费商户优惠列表，最多包含30条商户优惠 如果传入，用户侧则显示此参数 |
| 总金额 | total_amount | int64 | 是 | body 1、金额：数字，必须≥0（单位：分），只能为整数，详见支付金额。 2、总金额 =（完结付费项目1…+完结付费项目n）-（完结商户优惠项目1…+完结商户优惠项目n） 3、总金额上限 1）【评估不通过：交押金】模式：总金额≤创单时填写的“订单风险金额” 2）【评估不通过：拒绝】模式：总金额≤“每个服务ID的风险金额上限” 示例值：50000 |
| 服务时间段 | time_range | object | 条件选填 | body 服务时间范围，创建订单未填写服务结束时间，则完结的时候，服务结束时间必填 如果传入，用户侧则显示此参数。 |
| 服务位置 | location | object | 否 | body 服务位置 如果传入，用户侧则显示此参数。 |
| 微信支付服务分账标记 | profit_sharing | bool | 否 | body 完结订单分账接口标记。分账开通流程，详见 false：不分账，默认：false true：分账。 示例值：false |
| 订单优惠标记 | goods_tag | string（32） | 否 | body 订单优惠标记，代金券或立减金优惠的参数，说明详见代金券或立减金优惠 示例值：goods_tag |
请求示例
{
"appid": "wxd678efh567hg6787",
"service_id": "500001",
"post_payments": [
{
"name": "就餐费用服务费",
"amount": 4000,
"description": "就餐人均100元服务费：100/小时",
"count": 1
}
],
"post_discounts":[
{
"name": "满20减1元",
"description": "不与其他优惠叠加",
"amount": 4000
}
],
"total_amount": 3900,
"time_range": {
"start_time": "20091225091010",
"end_time": "20091225121010"
},
"location": {
"end_location": "嗨客时尚主题展餐厅"
},
"profit_sharing": false
}
返回参数
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 公众账号ID | appid | string[1,32] | 是 | 调用接口提交的公众账号ID 示例值：wxd678efh567hg6787 |
| 商户号 | mchid | string[1,32] | 是 | 调用接口提交的商户号 示例值：1230000109 |
| 商户服务订单号 | out_order_no | string[1,32] | 是 | 调用接口提交的商户服务订单号 示例值：1234323JKHDFE1243252 |
| 服务ID | service_id | string[1,32] | 是 | 调用该接口提交的服务ID 示例值：500001 |
| 服务信息 | service_introduction | string[1,20] | 是 | 服务信息，用于介绍本订单所提供的服务 示例值：某某酒店 |
| 服务订单状态 | state | string[1,32] | 是 | 表示当前单据状态。 1、CREATED：商户已创建服务订单 2、DOING：服务订单进行中 3、DONE：服务订单完成 4、REVOKED：商户取消服务订单 5、EXPIRED：服务订单已失效，"商户已创建服务订单"状态超过30天未变动，则订单失效 示例值：CREATED |
| 订单状态说明 | state_description | string[1,32] | 否 | 对服务订单"进行中"状态的附加说明 USER_CONFIRM：用户确认 MCH_COMPLETE：商户完结 示例值：MCH_COMPLETE |
| 商户收款总金额 | total_amount | int64 | 是 | 总金额，大于等于0的数字，单位为分，只能为整数，详见支付金额。 此参数需满足：总金额=后付费项目金额之和-后付费商户优惠项目金额之和，且小于等于订单风险金额。取消订单时，该字段必须为0。 示例值：40000 |
| 后付费项目 | post_payments | array | 是 | 后付费项目列表，最多包含100条付费项目 |
| 后付费商户优惠 | post_discounts | array | 否 | 后付费商户优惠，最多包含30条付费项目； 如果传入，用户侧则显示此参数 |
| 订单风险金 | risk_fund | object | 是 | 订单风险金信息 |
| 服务时间段 | time_range | object | 否 | 服务时间范围; 如果传入，用户侧则显示此参数 |
| 服务位置 | location | object | 否 | 服务使用信息； 如果传入，用户侧则显示此参数 |
| 微信支付服务订单号 | order_id | string[1,64] | 是 | 微信支付服务订单号，每个微信支付服务订单号与商户号下对应的商户服务订单号一一对应 示例值：15646546545165651651 |
| 是否需要收款 | need_collection | bool | 否 | true：微信支付分代收款 false：无需微信支付分代收款 示例值：true |
返回示例
{
"appid": "wxd678efh567hg6787",
"mchid": "1230000109",
"out_order_no": "1234323JKHDFE1243252",
"service_id": "500001",
"service_introduction": "某某酒店",
"state": "DOING",
"state_description": "",
"total_amount": 3900,
"post_payments": [
{
"name": "就餐费用服务费",
"amount": 1,
"description": "就餐人均100元服务费：100/小时",
"count": 1
}
],
"post_discounts": [
{
"name": "满20减1元",
"description": "不与其他优惠叠加",
"amount": 1
}
],
"risk_fund": {
"name": "ESTIMATE_ORDER_COST",
"amount": 4000,
"description": "就餐的预估费用"
},
"time_range": {
"start_time": "20091225091010",
"end_time": "20091225121010"
},
"location": {
"start_location": "嗨客时尚主题展餐厅",
"end_location": "嗨客时尚主题展餐厅"
},
"order_id": "15646546545165651651",
"need_collection": true
}
错误码
| 状态码 | 错误码 | 描述 | 解决方案 |
|---|---|---|---|
| 500 | SYSTEM_ERROR | 系统错误 | 5开头的状态码都为系统问题，请使用相同参数稍后重新调用 |
| 400 | PARAM_ERROR | 参数错误 | 根据错误提示，传入正确参数 |
| 403 | NO_AUTH | 商户信息不合法 | 登录商户平台核对，传入正确信息 |
| 429 | FREQUENCY_LIMITED | 频率超限 | 请求量不要超过接口调用频率限制 |
| 400 | INVALID_REQUEST | 请求参数符合参数格式，但不符合业务规则 | 请确认相同单号是否使用了不同的参数 |
| 404 | ORDER_NOT_ EXIST | 订单不存在 | 确认入参，传入正确单据 |
| 400 | INVALID_ORDER_STATE | 单据状态错误 | 确认操作是否符合流程 |
| 400 | ORDER_CANCELED | 单据已取消 | 当前状态无需操作 |
| 400 | ORDER_DONE | 订单已完成 | 当前状态无需操作 |
2.3 同步服务订单信息
由于收款商户进行的某些“线下操作”会导致微信支付侧的订单状态与实际情况不符。例如，用户通过线下付款的方式已经完成支付，而微信支付侧并未支付成功，此时可能导致用户重复支付。因此商户需要通过订单同步接口将订单状态同步给微信支付，修改订单在微信支付系统中的状态。
接口说明
适用对象：直连商户
请求URL： https://api.mch.weixin.qq.com/v3/payscore/serviceorder/{out_order_no}/sync
请求方式：POST
接口规则：https://wechatpay-api.gitbook.io/wechatpay-api-v3
前提条件：同步商户渠道收款成功信息时，即场景类型=“Order_Paid”，订单的状态需为[MCH_COMPLETE:商户完结订单]
path 指该参数为路径参数
query 指该参数需在请求URL传参
body 指该参数需在请求JSON传参
请求参数
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 商户服务订单号 | out_order_no | string[1,32] | 是 | path 商户系统内部订单号（不是交易单号），要求此参数只能由数字、大小写字母_-|*组成，且在同一个商户号下唯一，详见「商户订单号」，需要和创建订单的商户服务订单号一致。 示例值：1234323JKHDFE1243252 |
| 公众账号ID | appid | string[1,32] | 是 | body 微信公众平台分配的与传入的商户号建立了支付绑定关系的appid，可在公众平台查看绑定关系。 此参数需在本系统先进行配置，并与创建订单时的appid保持一致。 示例值：wxd678efh567hg6787 |
| 服务ID | service_id | string[1,32] | 是 | body 该服务ID有本接口对应产品的权限，需要与创建订单时保持一致。 示例值：500001 |
| 场景类型 | type | string[1,32] | 是 | body 场景类型为“Order_Paid”，字符串表示“订单收款成功” 。 示例值：Order_Paid |
| 内容信息详情 | detail | object | 否 | body 场景类型为Order_Paid时，为必填项。 |
请求示例
{
"appid": "wxd678efh567hg6787",
"service_id": "500001",
"type": "Order_Paid",
"detail": {
"paid_time": "20091225091210"
}
}
返回参数
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 公众账号ID | appid | string[1,32] | 是 | 调用接口提交的公众账号ID。 示例值：wxd678efh567hg6787 |
| 商户号 | mchid | string[1,32] | 是 | 调用接口提交的商户号。 示例值：1230000109 |
| 商户服务订单号 | out_order_no | string[1,32] | 是 | 调用接口提交的商户服务订单号。 示例值：1234323JKHDFE1243252 |
| 服务ID | service_id | string[1,32] | 是 | 调用该接口提交的服务ID。 示例值：500001 |
| 服务信息 | service_introduction | string[1,20] | 是 | 服务信息，用于介绍本订单所提供的服务。 示例值：某某酒店 |
| 服务订单状态 | state | string[1,32] | 是 | 表示当前单据状态。枚举值： CREATED：商户已创建服务订单 DOING：服务订单进行中 DONE：服务订单完成 REVOKED：商户取消服务订单 EXPIRED：服务订单已失效，"商户已创建服务订单"状态超过30天未变动，则订单失效 示例值：CREATED |
| 订单状态说明 | state_description | string[1,32] | 否 | 对服务订单"进行中"状态的附加说明。枚举值： USER_CONFIRM：用户确认 MCH_COMPLETE：商户完结 示例值：MCH_COMPLETE |
| 商户收款总金额 | total_amount | int64 | 否 | 总金额，大于等于0的数字，单位为分，只能为整数，详见支付金额。 此参数需满足：总金额=后付费项目金额之和-后付费商户优惠项目金额之和，且小于等于订单风险金额。取消订单时，该字段必须为0。 示例值：40000 |
| 后付费项目 | post_payments | array | 否 | 后付费项目列表，最多包含100条付费项目。 |
| 后付费商户优惠 | post_discounts | array | 否 | 后付费商户优惠，最多包含30条付费项目。 |
| 订单风险金 | risk_fund | object | 否 | 订单风险金信息 |
| 服务时间段 | time_range | object | 否 | 服务时间范围 |
| 服务位置 | location | object | 否 | 服务使用信息 |
| 商户数据包 | attach | string[1,256] | 否 | 商户数据包，可存放本订单所需信息，需要先urlencode后传入，总长度不大于256字符，超出报错处理。 示例值：Easdfowealsdkjfnlaksjdlfkwqoi&wl3l2sald |
| 商户回调地址 | notify_url | string[1,255] | 否 | 商户接收用户确认订单或扣款成功回调通知的地址。 示例值：https://api.test.com |
| 微信支付服务订单号 | order_id | string[1,64] | 是 | 微信支付服务订单号，每个微信支付服务订单号与商户号下对应的商户服务订单号一一对应。 示例值：15646546545165651651 |
| 是否需要收款 | need_collection | bool | 否 | true：微信支付分代收款 false：无需微信支付分代收款 示例值：true |
| 收款信息 | collection | object | 否 | 收款信息 |
返回示例
{
"appid": "wxd678efh567hg6787",
"mchid": "1230000109",
"service_id": "500001",
"out_order_no": "1234323JKHDFE1243252",
"service_introduction": "某某酒店",
"state": "CREATED",
"state_description": "MCH_COMPLETE",
"total_amount": 3900,
"post_payments": [
{
"name": "就餐费用服务费",
"amount": 4000,
"description": "就餐人均100元服务费：100/小时",
"count": 1
}
],
"post_discounts": [
{
"name": "满20减1元",
"description": "不与其他优惠叠加",
"amount": 100
}
],
"risk_fund": {
"name": "ESTIMATE_ORDER_COST",
"amount": 10000,
"description": "就餐的预估费用"
},
"time_range": {
"start_time": "20091225091010",
"end_time": "20091225121010"
},
"location": {
"start_location": "嗨客时尚主题展餐厅",
"end_location": "嗨客时尚主题展餐厅"
},
"attach": "Easdfowealsdkjfnlaksjdlfkwqoi&wl3l2sald",
"notify_url": "https://api.test.com",
"order_id": "15646546545165651651",
"need_collection": true,
"collection": {
"state": "USER_PAID",
"total_amount": 3900,
"paying_amount": 0,
"paid_amount": 3900,
"details": [
{
"amount": 10000,
"paid_type": "NEWTON",
"paid_time": "20091225091210",
"transaction_id ": "15646546545165651651"
}
]
}
}
错误码
| 状态码 | 错误码 | 描述 | 解决方案 |
|---|---|---|---|
| 500 | SYSTEM_ERROR | 系统错误 | 5开头的状态码都为系统问题，请使用相同参数稍后重新调用 |
| 400 | PARAM_ERROR | 参数错误 | 根据错误提示，传入正确参数 |
| 403 | NO_AUTH | 商户信息不合法 | 登录商户平台核对，传入正确信息 |
| 429 | FREQUENCY_LIMITED | 频率超限 | 请求量不要超过接口调用频率限制 |
| 400 | INVALID_REQUEST | 请求参数符合参数格式，但不符合业务规则 | 请确认相同单号是否使用了不同的参数 |
| 404 | ORDER_NOT_ EXIST | 订单不存在 | 确认入参，传入正确单据 |
| 400 | INVALID_ORDER_STATE | 单据状态错误 | 确认操作是否符合流程 |
| 400 | ORDER_CANCELED | 单据已取消 | 当前状态无需操作 |
| 400 | ORDER_DONE | 订单已完成 | 当前状态无需操作 |
# 3. 获取用户Unionid
GET /v3/facemch/users/{face_sid}
商户可以根据face_sid查询用户UnionId。
请求参数
| 变量名 | 所处位置 | 数据类型 | 必填 | 限制条件 | 描述 | 示例 |
|---|---|---|---|---|---|---|
| face_sid | path | string | true | 终端设备识别用户成功后返回的凭证,getWxpayfaceUserInfo接口返回的token字段 | aabbccdd12345 | |
| info_type | query | string | true | 标识本次请求获取的信息类型 | ASK_UNIONID:获取用户union_id | |
| appid | query | string | true | 微信分配的公众账号ID | wx2b029c08a6233333 | |
| sub_mchid | query | string | false | 微信支付分配的子商户号，服务商模式下必填 | 123456789 | |
| sub_appid | query | string | false | 微信分配的子商户公众账号ID | wx2b029c08a6255555 |
返回结果
| 状态码 | 含义 | 描述 | 数据类型 |
|---|---|---|---|
| 200 | OK | 处理成功 | JSON |
应答样例
200 Response
{
"union_id": "abcdefg111"
}
# 方案验收
1. 产品方案验收，需提供以下相关信息：
- 商户侧业务全流程的录屏
- 商户提供APP（包括IOS和安卓）、小程序或h5的验收环境，微信侧将在验收环境内进行验收确认。
2. 确认灰度时间并在约定时间灰度上线
3. 验收完成后微信侧即完成支付分配置，产品正式上线。
邮件审核
请将邮件发送至以下邮箱： wxfacepay_help@tencent.com