- On: 2026-08-07 18:52:17
- By: admin
提交付款码支付应用场景：
收银员使用扫码设备读取手Q钱包付款码以后，二维码或条码信息传送至商户收银台，由商户收银台或者商户后台调用该接口发起支付。
注意：
1、提交支付请求后，手Q钱包会同步返回支付结果，当返回结果为“系统错误”时，商户系统等待5秒后调用【订单查询接口】， 查询支付实际交易结果；当返回结果为“USERPAYING ”时，商户系统可设置间隔时间(建议10秒)重新查询支付结果，直到支付成功或超时(建议30秒)；
2、在多次调用订单查询接口后，如果交易状况仍不明晰，请调用【撤销订单接口】，如果交易失败则关闭订单，该单不能再支付成功；如果交易成功，则将扣款退回到用户账户。 当撤销无返回或错误时，请再次调用；
3、请勿在调用【提交付款码支付接口】后立即调用【撤销订单接口】，建议至少5分钟后再调用。撤销订单API需要双向证书。
接口地址：
https://qpay.qq.com/cgi-bin/pay/qpay_micro_pay.cgi
是否需要证书：
否
接口规则
· 为保证交易安全性，采用HTTPS传输
· 采用POST方法提交
· 统一采用UTF-8字符编码
更多详情见接口规则
请求参数：
变量名
字段名
字段类型
必填
描述
示例
appid
应用ID
String(32)
否
腾讯开放平台或QQ互联平台审核通过的应用APPID
1007033799
sub_appid
子商户应用ID
String(32)
否
腾讯开放平台或QQ互联平台审核通过的应用APPID
1007033799
mch_id
商户号
String(32)
是
QQ钱包分配的商户号
1900000109
sub_mch_id
子商户号
String(32)
是
子商户号或商户识别码
1900000109或9000000101
nonce_str
随机字符串
String(32)
是
随机字符串，不长于32位
3e5a036cb4bc3a677a38ad9d69eb3feb
sign
签名
String(128)
是
商户签名，详见商户签名算法规则
C380BEC2BFD727A4B6845133519F3AD6
body
商品描述
String(128)
是
商品命名规则，详见body字段格式规定
7-ElevenOrder
attach
附加数据
String(128)
否
附加数据，在查询API和支付通知中原样返回，该字段主要用于商户携带订单的自定义数据
深圳分店
out_trade_no
商户订单号
String(32)
是
商户系统内部的订单号,32个字符内、可包含字母，其它说明见商户订单号
20150806125346
fee_type
货币类型定义
String(16)
是
默认为人民币：CNY
CNY
total_fee
订单金额
Int
是
商户订单总金额，单位为分，只能为整数，详见交易金额
888
spbill_create_ip
终端IP
String(16)
是
商户设备IP
123.12.12.123
limit_pay
支付方式限制
String(32)
否
可以针对当前的交易，限制用户的支付方式，如：仅允许使用余额，或者是禁止使用信用卡。详情见支付方式限制
no_credit
promotion_tag
QQ钱包活动标识
String(128)
否
指定本单参与某个QQ钱包活动或活动档位的标识，包含两个标识： sale_tag --- 不同活动的匹配标志 level_tag --- 同一活动不同优惠档位的标志，可不填 。
格式如下（本字段参与签名）：promotion_tag=level_tag=xxx&sale_tag=xxx
hellokitty
notify_url
支付结果通知地址
String(256)
否接收QQ钱包异步通知回调地址，通知url必须为直接可访问的url，不能携带参数。基于安全考虑，建议使用 https
https://www.qpay.qq.com
device_info
设备号
String(32)
是
调用接口提交的终端设备号
013467007045764
auth_code
用户的付款码
String(32)
是
18位字符串，开头两位为91。该字段由商户的扫码设备，从用户的手机QQ上读取，或者是店员输入
911272938565404116
trade_type
支付场景
String(16)
是
付款码，MICROPAY
MICROPAY
示例如下：
返回结果：
变量名
字段名
类型
必填
描述
示例
return_code
返回状态码
String(16)
是
SUCCESS/FAIL 此字段是通信标识，非交易标识，交易是否成功需要查看result_code来判断
SUCCESS/FAIL
return_msg
返回信息
String(128)
否
返回信息，如非空，为错误原因
签名失败
retcode
手Q CGI原始错误码
String(16)
是
原始错误码
10025
retmsg
手Q CGI原始错误信息
String(128)
否
原始错误信息
系统繁忙
下列字段，在return_code为成功时有返回：
变量名
字段名
类型
必填
描述
示例
appid
应用ID
String(32)
否
腾讯开放平台或QQ互联平台审核通过的应用APPID
1007033799
sub_appid
子商户应用ID
String(32)
否
腾讯开放平台或QQ互联平台审核通过的应用APPID
1007033790
mch_id
商户号
String(32)
是
QQ钱包分配的商户号
1900000109
sub_mch_id
子商户号
String(32)
是
子商户号或银行识别码
1900000109或9000000101
sign
商户签名算法规则
String(128)
是
商户签名，详见商户签名算法规则
C380BEC2BFD727A4B6845133519F3AD6
result_code
业务结果
String(32)
是
SUCCESS/FAIL
SUCCESS
err_code
错误代码
String(32)
否
详情见错误代码
SYSTEMERROR
err_code_des
错误代码描述
String(128)
否
错误返回的信息描述
系统繁忙
nonce_str
随机字符串
String(32)
是
随机字符串，不长于32位
3e5a036cb4bc3a677a38ad9d69eb3feb
下列字段，在result_code为成功时有返回：
变量名
字段名
类型
必填
描述
示例
device_info
设备号
String(32)
否
调用接口提交的终端设备号
013467007045764
trade_type
支付场景
String(16)
是
MICROPAY、APP、JSAPI、NATIVE
MICROPAY
trade_state
交易状态
String(32)
是
SUCCESS 支付成功
REFUND 转入退款
REVOKED订单已撤销
CLOSED 订单已关闭
USERPAYING 用户支付中
SUCCESS
bank_type
付款银行
String(16)
是
银行类型，采用字符串类型的银行标识
CCB_DEBIT
fee_type
货币类型
String(16)
是
默认为人民币：CNY
CNY
total_fee
订单金额
Int
是
商户订单总金额，单位为分，只能为整数，详见订单金额
888
cash_fee
用户支付金额
Int
是
用户本次交易中，实际支付的金额
888
coupon_fee
QQ钱包优惠金额
Int
否
本次交易中，被优惠掉的金额。被优惠掉的金额，可能包含多个部分，具体构成，请参考 coupon_fee_$n 等字段。n 从0开始。
666
transaction_id
QQ钱包订单号
String(32)
是
QQ钱包订单号
128355470147160281308949397
out_trade_no
商户订单号
String(32)
是
商户系统内部的订单号,32个字符内、可包含字母。其它说明见商户订单号
20160806125346
attach
附加数据
String(128)
否
附加数据，在查询API和支付通知中原样返回，该字段主要用于商户携带订单的自定义数据
深圳分店
time_end
支付完成时间
String(14)
是
订单支付时间，格式为yyyyMMddHHmmss，如2009年12月25日9点10分10秒表示为20091225091010
20141030133525
trade_state_desc
交易状态描述
String(256)
是
对当前查询订单状态的描述和下一步操作的指引
支付失败，请重新下单支付
openid
用户标识
String(128)
否
用户在商户appid下的唯一标识
oUpF8uMuAJO_M2pxb1Q9zNjWeS6o
sub_openid
子商户用户标识
String(128)
否
用户在子商户appid下的唯一标识
oUpF8uMuAJO_M2pxb1Q9zNjWeS6o
示例如下：
错误代码：
错误码
描述
原因
解决方案
AUTH_CODE_ERROR
授权码参数错误
请求参数未按指引进行填写
每个二维码仅限使用一次，请刷新再试
AUTHCODEEXPIRE
二维码已过期，请用户在手机QQ上刷新后再试
用户的条码已经过期
请收银员提示用户，请用户在手机QQ上刷新条码，然后请收银员重新扫码。 直接将错误展示给收银员
AUTH_CODE_INVALID
授权码检验错误
收银员扫描的不是QQ付款码的条码
请扫描QQ付款码支付条码/二维码
BANKERROR
银行系统异常
银行端超时
请立即调用qpay_order_query.cgi 订单查询接口 ，查询当前订单的不同状态，决定下一步的操作
BUYER_MISMATCH
支付帐号错误
暂不支持同一笔订单更换支付方
请确认买家身份是否相同
INVALID_TRANSACTIONID
无效transaction_id
请求参数未按指引进行填写
请求参数错误，检查原交易号是否存在或发起支付交易接口返回失败
LACK_PARAMS
缺少参数
缺少必要的请求参数
请检查参数是否齐全
MCHID_NOT_EXIST
MCHID不存在
参数中缺少MCHID
请检查MCHID是否正确
NOAUTH
商户无此接口权限
商户未开通此接口权限
请商户前往申请此接口权限
NOTENOUGH
余额不足
用户的账户额度或者是QQ钱包余额不足
请收银员提示用户更换当前支付的卡，然后请收银员重新扫码。建议：商户系统返回给收银台的提示为“用户余额不足.提示用户换卡支付” 用户帐号余额不足，请用户充值或更换支付卡后再支付
NOTSUPORTCARD
不支持卡类型
用户使用卡种不支持当前支付形式
请用户重新选择卡种 建议：商户系统返回给收银台的提示为“该卡不支持当前支付，提示用户换卡支付或绑新卡支付”
ORDERCLOSED
订单已关闭
该订单已经被关闭
订单已经被关闭，请重新下单支付，不需要重复调用关单接口
ORDERNOTEXIST
此交易订单号不存在
查询系统中不存在此交易订单号
请商户检查需要查询的订单号是否正确 , 根据实际的情况判断，是否要关闭订单，禁止用户进行支付。
ORDERPAID
订单已支付
订单已支付
订单已支付 不能发起关单，请当作已支付的正常交易，请勿重复发起支付请求。
ORDERREVERSED
订单已撤销
当前订单已经被撤销
当前订单状态为“订单已撤销”，请提示用户重新下单支付。 无需重复调用 qpay_reverse.cgi 冲正接口（撤销接口）
OUT_TRADE_NO_USED
商户订单号重复
同一笔交易不能多次提交
请核实商户订单号是否重复提交
PARAM_ERROR
参数错误
请求参数未按指引进行填写
请根据接口返回的详细信息检查您的程序
POST_DATA_EMPTY
post数据为空
post数据不能为空
请检查post数据是否为空。
REQUIRE_POST_METHOD
请使用post方法
未使用post传递参数
请检查请求参数是否通过post方法提交，不要使用GET
SIGNERROR
签名错误
参数签名结果不正确
请检查签名参数和方法是否都符合签名算法要求
SYSTEMERROR
系统错误
系统错误
系统异常，请参数不变，重新调用该API
USER_ACCOUNT_ABNORMAL
退款请求失败
用户帐号异常或注销
此状态代表退款申请失败，商户可自行处理退款。
USERPAYING
用户支付中，需要输入密码
该笔交易因为业务规则要求，需要用户输入支付密码。
等待5秒，然后调用qpay_order_query.cgi 订单查询接口 ，查询当前订单的不同状态，决定下一步的操作。
XML_FORMAT_ERROR
XML格式错误
XML格式错误
请检查XML参数格式是否正确