API字典 / 委托代扣 / 扣款結(jié)果通知API

扣款結(jié)果通知API

最新更新時間：2023.10.19 版本說明

扣款完成后，微信會把相關(guān)支付結(jié)果及用戶信息通過數(shù)據(jù)流的形式發(fā)送給商戶。

注意：

● 同樣的通知可能會多次發(fā)送給商戶系統(tǒng)。商戶系統(tǒng)必須能夠正確處理重復(fù)的通知。推薦的做法是，當(dāng)收到通知進(jìn)行處理時，首先檢查對應(yīng)業(yè)務(wù)數(shù)據(jù)的狀態(tài)，判斷該通知是否已經(jīng)處理過，如果沒有處理過再進(jìn)行處理，如果處理過直接返回結(jié)果成功。在對業(yè)務(wù)數(shù)據(jù)進(jìn)行狀態(tài)檢查和處理之前，要采用數(shù)據(jù)鎖進(jìn)行并發(fā)控制，以避免函數(shù)重入造成的數(shù)據(jù)混亂。推薦的做法是，當(dāng)收到通知進(jìn)行處理時，首先檢查對應(yīng)業(yè)務(wù)數(shù)據(jù)的狀態(tài)，判斷該通知是否已經(jīng)處理過，如果沒有處理過再進(jìn)行處理，如果處理過直接返回結(jié)果成功。在對業(yè)務(wù)數(shù)據(jù)進(jìn)行狀態(tài)檢查和處理之前，要采用數(shù)據(jù)鎖進(jìn)行并發(fā)控制，以避免函數(shù)重入造成的數(shù)據(jù)混亂。

● 如果在所有通知頻率(4小時)后沒有收到微信側(cè)回調(diào)，商戶應(yīng)調(diào)用查詢訂單接口確認(rèn)訂單狀態(tài)。

特別提醒：商戶系統(tǒng)對于結(jié)果通知的內(nèi)容一定要做簽名驗(yàn)證，并校驗(yàn)通知的數(shù)據(jù)字段是否與商戶側(cè)的數(shù)據(jù)字段一致，防止數(shù)據(jù)泄漏導(dǎo)致出現(xiàn)“假通知”，造成資金損失。

1. 接口說明

適用對象： 直連模式機(jī)構(gòu)模式

請求URL：簽約結(jié)果通知路徑為簽約接口商戶上傳的success_notify_url字段，解約結(jié)果通知路徑為商戶申請代扣權(quán)限與代扣模板ID時提供的解約回調(diào)地址。必須為https協(xié)議。如果鏈接無法訪問，商戶將無法接收到微信通知。通知url必須為直接可訪問的url，不能攜帶參數(shù)。示例：success_notify_url：“http://www.tg885.com/wxpay/pay.action”

請求方式：POST

2. 通知規(guī)則

扣款完成后，微信會把相關(guān)支付結(jié)果及用戶信息通過數(shù)據(jù)流的形式發(fā)送給商戶，商戶需要接收處理，并按文檔規(guī)范返回應(yīng)答。出于安全的考慮，我們對通知結(jié)果數(shù)據(jù)進(jìn)行了加密，商戶需要先對通知數(shù)據(jù)進(jìn)行解密，才能得到結(jié)果數(shù)據(jù)。

對后臺通知交互時，如果微信收到商戶的應(yīng)答不是成功或超時，微信認(rèn)為通知失敗，微信會通過一定的策略定期重新發(fā)起通知，盡可能提高通知的成功率，但微信不保證通知最終能成功。（通知頻率為15/15/30/180/1800/1800/1800/1800/3600，單位：秒）

3. 通知報文

扣款結(jié)果通知是以POST方法訪問商戶設(shè)置的通知url，通知的數(shù)據(jù)以JSON格式通過請求主體（BODY）傳輸。通知的數(shù)據(jù)包括了加密的支付結(jié)果詳情。

下面詳細(xì)描述證書解密的流程

