完结速住订单
接口说明
| 接口url | https://api.mch.weixin.qq.com/wxv/finishhotelbill |
|---|---|
请求方式 |
POST |
传输格式 |
XML |
注意事项
- 当返回错误码为“SYSTEMERROR”时，请不要更换商户订单号，一定要使用原商户订单号重试，否则可能造成重复支付等资金风险。
- XML具有可扩展性，因此返回参数可能会有新增，而且顺序可能不完全遵循此文档规范，如果在解析回包的时候发生错误，请商户务必不要换单重试，请商户联系客服确认付款情况。如果有新回包字段，会更新到此API文档中。
- 因为错误代码字段err_code的值后续可能会增加，所以商户如果遇到回包返回新的错误码，请商户务必不要换单重试，请商户联系客服确认付款情况。如果有新的错误码，会更新到此API文档中。
- 错误代码描述字段err_code_des只供人工定位问题时做参考，系统实现时请不要依赖这个字段来做自动化处理。
是否需要证书
是，详见证书说明
完结订单场景
| 是否入住 | 实际离店时间 | 比较 | 预计离店时间 | 延迟退房费 | 取消费用 | 总金额 | 场景 |
|---|---|---|---|---|---|---|---|
| TRUE | 必填 | > | 选填 | 不允许填 | 房费+其他费用+赔偿金金额+延迟退房费用 | 延期离店 | |
| = | 不允许填 | 房费+其他费用+赔偿金金额 | 正常离店 | ||||
| < | 房费+其他费用+赔偿金金额 | 提前离店 | |||||
| FALSE | 不允许填 | 不允许填 | 必填 | 取消费用 | 未入住 |
前置条件
用户确认使用业务后
请求参数
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 接口版本号 | version | 是 | String(32) | 1.0 | 接口版本号，默认值1.0 |
| 公众账号ID | appid | 是 | String(32) | wxd678efh567hg6787 | 微信公众平台分配的与传入的商户号建立了支付绑定关系的appid，可在公众平台查看绑定关系. 需要在本系统先进行配置. 需要与创建订单时保持一致. |
| 商户号 | mch_id | 是 | String(32) | 1230000109 | 微信支付分配的商户号 需要在本系统先进行配置. 需要与创建订单时保持一致. |
| 随机字符串 | nonce_str | 是 | String(32) | ibuaiVcKdpRxkhJA | 随机字符串，长度要求在32位以内。推荐随机数生成算法 |
| 签名 | sign | 是 | String(128) | 029B52F67573D7E3BE74904BF9AEA | 通过签名算法计算得出的签名值，详见签名生成算法 |
| 签名类型 | sign_type | 是 | String(32) | HMAC-SHA256 | 签名类型，仅支持HMAC-SHA256 |
| 商户服务订单号 | out_order_no | 是 | String(32) | 1234323JKHDFE1243252 | 商户系统内部订单号，要求32个字符内，只能是数字、大小写字母_-|* 且在同一个商户号下唯一。详见商户订单号 |
| 服务ID | service_id | 是 | String(32) | 该服务ID有本接口对应产品的权限 需要与创建订单时保持一致. | |
| 是否入住 | checked_in | 是 | Bool | TRUE | TRUE -是，FALSE -否 |
| 实际离店时间 | real_end_time | 否 | String(14) | 20091225091010 | 【是否入住】为"TRUE"时必填,为"FALSE"时不允许填写 用户实际离店时间，格式为支持两种格式:yyyyMMddHHmmss和yyyyMMdd，如2009年12月25日9点10分10秒表示为20091225091010或者20091225.传入20091225默认时间为2009年12月25日23点59分59秒 |
| 其他费用金额 | other_fee | 如需填写，二者必须一起填写 | int | 10000 | 单位：分 必须>0,传入则代表需要扣取其他金额. 传0报错处理 |
| 其他费用说明 | other_fee_desc | String(200) | 早餐2份，每份50元 | 支持200个字符，按照字符计算 超过长度报错处理 | |
| 取消费用 | cancel_fee | 否 | int | 10000 | 单位：分，必须>=0, 且小于等于创建闪住订单传入的房费 当创建闪住订单传入的取消规则标签等于“FREE”时，取消费用不能填 |
| 赔偿金费用 | compensation_fee | 如需填写，二者必须一起填写 | int | 6000 | 【是否入住】为"TRUE"可选填 【是否入住】为"FALSE"时不允许填写 单位：分 必须>0 传入表示需要扣赔偿金 传0报错处理 【是否入住】为"TRUE"可选填 【是否入住】为"FALSE"时不允许填写 |
| 赔偿金说明 | compensation_fee_desc | String(30) | 打破房间杯子一个 | 支持30个字符，按照字符计算. 超过长度报错处理 | |
| 房费 | room_rate | 否 | int | 5000 |
单位：分 必须>=0, 且小于创建闪住订单传入的房费 【是否入住】为"TRUE"且【实际离店时间】小于【预定离店时间】时可选填. 【是否入住】为"FALSE"时不允许填写 传入后总金额的房费以此为准 |
| 延迟退房费用 | overdue_fine | 如需填写，二者必须一起填写 | int | 5000 | 单位：分 必须>0,传0报错返回 【是否入住】为"TRUE"且【实际离店时间】大于【预定离店时间】时可选填. 【是否入住】为"FALSE"时不允许填写 传入表示需要扣延迟退房费 |
| 延迟退房说明 | overdue_fine_desc | String(30) | 延迟退房2小时，增加50元房费 | 不超过30个字符，用来说明具体的一些扣费说明和解释。 超过长度报错处理 | |
| 总金额 | total_amount | 是 | int | 40000 | 总金额,单位:分 不能超过创建订单时候的押金金额. 当: 1.【是否入住】为"FALSE"或; 2.【是否入住】为"TRUE"且【实际离店时间】小于【预定离店时间】 时, 【总金额】需要等于【取消费用】, 【其他费用】, 【赔偿金费用】之和; 当: 1.【是否入住】为"TRUE"且 2.【实际离店时间】大于【预定离店时间】时, 【总金额】需要等于【房费】, 【其他费用金额】, 【赔偿金金额】以及【延迟退房费】之和 当 1.【是否入住】为"TRUE"且 2.【实际离店时间】等于【预定离店时间】时, 【总金额】需要等于【房费】, 【其他费用金额】以及【赔偿金金额】之和 |
| 完结凭证 | finish_ticket | 是 | String(512) | 用于完结订单时传入,确保订单完结时数据完整. 需要与创建订单时保持一致.需对字段再做处理。 （注意：该字段可通过查询订单或者用户确认使用服务回调里获取finish_ticket，finish_ticket是支付分用来校验的参数，商户不可自定义） |
|
| 分账标识 | profit_sharing | 是 | String(16) | Y | Y-是，需要分账 N-否，不分账 字母要求大写，不传默认不分账 |
返回参数
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 返回状态码 | return_code | 是 | String(16) | SUCCESS | SUCCESS/FAIL 此字段是通信标识，非业务标识，是否成功需要查看result_code来判断 |
| 返回结果 | return_msg | 否 | String(128) | 签名失败 | 返回信息，如非空，为错误原因，如签名失败，参数格式校验错误 |
以下字段在return_code为SUCCESS的时候有返回
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 签名 | sign | 是 | String(128) | 029B52F67573D7E3BE74904BF9A | 通过签名算法计算得出的签名值，详见签名生成算法 |
| 随机字符串 | nonce_str | 是 | String(32) | ibuaiVcKdpRxkhJA | 随机字符串，长度要求在32位以内。推荐随机数生成算法 |
| 业务结果 | result_code | 是 | String(16) | SUCCESS | SUCCESS/FAIL 完结成功返回SUCCESS,否则返回FAIL. FAIL情况需要根据err_code进行不同处理. |
| 错误代码 | err_code | 否 | String(32) | SYSTEMERROR | 错误码，详见错误码说明 |
| 错误描述 | err_code_des | 否 | String(128) | 系统错误 | 错误信息描述 |
| 公众账号ID | appid | 是 | String(32) | wxd678efh567hg6787 | 调用接口提交的公众账号ID |
| 商户号 | mch_id | 是 | String(32) | 1230000109 | 微信支付分配的商户号 |
| 商户服务订单号 | out_order_no | 是 | String(32) | 1234323JKHDFE1243252 | 调用接口提交的商户服务订单号 |
| 服务ID | service_id | 是 | String(32) | 调用该接口提交的服务ID |
以下字段当return_code、result_code都为SUCCESS时有返回
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 微信支付服务订单号 | order_id | 是 | String(128) | 微信支付服务订单号 每个微信支付服务订单号与商户号下对应的商户服务订单号一一对应 |
错误码
| 名称 | 描述 | 原因 | 解决方案 |
|---|---|---|---|
| SYSTEMERROR | 系统错误 | 系统超时 | 系统异常，请使用相同参数稍后重新调用 |
| PARAM_ERROR | 参数错误 | 请求参数不合法 | 请使用正确的参数重新调用 |
| INVALID_REQUEST | 无效的请求 | 商户没有接口权限 重入情况下参数不一致 | 请申请接口权限 请确认相同单号是否使用了不同的参数 |
| CANCELED | 单据已撤销 | 已撤销单据不可以完结 | 确认入参,传入正确单据 |
| ORDERNOTEXIST | 单据不存在 | 查询单据不存在 | 确认入参,传入正确单据 |
| RATE_LIMITED | 频率限制 | 超过接口调用频率限制 | 请求量不要超过XX/XX |