提交付款码支付
更新时间:2025.03.21收银员使用扫码设备读取微信用户刷卡授权码以后,二维码或条码信息传送至商户收银台,由商户收银台或者商户后台调用该接口发起支付。
|
接口说明
适用对象: 直连模式 机构模式
请求URL: https://apihk.mch.weixin.qq.com/pay/micropay
请求方式: POST
数据格式: XML
是否需要证书: 否
请求参数
参数名 | 变量 | 类型 | 必填 | 描述 |
---|---|---|---|---|
公众账号ID | appid | string(32) | 是 | 微信分配的公众账号ID |
子商户公众账号ID | sub_appid | string(32) | 否 | 微信分配的子商户公众账号ID |
商户号 | mch_id | string(32) | 是 | 微信支付分配的商户号 |
子商户号 | sub_mch_id | string(32) | 是 | 微信支付分配的子商户号,开发者模式下必填 |
设备号 | device_info | string(32) | 否 | 终端设备号(商户自定义,如门店编号) |
随机字符串 | nonce_str | string(32) | 是 | 随机字符串,不长于32位。推荐随机数生成算法 |
签名 | sign | string(64) | 是 | 签名,详见签名生成算法 |
签名类型 | sign_type | string(32) | 否 | 签名类型,目前支持HMAC-SHA256和MD5,默认为MD5 |
商品描述 | body | string(32) | 是 | 商品或支付单简要描述 |
版本号 | version | string(32) | 否 | 固定值 1.0 |
商品详情 | detail | string(6000) | 否 | 商品详细列表,使用Json格式,传输签名前请务必使用CDATA标签将JSON文本串保护起来。 |
附加数据 | attach | string(127) | 否 | 附加数据,在查询API和支付通知中原样返回,该字段主要用于商户携带订单的自定义数据 |
商户订单号 | out_trade_no | string(32) | 是 | 商户系统内部订单号,要求32个字符内,只能是数字、大小写字母_-|*@ ,且在同一个商户号下唯一。 其他说明见商户订单号 |
标价金额 | total_fee | int | 是 | 标价订单总金额,单位为分,只能为整数,详见支付金额 |
标价币种 | fee_type | string(16) | 是 | 符合ISO 4217标准的三位字母代码,币种列表详见货币类型 |
终端IP | spbill_create_ip | string(64) | 是 | 符合ISO 支持IPV4和IPV6两种格式的IP地址。调用微信支付API的机器IP |
订单优惠标记 | goods_tag | string(32) | 否 | 订单优惠标记,代金券或立减优惠功能的参数,说明详见代金券或立减优惠 |
授权码 | auth_code | string(128) | 是 | 扫码支付授权码,设备读取用户微信中的条码或者二维码信息 |
交易起始时间 | time_start | string(14) | 否 | 订单生成时间,格式为yyyyMMddHHmmss,如2009年12月25日9点10分10秒表示为20091225091010。其他详见时间规则 |
交易结束时间 | time_expire | string(14) | 否 | 订单失效时间,格式为yyyyMMddHHmmss,如2009年12月27日9点10分10秒表示为20091227091010。 |
场景信息 | scene_info | string(256) | 否 | 该字段用于统一下单时上报场景信息,目前支持上报实际门店信息。 |
请求示例:
返回参数
正常返回
字段名 | 变量 | 类型 | 必填 | 描述 |
---|---|---|---|---|
返回状态码 | return_code | string(16) | 是 | SUCCESS/FAIL |
返回信息 | return_msg | string(128) | 否 | 返回信息,如非空,为错误原因 |
当return_code为SUCCESS的时候,还会包括以下字段:
字段名 | 变量 | 类型 | 必填 | 描述 |
---|---|---|---|---|
公众账号ID | appid | string(32) | 是 | 调用接口提交的公众账号ID |
子商户公众账号ID | sub_appid | string(32) | 是 | 调用接口提交的子商户公众账号ID |
商户号 | mch_id | string(32) | 是 | 调用接口提交的商户号 |
子商户号 | sub_mch_id | string(32) | 是 | 调用接口提交的子商户号 |
设备号 | device_info | string(32) | 否 | 调用接口提交的终端设备号 |
随机字符串 | nonce_str | string(32) | 是 | 微信返回的随机字符串 |
签名 | sign | string(64) | 是 | 微信返回的签名,详见签名生成算法 |
业务结果 | result_code | string(16) | 是 | SUCCESS/FAIL |
错误代码 | err_code | string(32) | 否 | 详细参见错误列表 |
错误代码描述 | err_code_des | string(128) | 否 | 错误返回的信息描述 |
当return_code 和result_code都为SUCCESS的时,还会包括以下字段:
字段名 | 变量 | 类型 | 必填 | 描述 |
---|---|---|---|---|
用户标识 | openid | string(128) | 是 | 用户在商户appid 下的唯一标识 |
是否关注公众账号 | is_subscribe | string(1) | 是 | 用户是否关注公众账号,仅在公众账号类型支付有效,取值范围:Y或N;Y-关注;N-未关注 |
用户子标识 | sub_openid | string(128) | 否 | 子商户appid下用户唯一标识,如需返回则请求时需要传sub_appid |
是否关注子公众账号 | sub_is_subscribe | string(1) | 否 | 用户是否关注子公众账号,仅在公众账号类型支付有效,取值范围:Y或N;Y-关注;N-未关注 |
交易类型 | trade_type | string(16) | 是 | 支付类型为MICROPAY(即扫码支付) |
付款银行 | bank_type | string(32) | 是 | 银行类型,采用字符串类型的银行标识,值列表详见银行类型 |
标价币种 | fee_type | string(16) | 是 | 符合ISO 4217标准的三位字母代码,列表详见货币类型 |
标价金额 | total_fee | int | 是 | 订单总金额,单位为分,只能为整数,详见支付金额 |
现金支付币种 | cash_fee_type | string(16) | 否 | 符合ISO 4217标准的三位字母代码,列表详见货币类型 |
现金支付金额 | cash_fee | int | 是 | 订单现金支付金额,详见支付金额 |
微信支付订单号 | transaction_id | string(32) | 是 | 微信支付订单号 |
商户订单号 | out_trade_no | string(32) | 是 | 商户系统内部订单号,要求32个字符内,只能是数字、大小写字母_-|*@ ,且在同一个商户号下唯一。 |
商家数据包 | attach | string(128) | 否 | 自定义参数,原样返回 |
支付完成时间 | time_end | string(14) | 是 | 订单生成时间,格式为yyyyMMddHHmmss,如2009年12月25日9点10分10秒表示为20091225091010。详见时间规则 |
汇率 | rate | string(16) | 是 | 标价币种与支付币种的兑换比例乘以10的8次方即为此值,例如美元兑换人民币的比例为6.5,则rate=650000000 |
举例如下:
错误码
错误码 | 描述 | 问题 | 解决方案 |
---|---|---|---|
SYSTEMERROR | 接口返回错误 | 系统超时 | 请立即调用被扫订单结果查询API,查询当前订单状态,并根据订单的状态决定下一步的操作。 |
PARAM_ERROR | 参数错误 | 请求参数未按指引进行填写 | 请根据接口返回的详细信息检查您的程序 |
ORDERPAID | 订单已支付 | 订单号重复 | 请确认该订单号是否重复支付,如果是新单,请使用新订单号提交 |
NOAUTH | 商户无权限 | 商户没有开通被扫支付权限 | 请开通商户号权限。请联系产品或商务申请 |
AUTHCODEEXPIRE | 二维码已过期,请用户在微信上刷新后再试 | 用户的条码已经过期 | 请收银员提示用户,请用户在微信上刷新条码,然后请收银员重新扫码。 直接将错误展示给收银员 |
NOTENOUGH | 余额不足 | 用户的零钱余额不足 | 请收银员提示用户更换当前支付的卡,然后请收银员重新扫码。建议:商户系统返回给收银台的提示为“用户余额不足.提示用户换卡支付” |
NOTSUPORTCARD | 不支持卡类型 | 用户使用卡种不支持当前支付形式 | 请用户重新选择卡种 建议:商户系统返回给收银台的提示为“该卡不支持当前支付,提示用户换卡支付或绑新卡支付” |
ORDERCLOSED | 订单已关闭 | 该订单已关 | 商户订单号异常,请重新下单支付 |
ORDERREVERSED | 订单已撤销 | 当前订单已经被撤销 | 当前订单状态为“订单已撤销”,请提示用户重新支付 |
BANKERROR | 银行系统异常 | 银行端超时 | 请立即调用被扫订单结果查询API,查询当前订单的不同状态,决定下一步的操作。 |
USERPAYING | 用户支付中,需要输入密码 | 该笔交易因为业务规则要求,需要用户输入支付密码。 | 等待5秒,然后调用被扫订单结果查询API,查询当前订单的不同状态,决定下一步的操作。 |
AUTH_CODE_ERROR | 授权码参数错误 | 请求参数未按指引进行填写 | 每个二维码仅限使用一次,请刷新再试 |
AUTH_CODE_INVALID | 授权码检验错误 | 收银员扫描的不是微信支付的条码 | 请扫描微信支付被扫条码/二维码 |
XML_FORMAT_ERROR | XML格式错误 | XML格式错误 | 请检查XML参数格式是否正确 |
REQUIRE_POST_METHOD | 请使用post方法 | 未使用post传递参数 | 请检查请求参数是否通过post方法提交 |
SIGNERROR | 签名错误 | 参数签名结果不正确 | 请检查签名参数和方法是否都符合签名算法要求 |
LACK_PARAMS | 缺少参数 | 缺少必要的请求参数 | 请检查参数是否齐全 |
NOT_UTF8 | 编码格式错误 | 未使用指定编码格式 | 请使用UTF-8编码格式 |
BUYER_MISMATCH | 支付账号错误 | 暂不支持同一笔订单更换支付方 | 请确认支付方是否相同 |
APPID_NOT_EXIST | APPID不存在 | 参数中缺少APPID | 请检查APPID是否正确 |
MCHID_NOT_EXIST | MCHID不存在 | 参数中缺少MCHID | 请检查MCHID是否正确 |
OUT_TRADE_NO_USED | 商户订单号重复 | 同一笔交易不能多次提交 | 请核实商户订单号是否重复提交 |
APPID_MCHID_NOT_MATCH | appid和mch_id不匹配 | appid和mch_id不匹配 | 请确认appid和mch_id是否匹配 |