1、從商戶平臺上獲取商戶的密鑰，記為“key”。
2、針對resource.algorithm中描述的算法（目前為AEAD_AES_256_GCM），取得對應(yīng)的參數(shù)nonce和associated_data。
3、使用key、nonce和associated_data，對數(shù)據(jù)密文resource.ciphertext進(jìn)行解密，得到JSON形式的資源對象

注意：AEAD_AES_256_GCM算法的接口細(xì)節(jié)，請參考rfc5116。微信支付使用的密鑰key長度為32個字節(jié)，隨機(jī)串nonce長度12個字節(jié)，associated_data長度小于16個字節(jié)并可能為空。

4. 請求參數(shù)

參數(shù)名

變量

類型[長度限制]

必填

描述

通知ID

string[1,36]

是

通知的唯一ID
示例值：f7c34059-0f2d-5b32-ba33-a42dks0597c5

通知創(chuàng)建時間

create_time

string[1,64]

是

通知創(chuàng)建的時間，格式為rfc3339格式，如2018-06-08T10:34:56+08:00?代表北京時間2018年06月08日10時34分56秒
示例值：2018-06-08T10:34:56+08:00

通知類型

event_type

string[1,32]

是

通知的類型
簽約成功通知的類型為：PAPAY.SIGN
解約通知類型為：PAPAY.TERMINATE
示例值：PAPAY.SIGN

通知數(shù)據(jù)類型

resource_type

string[1,32]

是

通知的資源數(shù)據(jù)類型，支付成功通知為encrypt-resource
示例值：encrypt-resource

通知數(shù)據(jù)

resource

object

是

通知資源數(shù)據(jù)

參數(shù)名	變量	類型[長度限制]	必填	描述
加密算法類型	algorithm	string[1,32]	是	對支付結(jié)果數(shù)據(jù)進(jìn)行加密的加密算法，目前只支持AEAD_AES_256_GCM 示例值：AEAD_AES_256_GCM
數(shù)據(jù)密文	ciphertext	string[1,1048576]	是	Base64編碼后的支付結(jié)果數(shù)據(jù)密文
附加數(shù)據(jù)	associated_data	string[1,16]	否	加密使用的附加數(shù)據(jù)
隨機(jī)串	nonce	string[1,32]	是	加密使用的隨機(jī)串

收起

5. 通知簽名

加密不能保證通知請求來自微信。微信會對發(fā)送給商戶的通知進(jìn)行簽名，并將簽名值放在通知的HTTP頭Wechatpay-Signature。商戶應(yīng)當(dāng)驗(yàn)證簽名，以確認(rèn)請求來自微信，而不是其他的第三方。簽名驗(yàn)證的算法請參考《微信支付API V3簽名驗(yàn)證》。

簽約與解約結(jié)果通知

{
	"id":"f7c34059-0f2d-5b32-ba33-a42dks0597c5",
	"create_time":"20180225112233",
	"resource_type":"encrypt-resource",
	"event_type":"PAPAY.SIGN",
	"resource" : {
		"algorithm":"AEAD_AES_256_GCM",
		"ciphertext": "...",
		"nonce": "...",
		"associated_data": ""
	}
}

商戶對resource對象進(jìn)行解密后，得到的資源對象示例

場景一：直連模式場景二：服務(wù)商模式/機(jī)構(gòu)模式

