微信支付-开发者文档

返回上一层文档首页 / 修改订单金额API

修改订单金额API

最新更新时间：2020.03.05 版本说明

完结订单总金额与实际金额不符时，且当服务订单收款状态处于“待支付（USER_PAYING）”时，商户可通过该接口修改订单金额。

注意：

• 若此笔订单已收款成功，商户直接使用退款能力，将差价退回用户即可。

• 修改次数>=1，第n次修改后金额 <第n-1次修改后金额。

• 押金订单的金额不支持修改。

特别注意：待支付（USER_PAYING）状态下，当用户正在尝试通过收银台主动支付订单金额时，修改订单金额API无法调用成功，可等待3min后重试

接口说明

适用对象：直连商户

请求URL：https://api.mch.weixin.qq.com/v3/payscore/serviceorder/{out_order_no}/modify

请求方式：POST

前置条件：服务订单支付状态为待支付

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

+后付费项目

post_payments

array

是

body后付费项目列表，最多包含100条付费项目。

参数名	变量	类型[长度限制]	必填	描述
付费项目名称	name	string[1,20]	是	相同订单号下不能出现相同的付费项目名称（付费项目名称为“商品信息”时除外，即可传入多条“商品信息”），当参数长度超过20个字符时，报错处理。示例值：就餐费用, 服务费
金额	amount	int64	条件选填	此付费项目总金额，大于等于0，单位为分，等于0时代表不需要扣费，只能为整数。如果填写了“付费项目名称”，则amount或description必须填写其一，或都填。示例值：40000
计费说明	description	string[1,30]	条件选填	描述计费规则，不超过30个字符，超出报错处理。如果填写了“付费项目名称”，则amount或description必须填写其一，或都填。示例值：就餐人均100元，服务费：100/小时
付费数量	count	int32	否	付费项目的数量。特殊规则：数量限制100，不填时默认1 示例值：4

+后付费商户优惠

post_discounts

array

否

body后付费商户优惠列表，最多包含30条商户优惠。
如果传入，用户侧则显示此参数。

参数名	变量	类型[长度限制]	必填	描述
优惠名称	name	string[1,20]	否	优惠名称说明；name和description若填写，则必须同时填写。示例值：满20减1元
优惠说明	description	string[1,30]	条件选填	优惠使用条件说明。 name和description若填写，则必须同时填写。示例值：不与其他优惠叠加
优惠金额	amount	int64	条件选填	优惠金额；单位为分，只能为整数，详见支付金额。示例值：100
优惠数量	count	int32	否	优惠的数量。特殊规则：数量限制100，不填时默认1。示例值：2

总金额

total_amount

int64

是

body总金额，单位为分，不能超过完结订单时候的总金额，只能为整数，详见支付金额。此参数需满足：总金额 =（修改后付费项目1…+修改后完结付费项目n）-（修改后付费商户优惠项目1…+修改后付费商户优惠项目n）
示例值：50000

修改原因

reason

string[1,50]

是

body按照字符计算，超过长度报错处理。
示例值：用户投诉

请求示例

JSON


{
  "appid": "wxd678efh567hg6787",
  "service_id": "500001",
    "post_payments": [
    {
      "name": "就餐费用服务费",
      "amount": 4000,
      "description": "就餐人均100元服务费：100/小时",
      "count": 1
    }
  ],
  "post_discounts":[
  {
    "name": "满20减1元",
    "description": "不与其他优惠叠加",
    "amount": 100
   }
  ],
  "total_amount": 2000,
  "reason": "用户投诉"
}

    
｛
JAVA示例代码
｝

返回参数

参数名

变量

类型[长度限制]

必填

描述

应用ID

appid

string[1,32]

是

调用接口提交的公众账号ID。
示例值：wxd678efh567hg6787

商户号

mchid

string[1,32]

是

调用接口提交的商户号。
示例值：1230000109

服务ID

service_id

string[1,32]

是

调用该接口提交的服务ID。
示例值：500001

商户服务订单号

out_order_no

string[1,32]

是

调用接口提交的商户服务订单号。
示例值：1234323JKHDFE1243252

