开发文档

统一下单

应用场景

除被扫支付场景以外,商户系统先调用该接口在QQ钱包服务后台生成预支付交易单,返回正确的预支付交易会话标识后再按具体的场景生成交易串调起支付。

接口地址

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

是否需要证书

接口规则

· 为保证交易安全性,采用HTTPS传输

· 采用POST方法提交

· 统一采用UTF-8字符编码

 更多详情见接口规则

 

请求参数

变量名

字段名

字段类型

必须

描述

示例

appid

应用ID

String(32)

腾讯开放平台或QQ互联平台审核通过的应用AppID

88888888

sub_appid

子商户应用ID

String(32)

腾讯开放平台或QQ互联平台审核通过的应用AppID

88888888

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

time_start

订单生成时间

String(14)

订单生成时间,格式为yyyyMMddHHmmss,如2009年12月25日9点10分10秒表示为20091225091010,时区为GMT+8 beijing,该时间取自商户服务器

20091225091010

time_expire

订单超时时间

String(14)

订单失效时间,格式为yyyyMMddHHmmss,如2009年12月25日9点10分10秒表示为20091225091010,时区为GMT+8 beijing,该时间取自商户服务器

20091225091010

limit_pay

支付方式限制

String(32)

可以针对当前的交易,限制用户的支付方式,如:仅允许使用余额,或者是禁止使用信用卡,详情见支付方式限制

no_balance

contract_code

代扣签约序列号

String(64)

商户侧记录的用户代扣协议序列号,支付中开通代扣必传

100001256

promotion_tag

QQ钱包活动标识

String(128)

指定本单参与某个QQ钱包活动或活动档位的标识,包含两个标识:

sale_tag --- 不同活动的匹配标志

level_tag --- 同一活动不同优惠档位的标志,可不填

格式如下(本字段参与签名):promotion_tag=level_tag=xxx&sale_tag=xxx

hellokitty

trade_type

支付场景

String(16)

APP、JSAPI、NATIVE、MINIAPP,详见支付场景

APP

notify_url

支付结果通知地址

String(256)

接收QQ钱包异步通知回调地址,通知url必须为直接可访问的url,不能携带参数,基于安全考虑,建议使用 https

https://www.qpay.qq.com

device_info

设备号

String(32)

调用接口提交的终端设备号

013467007045764

mini_app_param

小程序跳转地址和参数

String(128)

https://m.q.qq.com/a/p/xxxxx?s=yyyyy

 

示例如下:

 <xml>

<attach>ATTACH</attach>

<body>BODY</body>

<device_info>WP00000001</device_info>

<fee_type>CNY</fee_type>

<mch_id>1900005911</mch_id>

<nonce_str>bc9951066dec3b15ae352497daeef3c5</nonce_str>

<notify_url>https://www.yourwebsite.com/some/interface/</notify_url>

<out_trade_no>da7c50bebd600b999693c82a9a67fc86</out_trade_no>

<spbill_create_ip>your.real.ipv4.address</spbill_create_ip>

<total_fee>1</total_fee>

<trade_type>NATIVE</trade_type>

<sign>b35dc6220f1d2d55f91030f744780665</sign>

</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

88888888

sub_appid

子商户应用ID

String(32)

腾讯开放平台或QQ互联平台审核通过的应用AppID

88888888

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为成功时有返回

变量名

字段名

类型

必填

描述

示例

trade_type

支付场景

String(16)

APP、JSAPI、NATIVE、MINIAPP

APP

prepay_id

QQ钱包的预支付会话标识 

String(64)

QQ钱包的预支付会话标识,用于后续接口调用中使用

2FF3D78E77957380ADFF91D55D912F10

code_url

二维码链接

String(256)

当trade_type为 NATIVE 时,才会返回该字段,值可以直接转换为二维码,用户使用手机QQ扫描后,将会打开QQ钱包的支付页面,APP、JSAPI、MINIAPP不会返回此参数

http://qpay.qq.com/qr/0e02ebc4

示例如下:

<xml>

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

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

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

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

<code_url><![CDATA[https://qpay.qq.com/qr/5e272a22]]></code_url>

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

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

<prepay_id><![CDATA[5Vd929f526581b64d61577ecaf2eb84b]]></prepay_id>

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

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

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

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