{
		"mchid": "10000100",
		"appid": "wx2421b1c4370ec43b",
		"out_trade_no": "20150806125346",
		"transaction_id": "1008450740201411110005820873",
		"attach": "支付測試",
		"trade_type": "AUTH",
		"bank_type": "CCB_DEBIT",
		"success_time": "2018-06-08T10:34:56+08:00",
		"trade_state": "SUCCESS",
		"trade_state_desc": "支付成功",
		"merchant_category_code": "1011",
		"contract_id": "Wx15463511252015071056489715",
		"payer": {
			"openid": "oUpF8uN95-Ptaags6E_roPHg7AG0"
		},
		"amount": {
			"total": 528800,
			"currency": "HKD",
			"payer_total": 518799,
			"payer_currency": "CNY",
			"exchange_rate": {
				"type": "SETTLEMENT_RATE",
				"rate": 8000000
			}
		},
		"promotion_detail": [{
			"promotion_id": "109519",
			"name": "單品惠-6",
			"scope": "SINGLE",
			"type": "DISCOUNT",
			"amount": 1,
			"currency": "HKD",
			"activity_id": "931386",
			"wechatpay_contribute_amount": 1,
			"merchant_contribute_amount": 0,
			"other_contribute_amount": 0,
			"goods_detail": [{
				"goods_id": "iphone6s_16G",
				"goods_remark": "商品備注",
				"quantity": 1,
				"price": 528800
			}]
		}]
}

{
		"sp_mchid": "10000100",
		"sp_appid": "wx2421b1c4370ec43b",
		"sub_mchid": "20000100",
		"out_trade_no": "20150806125346",
		"transaction_id": "1008450740201411110005820873",
		"attach": "支付測試",
		"trade_type": "AUTH",
		"bank_type": "CCB_DEBIT",
		"success_time": "2018-06-08T10:34:56+08:00",
		"trade_state": "SUCCESS",
		"trade_state_desc": "支付成功",
		"merchant_category_code": "1011",
		"contract_id": "Wx15463511252015071056489715",
		"payer": {
			"sp_openid": "oUpF8uN95-Ptaags6E_roPHg7AG0"
		},
		"amount": {
			"total": 528800,
			"currency": "HKD",
			"payer_total": 518799,
			"payer_currency": "CNY",
			"exchange_rate": {
				"type": "SETTLEMENT_RATE",
				"rate": 8000000
			}
		},
		"promotion_detail": [{
			"promotion_id": "109519",
			"name": "單品惠-6",
			"scope": "SINGLE",
			"type": "DISCOUNT",
			"amount": 1,
			"currency": "HKD",
			"activity_id": "931386",
			"wechatpay_contribute_amount": 1,
			"merchant_contribute_amount": 0,
			"other_contribute_amount": 0,
			"goods_detail": [{
				"goods_id": "iphone6s_16G",
				"goods_remark": "商品備注",
				"quantity": 1,
				"price": 528800
			}]
		}]
}

6. 支付成功通知參數(shù)

參數(shù)名

變量

類型[長度限制]

必填

描述

商戶號

mchid

string[1,32]

是

微信支付分配的商戶號
注意：僅適用于直連模式
示例值：1900000109

應(yīng)用ID

appid

string[1,32]

是

商戶號綁定的appid
注意：僅適用于直連模式
示例值：wxcbda96de0b165486

服務(wù)商商戶號

sp_mchid

string[1,32]

是

微信支付分配的機(jī)構(gòu)商戶號
注意：僅適用于機(jī)構(gòu)模式
示例值：10000098

子商戶號

sub_mchid

string[1,32]

是

微信支付分配的子商戶號
注意：僅適用于機(jī)構(gòu)模式
示例值：10000097

服務(wù)商應(yīng)用ID

sp_appid

string[1,32]

是

服務(wù)商綁定的appid
注意：僅適用于機(jī)構(gòu)模式
示例值：wxcbda96de0b165486

子商戶應(yīng)用ID

sub_appid

string[1,32]

否

發(fā)起簽約的子商戶號綁定的appid
注意：僅適用于機(jī)構(gòu)模式
示例值：wxcbda96de0b165484

商戶訂單號

out_trade_no

string[1,32]

是

返回的商戶訂單號
示例值：1217752501201407033233368018

微信支付訂單號

contract_id

string[1,32]

是

微信支付訂單號
示例值：1217752501201407033233368018

商戶數(shù)據(jù)

attach

string[1,127]

否

附加數(shù)據(jù)，在查詢API和支付通知中原樣返回，該字段主要用于商戶攜帶訂單的自定義數(shù)據(jù)
示例值：自定義數(shù)據(jù)

交易類型

trade_type

string[1,16]

