开发文档

提交付款码支付

应用场景:

收银员使用扫码设备读取手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)

子商户号或商户识别码

19000001099000000101

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

示例如下:

    <xml>

        <appid>1111223451</appid>

        <auth_code>910821442572383696</auth_code>

        <body>12313</body>

        <device_info>1234567890abc</device_info>

        <mch_id>1301278501</mch_id>

        <nonce_str>fecf31a13be2309093db5df934848583</nonce_str>

        <notify_url>https://qpay.qq.com/cgi-bin/pay/qpay_unified_order.cgi</notify_url>

        <out_trade_no>2016061235213808</out_trade_no>

        <sign>5113de07932a7db827459671ebc05f44</sign>

        <spbill_create_ip>10.123.9.102</spbill_create_ip>

        <sub_mch_id>9000000002</sub_mch_id>

        <total_fee>1000</total_fee>

        <trade_type>MICROPAY</trade_type>

   </xml>

 

返回结果:

变量名

字段名

类型

必填

描述

示例

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)

子商户号或银行识别码

19000001099000000101

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)

MICROPAYAPPJSAPINATIVE

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 等字段。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,如2009122591010秒表示为20091225091010

20141030133525

trade_state_desc

交易状态描述

String(256)

对当前查询订单状态的描述和下一步操作的指引

支付失败,请重新下单支付

openid

用户标识

String(128)

用户在商户appid下的唯一标识

oUpF8uMuAJO_M2pxb1Q9zNjWeS6o

sub_openid

子商户用户标识

String(128)

用户在子商户appid下的唯一标识

oUpF8uMuAJO_M2pxb1Q9zNjWeS6o

示例如下:

   <xml>

       <retcode><![CDATA[0]]></retcode>

       <retmsg><![CDATA[ok]]></retmsg>

       <appid><![CDATA[1111223451]]></appid>

       <bank_type><![CDATA[CMB_DEBIT]]></bank_type>

       <cash_fee><![CDATA[884]]></cash_fee>

       <coupon_count><![CDATA[1]]></coupon_count>

       <coupon_fee><![CDATA[116]]></coupon_fee>

       <coupon_fee_0><![CDATA[116]]></coupon_fee_0>

       <device_info><![CDATA[1234567890abc]]></device_info>

       <fee_type><![CDATA[CNY]]></fee_type>

       <mch_id><![CDATA[1301278501]]></mch_id>

       <nonce_str><![CDATA[fecf31a13be2309093db5df934848583]]></nonce_str>

       <out_trade_no><![CDATA[2016061235213808]]></out_trade_no>

       <price><![CDATA[1000]]></price>

       <result_code><![CDATA[SUCCESS]]></result_code>

       <return_code><![CDATA[SUCCESS]]></return_code>

       <return_msg><![CDATA[SUCCESS]]></return_msg>

       <sign><![CDATA[C2FC563555502E6B6B1DAEA35C04836B]]></sign>

       <sub_appid><![CDATA[]]></sub_appid>

       <sub_mch_id><![CDATA[]]></sub_mch_id>

       <time_end><![CDATA[20160722112915]]></time_end>

       <total_fee><![CDATA[1000]]></total_fee>

       <trade_desc_desc><![CDATA[]]></trade_desc_desc>

       <trade_state><![CDATA[SUCCESS]]></trade_state>

       <trade_type><![CDATA[MICROPAY]]></trade_type>

       <transaction_id><![CDATA[1301278501201607223160011619]]></transaction_id>

       <openid><![CDATA[A662268D9A320D7B75A8AAB2E8F47013]]></openid>

   </xml>


错误代码:

错误码

描述

原因

解决方案

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参数格式是否正确