服务信息

service_introduction

string[1,20]

是

服务信息用于介绍本订单所提供的服务，当参数长度超过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的数字，单位为分，只能为整数，详见支付金额。
此参数需满足：总金额=修改后付费项目金额之和-修改后付费商户优惠项目金额之和，且小于等于订单风险金额。
示例值：40000

+后付费项目

post_payments

array

是

后付费项目列表，最多包含100条付费项目。

参数名	变量	类型[长度限制]	必填	描述
付费项目名称	name	string[1,20]	是	相同订单号下不能出现相同的付费项目名称（付费项目名称为“商品信息”时除外，即可传入多条“商品信息”），当参数长度超过20个字符时，报错处理。示例值：就餐费用, 服务费
金额	amount	int64	条件选填	此付费项目总金额，大于等于0，单位为分，等于0时代表不需要扣费，只能为整数。如果填写了“付费项目名称”，则amount或description必须填写其一，或都填。示例值：40000
计费说明	description	string[1,30]	条件选填	描述计费规则，不超过30个字符，超出报错处理。如果填写了“付费项目名称”，则amount或description必须填写其一，或都填。示例值：就餐人均100元，服务费：100/小时
付费数量	count	int32	否	付费项目的数量。示例值：4

+后付费商户优惠

post_discounts

array

否

后付费商户优惠，最多包含30条付费项目。
如果传入，用户侧则显示此参数。

参数名	变量	类型[长度限制]	必填	描述
优惠名称	name	string[1,20]	否	优惠名称说明。示例值：满20减1元
优惠说明	description	string[1,30]	否	优惠使用条件说明。如果填写了name（优惠名称）和description（优惠说明）其中一个字段内容，则另一个字段也必须填写。示例值：不与其他优惠叠加
优惠金额	amount	int64	条件选填	优惠金额示例值：100
优惠数量	count	int32	否	优惠的数量。特殊规则：数量限制100，不填时默认1。示例值：2

+订单风险金

risk_fund

object

是

订单风险金信息。
如果传入，用户侧则显示此参数。

参数名	变量	类型[长度限制]	必填	描述
风险金名称	name	string[1,64]	是	枚举值：【先免模式】（评估不通过可交押金）可填名称为 DEPOSIT：押金 ADVANCE：预付款 CASH_DEPOSIT：保证金【先享模式】（评估不通过不可使用服务）可填名称为 ESTIMATE_ORDER_COST：预估订单费用示例值：ESTIMATE_ORDER_COST
风险金额	amount	int64	是	1、数字，必须>0（单位分）。 2、风险金额≤每个服务ID的风险金额上限。 3、当商户优惠字段为空时，付费项目总金额≤服务ID的风险金额上限（未填写金额的付费项目，视为该付费项目金额为0）。示例值：10000
风险说明	description	string[1,30]	否	文字，不超过30个字。示例值：就餐的预估费用

+服务时间段

time_range

object

否

服务时间范围。
如果传入，用户侧则显示此参数。

参数名	变量	类型[长度限制]	必填	描述
服务开始时间	start_time	string[1,14]	否	用户端展示用途。用户下单时确认的服务开始时间（比如用户今天下单，明天开始接受服务，这里指的是明天的服务开始时间）。支持三种格式：yyyyMMddHHmmss、yyyyMMdd和 OnAccept ● 传入20091225091010表示2009年12月25日9点10分10秒。 ● 传入20091225默认时间为2009年12月25日。 ● 传入OnAccept表示用户确认订单成功时间为【服务开始时间】。根据传入时间精准度进行校验 1）若传入时间精准到秒，则校验精准到秒。 2）若传入时间精准到日，则校验精准到日。示例值：20091225091010
服务开始时间备注	start_time_remark	string[1,20]	否	服务开始时间备注说明，服务开始时间有填时，可填写服务开始时间备注，不超过20个字符，超出报错处理。示例值：开始租借日期
服务结束时间	end_time	string[1,14]	否	用户端展示用途，支持两种格式：yyyyMMddHHmmss和yyyyMMdd ● 传入20091225091010表示2009年12月25日9点10分10秒。 ● 传入20091225默认时间为2009年12月25日。根据传入时间精准度进行校验 1、若传入时间精准到秒，则校验精准到秒。 2、若传入时间精准到日，则校验精准到日。示例值：20091225121010
服务结束时间备注	end_time_remark	string[1,20]	否	服务结束时间备注说明，服务结束时间有填时，可填写服务结束时间备注，不超过20个字符，超出报错处理。示例值：结束租借日期

