微信支付-跨境开发者中心

1. 接口说明

适用对象:直连模式机构模式

请求URL: https://apihk.mch.weixin.qq.com/v3/global/micropay/transactions/pay

请求方式: POST

频率限制:150qps

Path指该参数为路径参数

Query指该参数为URL参数

Body指该参数需在请求JSON传参

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]

是

BodyMICROPAY：刷卡支付
示例值：MICROPAY

指定支付方式

limit_pay

string[1, 32]

否

Bodyno_credit：指定不能使用信用卡支付
示例值：no_credit

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标准的三位字母代码示例值：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优惠功能信息，详细说明见下文

参数名

变量

类型[长度限制]

必填

描述

订单原价

cost_price

int

否

1.商户侧一张小票订单可能被分多次支付，订单原价用于记录整张小票的交易金额。
2.当订单原价与支付金额不相等，则不享受优惠。
3.该字段主要用于防止同一张小票分多次支付，以享受多次优惠的情况，正常支付订单不必上传此参数。
示例值：608800

商品小票ID

receipt_id

string[1, 32]

否

商家小票ID
示例值：wx123

单品列表

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
商品单价	price	int	是	如果商户有优惠，需传输商户优惠后的单价(例如：用户对一笔100元的订单使用了商场发的优惠券100-50，则活动商品的单价应为原单价-50) 示例值：528800

收起

请求示例

机构模式直连模式


{
	"sp_appid": "wxdace645e0bc2c424",
	"sp_mchid": "10000100",
	"sub_mchid": "20000100",
	"out_trade_no": "20150806125346",
	"merchant_category_code": "4111",
	"payer": {
		"auth_code": "134650720866361395"
	},
	"trade_type": "MICROPAY",
	"amount": {
		"total": 1,
		"currency": "HKD"
	},
	"attach": "Payment Test",
	"description": "Image Store - Tencent Building in Shenzhen - QQ Doll",
	"goods_tag": "1234",
	"limit_pay": "no_credit",
	"detail": [{
		"cost_price": 1,
		"receipt_id": "1234",
		"goods_detail": [{
			"goods_id": "iphone6s_16G",
			"wxpay_goods_id": "3405",
			"goods_name": "iPhone6s 16G",
			"quantity": 1,
			"price": 1
		}]
	}],
	"scene_info": {
		"payer_client_ip": "14.23.150.211",
		"device_ip": "59.37.125.32",
		"device_id": "013467007045764",
		"operator_id": "P001",
		"store_info": {
			"id": "SZTX001",
			"name": "Tencent Building Branch",
			"address": "Nanshan District, Shenzhen, Guangdong"
		}
	}
}


{
	"appid": "wxdace645e0bc2c424",
	"mchid": "10000100",
	"out_trade_no": "20150806125346",
	"merchant_category_code": "4111",
	"payer": {
		"auth_code": "134650720866361395"
	},
	"trade_type": "MICROPAY",
	"amount": {
		"total": 1,
		"currency": "HKD"
	},
	"attach": "Payment Test",
	"description": "Image Store - Tencent Building in Shenzhen - QQ Doll",
	"goods_tag": "1234",
	"limit_pay": "no_credit",
	"detail": [{
		"cost_price": 1,
		"receipt_id": "1234",
		"goods_detail": [{
			"goods_id": "iphone6s_16G",
			"wxpay_goods_id": "3405",
			"goods_name": "iPhone6s 16G",
			"quantity": 1,
			"price": 1
		}]
	}],
	"scene_info": {
		"payer_client_ip": "14.23.150.211",
		"device_ip": "59.37.125.32",
		"device_id": "013467007045764",
		"operator_id": "P001",
		"store_info": {
			"id": "SZTX001",
			"name": "Tencent Building Branch",
			"address": "Nanshan District, Shenzhen, Guangdong"
		}
	}
}


									{
										"stock_id": ".NET",
										"limit": 10,
									}


									{
										"stock_id": "Python",
										"stock_creator_mchid": "123456",
										"limit": 10,
									}

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标准的三位字母代码。
示例值：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 示例值：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

单品列表

amount

object

是

订单金额信息，详细说明见下文

参数名	变量	类型[长度限制]	必填	描述
商品编码	goods_id	string[1, 32]	是	由半角的大小写字母、数字、中划线、下划线中的一种或几种组成示例值：12345
商品备注	goods_remark	string[1, 128]	否	goods_remark为备注字段，按照配置原样返回，字段内容在微信后台配置券时进行设置。示例值：1001
商品数量	quantity	int	是	用户购买的数量示例值：1
商品价格	price	int	是	单位为：分。如果商户有优惠，需传输商户优惠后的单价(例如：用户对一笔100元的订单使用了商场发的纸质优惠券100-50，则活动商品的单价应为原单价-50) 示例值：528800
商户端设备号	device_id	string[1, 32]	否	终端设备号(商户自定义，如门店编号) 示例值：013467007045764

收起

注意

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

收起

返回示例

正常示例异常示例


{
	"sp_appid": "wxdace645e0bc2c424",
	"sp_mchid": "10000100",
	"sub_mchid": "20000100",
	"out_trade_no": "20150806125346",
	"merchant_category_code": "4111",
	"payer": {
		"auth_code": "134650720866361395"
	},
	"trade_type": "MICROPAY",
	"amount": {
		"total": 1,
		"currency": "HKD"
	},
	"attach": "Payment Test",
	"description": "Image Store - Tencent Building in Shenzhen - QQ Doll",
	"goods_tag": "1234",
	"limit_pay": "no_credit",
	"promotion_detail": [{
		"cost_price": 1,
		"receipt_id": "1234",
		"goods_detail": [{
			"goods_id": "iphone6s_16G",
			"wxpay_goods_id": "3405",
			"goods_name": "iPhone6s 16G",
			"quantity": 1,
			"price": 1
		}]
	}],
	"scene_info": {
		"payer_client_ip": "14.23.150.211",
		"device_ip": "59.37.125.32",
		"device_id": "013467007045764",
		"operator_id": "P001",
		"store_info": {
			"id": "SZTX001",
			"name": "Tencent Building Branch",
			"address": "Nanshan District, Shenzhen, Guangdong"
		}
	}
}

 
{
	"code": "INVALID_REQUEST",
	"message": "Parameter format verification error",
	"detail": {
		"field": "#/properties/payer",
		"value": "1346177081915535577",
		"issue": "与ALLOF schema不符",
		"location": "body"
	}
}

4. 错误码

错误码	描述	解决方案
INVALID_REQUEST	无效请求	请根据接口返回的详细错误描述信息检查您的程序
TRADE_ERROR	交易失败	提示用户更换支付方式
SYSTEM_ERROR	系统错误	请用原请求参数再次调用支付接口以确认结果。如果持续返回SYSTEMERROR，请调用撤销接口，并告知用户更换支付方式。
PARAM_ERROR	请求参数错误	请根据接口返回的详细错误描述信息检查您的程序
NOT_ENOUGH	余额不足	提示用户余额不足或更换支付方式
AUTH_CODE_INVALID	付款码无效	请检查是否是微信的付款码。然后更换out_trade_no和付款码后再次发起支付。

WeChat Pay

Feedback

Feedback

Submitted successfully

Feedback

Network exception, please try again later

支付产品

资金类产品

其他产品

提交付款码支付

1. 接口说明

2. 请求参数

请求示例

3. 返回参数

正常返回

异常返回

返回示例

4. 错误码