开发指引

开发前，开发者需要完成如下两个步骤：配置开发参数和配置产品功能。

• 当用户通过商户提供的入口申请使用服务后，商户系统同步创建微信支付分服务订单，商家再根据返回参数拉起支付分确定订单界面，用户确认订单后商家开始向用户提供服务。

• 服务结束后商户通过完结订单接口告知支付分需要收款，由支付分完成自动扣款，最后通过下载交易账单进行对账。特殊需要退款的服务订单，也可调用退款接口完成退款。

• 整个业务开发过程中的前端UI交互，需要满足支付分合作品牌线上应用规范。

当用户申请使用服务时，商户需调用创建支付分订单API接口创建订单。在接口参数中，商户需要通过post_payments字段，上传本笔订单的预估费用或计费规则等信息，不同的场景有不同的传值要求，详见：post_payments(后付费项目)字段传参说明

下单接口需要注意的参数：

service_id：支付分服务ID，商户支付分服务的唯一标识，支付分产品权限申请审核通过后，微信支付运营同学会向商户提供支付分服务ID。

need_user_confirm：该参数表示这一笔服务订单，是否需要用户确认。需确认模式下，商户必须固定传"true"。

risk_fund.name：服务风险金名称。

先免模式下，该参数只能传 押金[DEPOSIT]、预付款[ADVANCE]、保证金[CASH_DEPOSIT] 中的一个值；

先享模式，该参数只能传 [预估订单费用]ESTIMATE_ORDER_COST。

risk_fund.amount：服务风险金金额，不可超过服务ID风险金额上限，支付分运营同学提供service_id时会告知服务ID风险金额上限。

先免模式下，传这笔服务单需要的押金、预付款、保证金数额。

先享模式，传这笔订单预估的实际费用。

time_range：时间参数时需注意如果选用"yyyyMMddHHmmss"精确到秒格式，由于商户系统和微信支付分系统可能存在一定时差，导致API接口调用出现时间检验不通过失败情况，因此商户在传入时间参数时需预留一定误差时间。

package：用于拉起支付分小程序确认订单，创单成功后返回。

商户调用创建支付分订单API接口生成订单后，会获取到用于拉起支付分订单确认页面的关键参数"package"，商户根据自己使用支付分的载体选择对应API接口拉起支付分，移动应用类型使用APP调起支付分订单确认页面，公众号类型使用JSAPI调起支付分订单确认页面，小程序类型使用小程序调起支付分订单确认页面。

• 用户确认订单后，微信支付会向商户发送回调通知，告知用户已确认完成。商户也可通过查询支付分订单API获取用户确认订单的状态(确认后state为DOING，未确认为CREATED)，用户确认订单后，商户可以开始向用户提供服务。

• 服务完成后，商户需调用完结支付分订单API，通知微信支付服务已结束(collection.state参数变为USER_PAYING状态，即用户待支付状态)。在接口参数中，商户需要通过post_payments字段，上传本笔订单实际的付费项目明细，不同的场景有不同的传值要求，详见：post_payments(后付费项目)字段传参说明

• 订单完结后，支付分会持续自动扣款，无需重复调用完结接口。

完结订单接口需要注意的参数：

total_amount：订单收款总金额，先免模式(订单收款总金额<=创单传的服务风险金额<=服务ID风险金额上限)，先享模式(订单收款总金额<=服务ID风险金额上限)，支付分运营同学在提供service_id时会告知服务ID风险金额上限。

post_payments：后付费项目，表示本次服务完成后，商家收取的服务费用项目。商户需要严格按照post_payments(后付费项目)字段传参说明传参，否则会导致支付分订单页无法正常展示后付费项目，影响验收上线。

time_range：实际服务时间，该参数有三种参数格式，如果选用"yyyyMMddHHmmss"精确到秒格式，可能由于商户系统和微信支付分系统存在一定时差，导致API接口调用出现时间检验不通过失败情况，因此商户在传入时间参数时需预留一定误差时间。

商户调用完结支付分订单API成功后，微信支付分就会对用户发起扣款，商户也可以调起支付分小程序订单详情页引导用户主动支付，用户如果有满足核销条件的代金券会自动使用(使用后，在支付成功回调和查询支付分订单接口的promotion_detail字段会返回代金券信息)，目前支付分只支持全场券。若扣款成功，微信支付会给商户系统发送支付成功回调通知，支付分订单结束。商户系统也通过调用查询支付分订单API主动查询扣款情况。

下面介绍几种扣款过程中的异常处理情况：

• 如果订单在“待支付”状态下（collection.state: USER_PAYING），若扣款金额有误可调用修改订单金额API修改订单金额，系统将按照修改后的金额发起扣款(注意只能下调扣款金额)。

• 如果订单在“待支付”状态下（collection.state: USER_PAYING），若不需要继续扣款，希望微信支付分停止继续扣款。可调用取消支付分订单API取消待支付的支付分订单，支付分订单将变成已取消状态。

• 如果订单在“待支付”状态下（collection.state: USER_PAYING），用户通过其他方式完成支付，商户可调用同步订单信息API将订单支付成功状态同步给微信支付，后续微信支付将不再发起扣款，支付分订单将变成已完成状态。

商户可在次日上午10点后通过商户平台手动下载交易账单文件进行对账，详见如何在商户平台下载账单。另外，商户也可以通过申请交易账单API请求账单，然后使用下载账单API下载交易账单进行对账。

需要注意以下几点：

• 订单只有在支付成功后才会出现在交易账单中，未支付成功的订单不会显示在账单里。

• 主动支付完成的支付分订单账单的交易类型是JSAPI，而自动扣款完成的支付分订单账单的交易类型为AUTH。

• 在账单中，商户订单号并非支付分商户服务单号，而是在账单的商户数据包中（格式为wxzff|微信服务单号|商户服务单号）。

支付分订单支付后，若订单需要退款，商户可登录商户平台手动操作提交退款，具体参考交易退款方法介绍。

同时也可通过支付成功回调和查询订单获取微信交易单号（transaction_id），然后使用申请退款API提交退款。提交退款后，可使用查询单笔退款API查看当前退款状态，成功退款后将收到退款结果通知。

2、当支付分订单状态在待支付状态(collection.state: USER_PAYING)下，商户可以调用接口修改订单金额，修改成功后微信侧将按新金额发起扣款。

3、当支付分订单状态为已创建(state:CREATE)和用户已确认订单(collection.state: USER_CONFIRM)和待支付状态(collection.state: USER_PAYING)下，商户可以调用取消服务订单接口，取消支付分服务订单。

• state：EXPIRED

• state：REVOKED

• state：DONE

商户侧使用测试微信号完成开发测试后，需按照以下流程进行验收和上线工作(验收审核通过后对应服务才能配置上线并开放用户使用)：