1. 接口说明 请求URL: https://apihk.mch.weixin.qq.com/v3/global/micropay/transactions/pay
2. 请求参数 商户号
mchid
string[1, 32]
是
Body 微信支付分配的商户号 注意：仅适用于 直连模式 示例值：1900000109
APPID
appid
string[1, 32]
是
Body 商户在微信公众平台申请服务号对应的APPID 注意：仅适用于 直连模式 示例值：wx8888888888888888
子商户号
sub_mchid
string[1, 32]
是
Body 微信支付分配的子商户号 注意：仅适用于 机构模式 示例值：1900000109
机构商户号
sp_mchid
string[1, 32]
是
Body 微信支付分配的机构商户号 注意：仅适用于 机构模式 示例值：1900000100
机构APPID
sp_appid
string[1, 32]
是
Body 机构在微信公众平台申请服务号对应的APPID 注意：仅适用于 机构模式 示例值：wx8888888888888888
子商户APPID
sub_appid
string[1, 32]
否
Body 子商户在微信开放平台申请移动应用对应的APPID 注意：仅适用于 机构模式 示例值：wx8888888888888888
商品描述
description
string[1, 127]
是
Body 商品或支付单简要描述，格式要求：门店品牌名-城市分店名-实际商品名称 示例值：image形象店-深圳腾大- QQ公仔
商户数据
attach
string[1, 127]
否
Body 附加数据，在查询API和支付通知中原样返回，该字段主要用于商户携带订单的自定义数据 示例值：自定义数据
商户订单号
out_trade_no
string[1, 32]
是
Body 商户系统内部的订单号,32个字符内、可包含字母；重新下单时请更换单号，其他说明见 商户订单号 示例值：1217752501201407033233368018
商品标记
goods_tag
string[1, 32]
否
Body 商品标记 示例值：WXG
交易类型
trade_type
string[1, 16]
是
Body MICROPAY：刷卡支付 示例值：MICROPAY
MCC码
merchant_category_code
string[1, 16]
是
Body 商户行业编码，值列表详见 商户行业编码 示例值：4111
支付者
payer
object
是
Body 支付者信息，详细说明见下文
支付者 授权码
auth_code
string[1, 128]
是
扫码支付授权码，即用户打开微信钱包显示的码
示例值：120061098828009406
订单金额
amount
object
是
Body 订单金额信息，详细说明见下文
订单金额 总金额
total
int
是
订单总金额，币种的最小单位，只能为整数，详见交易金额
示例值：888
货币类型
currency
string[1, 16]
是
符合ISO 4217标准的三位字母代码，默认仅支持使用mch_id 对应的结算币种或 CNY，如结算币种为 USD，则currency 可使用 USD 或 CNY，如需 使用非结算币种标价 ，请联系微信支付的区域运营申请
示例值：HKD
场景信息
scene_info
object
否
Body 场景信息对象，详细说明见下文
场景信息 商户端设备号
device_id
string[1, 32]
否
终端设备号(商户自定义，如门店编号)
示例值：013467007045764
商户端设备IP
device_ip
string[1, 40]
否
商户侧设备IP，取公网出口IP，支持IPV6
示例值：128.0.0.1
用户终端IP
payer_client_ip
string[1, 40]
否
用户侧设备IP，取公网出口IP，支持IPV6
示例值：128.0.0.1
操作员ID
operator_id
string[1, 32]
否
收银员ID，由商户自定义
示例值：123145
商户门店信息
store_info
object
否
Body 门店信息对象，详细说明见下文
商户门店信息 编号
id
string[1, 32]
否
商户侧门店ID
示例值：0001
名称
name
string[1, 32]
是
商户侧门店名称
示例值：腾讯大厦分店
详细地址
address
string[1, 64]
是
详细的商户门店地址
示例值：广东省深圳市南山区科技中一道10000号
商品详情
detail
array
否
Body 交易购买商品或服务详情，详细说明见下文
填写本参数有助于通过反洗钱和风控检测，并有助于提高支付成功率。
商品详情 商品列表
goods_detail
Array
是
Body 单品信息，使用Json格式
商品列表 商品编码
goods_id
string[1, 32]
是
由半角的大小写字母、数字、中划线、下划线中的一种或几种组成
示例值：商品编码
微信支付商品编码
wxpay_goods_id
string[1, 32]
否
微信支付定义的统一商品编号（没有可不传）
示例值：1001
商品名称
goods_name
string[1, 256]
否
用户购买商品或服务的实际名称
示例值：iPhone6s 16G
商品数量
quantity
int
是
用户购买商品或服务的数量
示例值：1
商品种类
category
string[1, 64]
否
用户购买商品或服务的业务品类或行业分类
示例值： FOOD_BEVERAGE ; 50201700
商品单价
price
int
是
如果商户有优惠，需传输商户优惠后的单价(例如：用户对一笔100元的订单使用了商场发的优惠券100-50，则活动商品的单价应为原单价-50)
示例值：528800
订单原价
cost_price
int
否
1.商户侧一张小票订单可能被分多次支付，订单原价用于记录整张小票的交易金额。 2.当订单原价与支付金额不相等，则不享受优惠。 3.该字段主要用于防止同一张小票分多次支付，以享受多次优惠的情况，正常支付订单不必上传此参数。
示例值：608800
商品小票ID
receipt_id
string[1, 32]
否
商家小票ID
示例值：wx123
请求示例 机构模式
1 {
2 "sp_appid" : "wxdace645e0bc2c424" ,
3 "sp_mchid" : "10000100" ,
4 "sub_mchid" : "20000100" ,
5 "out_trade_no" : "20150806125346" ,
6 "merchant_category_code" : "4111" ,
7 "payer" : {
8 "auth_code" : "134650720866361395"
9 } ,
10 "trade_type" : "MICROPAY" ,
11 "amount" : {
12 "total" : 1 ,
13 "currency" : "HKD"
14 } ,
15 "attach" : "Payment Test" ,
16 "description" : "Image Store - Tencent Building in Shenzhen - QQ Doll" ,
17 "goods_tag" : "1234" ,
18 "detail" : [
19 {
20 "cost_price" : 1 ,
21 "receipt_id" : "1234" ,
22 "goods_detail" : [
23 {
24 "goods_id" : "iphone6s_16G" ,
25 "wxpay_goods_id" : "3405" ,
26 "goods_name" : "iPhone6s 16G" ,
27 "quantity" : 1 ,
28 "price" : 1 ,
29 "category" : "FOOD_BEVERAGE"
30 }
31 ]
32 }
33 ] ,
34 "scene_info" : {
35 "payer_client_ip" : "14.23.150.211" ,
36 "device_ip" : "59.37.125.32" ,
37 "device_id" : "013467007045764" ,
38 "operator_id" : "P001" ,
39 "store_info" : {
40 "id" : "SZTX001" ,
41 "name" : "Tencent Building Branch" ,
42 "address" : "Nanshan District, Shenzhen, Guangdong"
43 }
44 }
45 }
直连模式
1 {
2 "appid" : "wxdace645e0bc2c424" ,
3 "mchid" : "10000100" ,
4 "out_trade_no" : "20150806125346" ,
5 "merchant_category_code" : "4111" ,
6 "payer" : {
7 "auth_code" : "134650720866361395"
8 } ,
9 "trade_type" : "MICROPAY" ,
10 "amount" : {
11 "total" : 1 ,
12 "currency" : "HKD"
13 } ,
14 "attach" : "Payment Test" ,
15 "description" : "Image Store - Tencent Building in Shenzhen - QQ Doll" ,
16 "goods_tag" : "1234" ,
17 "detail" : [
18 {
19 "cost_price" : 1 ,
20 "receipt_id" : "1234" ,
21 "goods_detail" : [
22 {
23 "goods_id" : "iphone6s_16G" ,
24 "wxpay_goods_id" : "3405" ,
25 "goods_name" : "iPhone6s 16G" ,
26 "quantity" : 1 ,
27 "price" : 1 ,
28 "category" : "FOOD_BEVERAGE"
29 }
30 ]
31 }
32 ] ,
33 "scene_info" : {
34 "payer_client_ip" : "14.23.150.211" ,
35 "device_ip" : "59.37.125.32" ,
36 "device_id" : "013467007045764" ,
37 "operator_id" : "P001" ,
38 "store_info" : {
39 "id" : "SZTX001" ,
40 "name" : "Tencent Building Branch" ,
41 "address" : "Nanshan District, Shenzhen, Guangdong"
42 }
43 }
44 }
3. 返回参数
正常返回 微信支付订单号
id
string[1, 32]
是
微信支付订单号 示例值：1217752501201407033233368018
商户号
mchid
string[1, 32]
是
微信支付分配的商户号 注意：仅适用于 直连模式 示例值：1900000109
APPID
appid
string[1, 32]
是
商户在微信公众平台申请服务号对应的APPID 注意：仅适用于 直连模式 示例值：wx8888888888888888
子商户号
sub_mchid
string[1, 32]
是
微信支付分配的子商户号 注意：仅适用于 机构模式 示例值：1900000109
机构商户号
sp_mchid
string[1, 32]
是
微信支付分配的机构商户号 注意：仅适用于 机构模式 示例值：1900000100
机构APPID
sp_appid
string[1, 32]
是
机构在微信公众平台申请服务号对应的APPID 示例值：wx8888888888888888
子商户APPID
sub_appid
string[1, 32]
否
子商户在微信开放平台申请移动应用对应的APPID 示例值：wx8888888888888888
商户订单号
out_trade_no
string[1, 32]
是
返回的商户订单号 示例值：1217752501201407033233368018
交易类型
trade_type
string[1, 16]
是
刷卡支付 示例值：MICROPAY
交易状态
trade_state
string[1, 32]
是
SUCCESS—支付成功 REFUND—转入退款 NOTPAY—未支付 CLOSED—已关闭 REVOKED—已撤销（刷卡支付） USERPAYING--用户支付中 PAYERROR--支付失败(其他原因，如银行返回失败) 示例值：SUCCESS
交易状态描述
trade_state_desc
string[1, 256]
是
对当前订单状态的描述和下一步操作的指引 示例值：支付失败，请重新下单支付
付款银行
bank_type
string[1, 32]
是
银行类型，采用字符串类型的银行标识，值列表详见 银行类型 示例值：CMC
商户数据
attach
string(1, 127)
否
附加数据，在查询API和支付通知中原样返回，该字段主要用于商户携带订单的自定义数据 示例值：自定义数据
支付完成时间
success_time
string[1, 64]
是
订单支付成功时间，格式为rfc3339格式，如2018-06-08T10:34:56+08:00 代表北京时间2018年06月08日10时34分56秒 示例值：2018-06-08T10:34:56+08:00
支付者
payer
object
是
支付者信息，详细说明见下文
支付者 用户标识
openid
string[1, 128]
否
用户在商户appid对应下的唯一标识，需要传appid才有返回
注意：仅适用于 直连模式 示例值：oUpF8uMuAJO_M2pxb1Q9zNjWeS6o
用户标识（机构）
sp_openid
string[1, 128]
否
用户在机构sp_appid对应下的唯一标识，openid和sub_openid可以选传其中之一，如果选择传sub_openid,则必须传sub_appid。下单前需要调用【网页授权】接口获取到用户的openid。
注意：仅适用于 机构模式 示例值：oUpF8uMuAJO_M2pxb1Q9zNjWeS6o
用户标识（子商户）
sub_openid
string[1, 128]
否
用户在子商户sub_appid下用户唯一标识，openid和sub_openid可以选传其中之一，如果选择传sub_openid,则必须传sub_appid。下单前需要调用【网页授权】接口获取到用户的openid，
注意：仅适用于 机构模式 示例值：oUpF8uMuAJO_M2pxb1Q9zNjWeS6o
订单金额
amount
object
是
订单金额信息，详细说明见下文
订单金额 订单金额
total
int
是
订单总金额，币种的最小单位，只能为整数，详见 交易金额 示例值：oUpF8uMuAJO_M2pxb1Q9zNjWeS6o
货币类型
currency
string[1, 16]
否
符合ISO 4217标准的三位字母代码，默认仅支持使用mch_id 对应的结算币种或 CNY，如结算币种为 USD，则currency 可使用 USD 或 CNY. 如需使用非结算币种标价，请联系微信支付的区域运营申请 示例值：CNY
用户支付金额
payer_total
int
是
用户实际支付金额，币种的最小单位，只能为整数，详见 交易金额 示例值：888
支付货币类型
payer_currency
string[1, 16]
否
符合ISO 4217标准的三位字母代码 示例值：888
汇率
exchange_rate
object
否
汇率信息
汇率 汇率类型
type
string[1, 16]
否
SETTLEMENT_RATE,即标价币种和结算币种的汇率 示例值：SETTLEMENT_RATE
汇率值
rate
int
否
rate值是兑换比例乘以10的8次方。 如果标价币种和结算币种一致，兑换比例是1，则rate=100000000； 如果标价币种和结算币种不一致，例如美元兑换人民币的比例为6.5，则rate=650000000
交易金额计算规则：交易金额乘以汇率后，取该币种支持的最小单位，后面全舍。例如交易金额是 1.5USD，美金兑人民币汇率为 7.1238，计算后人民币交易金额为 10.6857，全舍后为 10.68 示例值：80000000
优惠功能
promotion_detail
Object
否
优惠功能信息，详细说明见下文
优惠功能 券ID
promotion_id
string[1, 32]
是
券或者立减优惠id
示例值：109519
优惠名称
name
string[1, 64]
否
优惠名称
示例值：单品惠-6
优惠范围
scope
string[1, 32]
否
GLOBAL：全场代金券 SINGLE：单品优惠
示例值：SINGLE
优惠类型
type
string[1, 32]
否
COUPON- 代金券，需要走结算资金的充值型代金券,（境外商户券币种与支付币种一致） DISCOUNT- 优惠券，不走结算资金的免充值型优惠券，（境外商户券币种与标价币种一致
示例值：DISCOUNT
优惠券面额
amount
int
是
用户享受优惠的金额
示例值：5
货币类型
currency
string[1, 16]
否
符合ISO 4217标准的三位字母代码
示例值：CNY
活动ID
activity_id
string[1, 32]
否
在微信商户后台配置的批次ID
示例值：931386
微信出资
wechatpay_contribute_amount
int
否
特指由微信支付商户平台创建的优惠，出资金额等于本项优惠总金额
示例值：0
商户出资
merchant_contribute_amount
int
否
特指商户自己创建的优惠，出资金额等于本项优惠总金额
示例值：0
其他出资
other_contribute_amount
int
否
其他出资方出资金额
示例值：5
单品列表
goods_detail
Array
是
订单金额信息，详细说明见下文
单品列表 商品编码
goods_id
string[1, 32]
是
由半角的大小写字母、数字、中划线、下划线中的一种或几种组成
示例值：12345
商品备注
goods_remark
string[1, 128]
否
goods_remark为备注字段，按照配置原样返回，字段内容在微信后台配置券时进行设置。
示例值：1001
商品数量
quantity
int
是
用户购买的数量
示例值：1
商品价格
price
int
是
单位为：分。如果商户有优惠，需传输商户优惠后的单价(例如：用户对一笔100元的订单使用了商场发的纸质优惠券100-50，则活动商品的单价应为原单价-50)
示例值：528800
goods_remark为备注字段，按照配置原样返回，goods_tag是订单优惠标记，用于区分订单是否可以享受优惠，两个字段内容都在微信后台配置券时进行设置。
异常返回 返回状态码
code
string[1, 32]
是
错误码，枚举值见错误码列表 示例值：INVALID_REQUEST
返回信息
message
string[1, 256]
是
返回信息，如非空，为错误原因 示例值：参数格式校验错误
详细的错误描述
detail
Object
否
当code为PARAM_ERROR时返回，详细说明见下
详细的错误描述 指示错误参数的位置
field
string[1, 256]
是
当错误参数位于请求body的JSON时，填写指向参数的JSON Pointer 当错误参数位于请求的url或者querystring时，填写参数的变量名
示例值：#/properties/payer
错误参数的值
value
string[1, 256]
是
错误参数的值
示例值：1346177081915535577
具体错误原因
issue
string[1, 256]
是
具体错误原因
示例值：与ALLOF schema不符
错误参数的位置
location
string[1, 256]
否
body：错误参数位于请求body的JSON中 url：错误参数位于请求url中 query：错误参数位于请求的querystring中
示例值：body
返回示例 正常示例
1 {
2 "id" : "1008450740201411110005820873" ,
3 "sp_appid" : "wx2421b1c4370ec43b" ,
4 "sub_appid" : "" ,
5 "sp_mchid" : "10000100" ,
6 "sub_mchid" : "20000100" ,
7 "out_trade_no" : "20150806125346" ,
8 "payer" : {
9 "sp_openid" : "oUpF8uN95-Ptaags6E_roPHg7AG0" ,
10 "sub_openid" : ""
11 } ,
12 "amount" : {
13 "total" : 528800 ,
14 "currency" : "HKD" ,
15 "payer_total" : 518799 ,
16 "payer_currency" : "CNY" ,
17 "exchange_rate" : {
18 "type" : "SETTLEMENT_RATE" ,
19 "rate" : 80000000
20 }
21 } ,
22 "trade_type" : "MICROPAY" ,
23 "trade_status" : "SUCCESS" ,
24 "trade_state_desc" : "Payment successful" ,
25 "bank_type" : "CCB_DEBIT" ,
26 "attach" : "Payment test" ,
27 "success_time" : "2018-06-08T10:34:56+08:00" ,
28 "promotion_detail" : [
29 {
30 "promotion_id" : "109519" ,
31 "name" : "Single-item discount-6" ,
32 "scope" : "SINGLE" ,
33 "type" : "DISCOUNT" ,
34 "amount" : 1 ,
35 "currency" : "CNY" ,
36 "activity_id" : "931386" ,
37 "wechatpay_contribute_amount" : 1 ,
38 "merchant_contribute_amount" : 0 ,
39 "other_contribute_amount" : 0 ,
40 "goods_detail" : [
41 {
42 "goods_id" : "iphone6s_16G" ,
43 "goods_remark" : "Product remarks" ,
44 "quantity" : 1 ,
45 "price" : 528800
46 }
47 ]
48 }
49 ]
50 } 异常示例
1 {
2 "code" : "INVALID_REQUEST" ,
3 "message" : "Parameter format verification error" ,
4 "detail" : {
5 "field" : "#/properties/payer" ,
6 "value" : "1346177081915535577" ,
7 "issue" : "与ALLOF schema不符" ,
8 "location" : "body"
9 }
10 }
4. 错误码 INVALID_REQUEST
无效请求
请根据接口返回的详细错误描述信息检查您的程序
TRADE_ERROR
交易失败
提示用户更换支付方式
SYSTEM_ERROR
系统错误
请用原请求参数再次调用支付接口以确认结果。如果持续返回SYSTEMERROR，请调用撤销接口，并告知用户更换支付方式。
PARAM_ERROR
请求参数错误
请根据接口返回的详细错误描述信息检查您的程序
NOT_ENOUGH
余额不足
提示用户余额不足或更换支付方式
AUTH_CODE_INVALID
付款码无效
请检查是否是微信的付款码。然后更换out_trade_no和付款码后再次发起支付。