是

代扣支付
示例值：AUTH

付款銀行

bank_type

string[1,32]

否

銀行類型
示例值：WPHK：香港錢包支付

支付完成時間

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

交易狀態(tài)

trade_state

string[1,16]

是

枚舉值：
SUCCESS：支付成功
REFUND：轉(zhuǎn)入退款
NOTPAY：未支付
CLOSED：已關(guān)閉
PAYERROR：支付失敗
USERPAYING：用戶支付中
示例值：SUCCESS

支付者

payer

object

否

Body成功時才返回。支付者信息，詳細(xì)說明見下文

參數(shù)名	變量	類型[長度限制]	必填	描述
用戶標(biāo)識（直連商戶）	openid	string[1,128]	是	用戶在商戶appid下的openid 注意：僅適用于直連模式示例值：oUpF8uMuAJO_M2pxb1Q9zNjWeS6a
用戶標(biāo)識（服務(wù)商）	sp_openid	string[1,128]	是	用戶在商戶sp_appid對應(yīng)下的唯一標(biāo)識，需要傳sp_appid才有返回注意：僅適用于機(jī)構(gòu)模式示例值：oUpF8uMuAJO_M2pxb1Q9zNjWeS6o
用戶標(biāo)識（子商戶）	sub_openid	string[1,128]	否	用戶在收單行sub_appid下用戶唯一標(biāo)識，需要傳sub_appid才有返回注意：僅適用于機(jī)構(gòu)模式示例值：oUpF8uMuAJO_M2pxb1Q9zNjWeS6o

收起

訂單金額

amount

object

否

Body成功時才返回。訂單金額信息，詳細(xì)說明見下文

參數(shù)名

變量

類型[長度限制]

必填

描述

訂單金額

total

int

是

訂單總金額，幣種的最小單位，只能為整數(shù)，詳見交易金額
示例值：888

用戶支付金額

payer_total

int

是

用戶實(shí)際支付金額，幣種的最小單位，只能為整數(shù)，詳見交易金額
示例值：888

訂單標(biāo)價幣種

currency

string[1,16]

是

符合ISO 4217標(biāo)準(zhǔn)的三位字母代碼
示例值：CNY

用戶支付幣種

payer_currency

string[1,16]

否

符合ISO 4217標(biāo)準(zhǔn)的三位字母代碼
示例值：HKD

匯率信息

exchange_rate

object

否

Body匯率信息

參數(shù)名	變量	類型[長度限制]	必填	描述
匯率類型	type	string[1,16]	否	枚舉值： SETTLEMENT_RATE：標(biāo)價幣種和結(jié)算幣種的匯率類型 USERPAYMENT_RATE：標(biāo)價幣種和支付幣種的匯率類型示例值：SETTLEMENT_RATE
匯率值	rate	int	否	rate值是兌換比例乘以10的8次方。如果標(biāo)價幣種和結(jié)算幣種一致，兌換比例是1，則rate=100000000；如果標(biāo)價幣種和結(jié)算幣種不一致，例如美元兌換人民幣的比例為6.5，則rate=650000000 示例值：80000000

收起

場景信息

scene_info

object

否

Body成功時才返回。場景信息對象，詳細(xì)說明見下文

參數(shù)名	變量	類型[長度限制]	必填	描述
商戶端設(shè)備	device_id	string[1,32]	否	終端設(shè)備號(商戶自定義，如門店編號) 示例值：013467007045764
商戶端設(shè)備IP	device_ip	string[1,40]	否	商戶側(cè)設(shè)備IP，取公網(wǎng)出口IP，支持IPV6 示例值：128.0.0.1

收起

優(yōu)惠功能

promotion_detail

array

否

Body成功時才返回。優(yōu)惠功能信息，詳細(xì)說明見下文

參數(shù)名

變量

類型[長度限制]

必填

描述

券ID

promotion_id

string[1,32]

是

券或者立減優(yōu)惠id
示例值：109519

優(yōu)惠名稱

name

string[1,64]

否