+服务位置

location

object

否

服务位置信息。
如果传入，用户侧则显示此参数。

参数名	变量	类型[长度限制]	必填	描述
服务开始地点	start_location	string[1,50]	否	开始使用服务的地点，不超过50个字符，超出报错处理。示例值：嗨客时尚主题展餐厅
服务结束位置	end_location	string[1,50]	否	结束使用服务的地点，不超过50个字符，超出报错处理。示例值：嗨客时尚主题展餐厅

商户数据包

attach

string[1,256]

否

商户数据包可存放本订单所需信息，需要先urlencode后传入。
当商户数据包总长度超出256字符时，报错处理。商户接收回包是根据场景，决定是否需要做安全过滤(XSS/CSRF)。
示例值：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

否

服务使用信息

参数名

变量

类型[长度限制]

必填

描述

收款状态

state

string[1,32]

是

USER_PAYING：待支付
USER_PAID：已支付
示例值：USER_PAID

总收款金额

total_amount

int64

否

总金额，大于等于0的数字，单位为分，只能为整数，详见支付金额。
此参数需满足：总金额=付费项目金额之和-商户优惠项目金额之和，且小于等于订单风险金额。未使用服务、取消订单时，该字段必须为0。
示例值：50000

待收金额

paying_amount

int64

否

等待用户付款金额，只能为整数，详见支付金额。
示例值：40000

已收金额

paid_amount

int64

否

用户已付款的金额，只能为整数，详见支付金额。
示例值：10000

+收款明细列表

details

array

否

收款明细列表

参数名	变量	类型[长度限制]	必填	描述
收款序号	seq	int64	否	从1开始递增示例值：1
单笔收款金额	amount	int64	否	单笔收款动作的金额，只能为整数，详见支付金额。示例值：10000
收款成功渠道	paid_type	string[1,32]	否	NEWTON：微信支付分 MCH：商户渠道示例值：NEWTON
收款成功时间	paid_time	string[1,14]	否	支付成功时间，支持两种格式:yyyyMMddHHmmss和yyyyMMdd ● 传入20091225091010表示2009年12月25日9点10分10秒 ● 传入20091225默认时间为2009年12月25日0点0分0秒示例值：20091225091210
微信支付交易单号	transaction_id	string[1,200]	否	结单交易单号，等于普通支付接口中的transaction_id，可以使用该订单号在APP支付->API列表->查询订单、申请退款。只有单据状态为USER_PAID，且收款成功渠道为支付分渠道，收款金额大于0，才会返回结单交易单号。示例值：15646546545165651651

返回示例

正常示例


{
  "appid": "wxd678efh567hg6787",
  "mchid": "1230000109",
  "service_id": "500001",
  "out_order_no": "1234323JKHDFE1243252",
  "service_introduction": "某某酒店",
  "state": "CREATED",
  "state_description": "MCH_COMPLETE",
  "total_amount": 2000,
  "post_payments": [
    {
      "name": "就餐费用服务费",
      "amount": 2000
    }
  ],
  "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",
  "order_id": "15646546545165651651",
  "need_collection": true,
  "collection": {
    "state": "USER_PAYING",
    "total_amount": 2000,
    "paying_amount": 2000,
    "paid_amount": 0,
    "details": [
      {}
    ]
  }
}


    http://2323weixin.qq.com

错误码公共错误码

状态码	错误码	描述	解决方案
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	订单已完成	当前状态无需操作

常见问题更多QA

1、微信支付分通用化常见技术问题

微信支付商户平台

修改订单金额API

注意：

接口说明

请求参数

请求示例

返回参数

返回示例

错误码公共错误码