優(yōu)惠名稱
示例值：單品惠-6

優(yōu)惠范圍

scope

string[1,32]

否

GLOBAL：全場代金券
SINGLE：單品優(yōu)惠
示例值：SINGLE

優(yōu)惠類型

type

string[1,16]

否

COUPON：代金券，需要走結(jié)算資金的充值型代金券,（境外商戶券幣種與支付幣種一致）
DISCOUNT：優(yōu)惠券，不走結(jié)算資金的免充值型優(yōu)惠券，（境外商戶券幣種與標(biāo)價幣種一致
示例值：COUPON

優(yōu)惠券面額

amount

int

是

用戶享受優(yōu)惠的金額
示例值：5

優(yōu)惠幣種

currency

string[1,16]

是

符合ISO 4217標(biāo)準(zhǔn)的三位字母代碼
示例值：HKD

活動ID

activity_id

string[1,32]

否

在微信商戶后臺配置的批次ID
示例值：931386

微信出資

wxpay_contribute_amount

int

否

特指由微信支付商戶平臺創(chuàng)建的優(yōu)惠，出資金額等于本項(xiàng)優(yōu)惠總金額
示例值：5

商戶出資

merchant_contribute_amount

int

否

特指商戶自己創(chuàng)建的優(yōu)惠，出資金額等于本項(xiàng)優(yōu)惠總金額
示例值：5

其他出資

other_contribute_amount

int

否

其他出資方出資金額
示例值：5

單品列表

goods_detail

array

否

成功時才返回。優(yōu)惠功能信息，詳細(xì)說明見下文

參數(shù)名	變量	類型[長度限制]	必填	描述
商品編碼	goods_id	string[1,32]	是	由半角的大小寫字母、數(shù)字、中劃線、下劃線中的一種或幾種組成示例值：124512
商品備注	goods_remark	string[1,128]	否	goods_remark為備注字段，按照配置原樣返回，字段內(nèi)容在微信后臺配置券時進(jìn)行設(shè)置示例值：1001
商品優(yōu)惠金額	discount_amount	int	是	單品的總優(yōu)惠金額示例值：100
商品數(shù)量	quantity	int	是	用戶購買的數(shù)量示例值：1
商品價格	price	int	是	單位為：分。如果商戶有優(yōu)惠，需傳輸商戶優(yōu)惠后的單價示例值：528800

收起

7. 通知應(yīng)答

接收成功：HTTP應(yīng)答狀態(tài)碼需返回200或204，無需返回應(yīng)答報文。

接收失敗：HTTP應(yīng)答狀態(tài)碼需返回5XX或4XX，同時需返回應(yīng)答報文，格式如下：

注意：重試過多會導(dǎo)致微信支付端積壓過多通知而堵塞，影響其他正常通知。

參數(shù)名	變量	類型	必填	描述
返回狀態(tài)碼	code	string[1,32]	是	詳見下面返回狀態(tài)碼說明示例值：SUCCESS
返回信息	message	string[1,256]	否	返回信息，為錯誤原因示例值：系統(tǒng)錯誤

場景一：成功示例場景二：失敗示例

200
{
	"code": "SUCCESS",
	"message": "OK"
}

{
    "code": "SYSTEM_ERROR",
    "message": "系統(tǒng)失敗"
}

語言

頁面導(dǎo)航

视频一区二区三区自拍_千金肉奴隷1985未删减版在线观看_国产成人黄色视频在线播放_少女免费播放片高清在线观看_国产精品v欧美精品v

WeChat Pay

Feedback

Feedback

Submitted successfully

Feedback

Network exception, please try again later

支付產(chǎn)品

資金類產(chǎn)品

其他產(chǎn)品

扣款結(jié)果通知API

1. 接口說明

2. 通知規(guī)則

3. 通知報文

4. 請求參數(shù)

5. 通知簽名

商戶對resource對象進(jìn)行解密后，得到的資源對象示例

6. 支付成功通知參數(shù)

7. 通知應(yīng)答

版本說明