掃碼支付API接口說明文檔

.掃碼支付API接口開發(fā)指南商戶接口規(guī)版本(3.0.7)修訂時(shí)間：2021-08-01目錄第一章文檔描述21、文檔說明22、閱讀對象23、名詞定義2第二章接口定義21、掃碼支付22、公眾號支付23、支付異步通知94、交易查詢115、對賬查詢13第三章簽名說明141、簽名算法142、密鑰生產(chǎn)15附錄1錯(cuò)誤碼說明151.第一章文檔描述1、文檔說明本說明文檔用于指導(dǎo)商戶接入掃碼支付API系統(tǒng)進(jìn)展的對接，目前支持支付寶、微信掃碼。請相關(guān)技術(shù)人員詳細(xì)閱讀本文檔。2、閱讀對象商戶開發(fā)人員。掃碼支付API接口相關(guān)技術(shù)人員。3、名詞定義合作方：指對接掃碼支付平臺的機(jī)構(gòu)。商戶：指委托收單的營業(yè)機(jī)構(gòu)，如超市、便利店等。用戶：指在商戶系統(tǒng)進(jìn)展消費(fèi)的企業(yè)或者個(gè)人。商戶ID：指支付系統(tǒng)為使用外部接入接口的商戶統(tǒng)一分配的唯一標(biāo)識。商戶密鑰：指商戶在和支付系統(tǒng)進(jìn)展數(shù)據(jù)簽名認(rèn)證的密鑰，采用RSA加密算法。第二章接口定義1、掃碼支付1、接入U(xiǎn)RL：118.178.126.35:8088/payservice/pay/smzf2、接入方式：POST方式均可3、請求協(xié)議參數(shù)：參數(shù)名 參數(shù) 數(shù)據(jù)類型 必填 說明1.訂單IDorderIdVARCHARY交易訂單ID支付通道：W*ZF-微信支付，支付通道payTypeVARCHARYZFBZF-支付寶支付merchantCo商戶編碼，接入時(shí)系統(tǒng)分配商戶編碼VARCHARYde交易金額，單位：元，最小2交易金額totalAmountVARCHARY元交易標(biāo)題，顯示在微信或支付交易標(biāo)題subjectVARCHARY寶支付頁面交易描述descVARCHARY交易描述商戶操作員idoperatorIdVARCHARN操作員編號，如員工編碼門店編號storeIdVARCHARN商戶的門店編號商戶終端編號terminalIdVARCHARY商戶機(jī)器的終端編號微信/支付寶：1-不能使用信用卡支付方式limitPayVARCHARN支付寶：2-不適用花唄3-不使用信用卡/花唄支付寶分配給下游的pid識別號，2088開頭的一串16位數(shù)來源信息sourceVARCHARN字,對應(yīng)支付寶的sys_service_provider_id字段微信渠道可選上送，代金券或立減優(yōu)惠功能參數(shù)，對應(yīng)微信商品標(biāo)記goodsTagVARCHARN的goods_tag字段支付寶目前用不到該參數(shù)。支付有效時(shí)間e*pireTimeVARCHARN指定訂單的支付有效時(shí)間〔分1.鐘數(shù)〕，超過有效時(shí)間用戶將無法支付。假設(shè)不指定該參數(shù)則系統(tǒng)默認(rèn)設(shè)置24小時(shí)支付有效時(shí)間。參數(shù)允許設(shè)置圍：1-1440區(qū)間的整數(shù)值，超過1440默認(rèn)設(shè)置1440支付寶：用戶掃碼后開場計(jì)算支付有效時(shí)間微信：用戶下單后開場計(jì)算支付有效時(shí)間回調(diào)通知地址notifyurlVARCHARY支付成功失敗的通知地址交易終端ipcreateipVARCHARY交易終端IP備注e*tend1VARCHARN備注信息，測試系統(tǒng)必填簽名signVARCHARYRSA簽名4、返回協(xié)議參數(shù)：參數(shù)名參數(shù)數(shù)據(jù)類型必填說明返回的錯(cuò)誤碼，000000代表返回狀態(tài)rspCodeVARCHARY成功，其它為失敗返回信息rspMsgVARCHARY返回信息訂單的二維碼，商戶生成二維二維碼qrCodeVARCHARY碼提供給用戶掃碼支付簽名signVARCHARYRSA簽名5、接請求入提交方法：{"payType":"ZFBZF","orderId":"WE1124567810","merchantCode":","totalAmount":"2",1."subject":"firsttest","desc":"testproduct","body":"testproduct","terminalId":"1213412134","e*tend1":"test","notifyurl":"118.178.126.35:8088/payservice/pay/notifytestsucc","createip":"192.168.0.1"}返回值：{"rspCode":"000000","rspMsg":"OK","qrCode":"s://qr.alipay./ba*02559bawzwz2erezj00d4","sign":"Ek7H4c6f5OgechohLFr*cgPoGC/vVy0Bg5*DzYGVIReHYaFtEBfSU*hS*Cf/rDMhM+DZKJaw5jhTU1mE1ijEQoguj6c6gKDSg6f*uEEwbKODlQDW9cHRF*MVki2THe*o*/g8KgipUiEW5HOdNNm4LcwQe8YC+8gauHcKE*SW7Rw="}2、公眾號支付1、接入U(xiǎn)RL：118.178.126.35:8088/payservice/pay/pn2、接入方式：POST方式均可3、請求協(xié)議參數(shù)：參數(shù)名參數(shù)數(shù)據(jù)類型必填說明訂單IDorderIdVARCHARY交易訂單ID支付通道payTypeVARCHARY支付通道：W*ZF-微信支付merchantCo商戶編碼，接入時(shí)系統(tǒng)分配商戶編碼VARCHARYde交易金額totalAmountVARCHARY交易金額，單位：元，最小21.元交易標(biāo)題，顯示在微信或支付交易標(biāo)題subjectVARCHARY寶支付頁面交易描述descVARCHARY交易描述商戶操作員idoperatorIdVARCHARN操作員編號，如員工編碼門店編號storeIdVARCHARN商戶的門店編號商戶終端編號terminalIdVARCHARY商戶機(jī)器的終端編號微信/支付寶：1-不能使用信用卡支付方式limitPayVARCHARN支付寶：2-不適用花唄3-不使用信用卡/花唄微信渠道可選上送，代金券或立減優(yōu)惠功能參數(shù)，對應(yīng)微信商品標(biāo)記goodsTagVARCHARN的goods_tag字段支付寶目前用不到該參數(shù)。指定訂單的支付有效時(shí)間〔分鐘數(shù)〕，超過有效時(shí)間用戶將無法支付。假設(shè)不指定該參數(shù)則系統(tǒng)默認(rèn)設(shè)置24小時(shí)支付有效時(shí)間。參數(shù)允許設(shè)置圍：支付有效時(shí)間e*pireTimeVARCHARN1-1440區(qū)間的整數(shù)值，超過1440默認(rèn)設(shè)置1440支付寶：用戶掃碼后開場計(jì)算支付有效時(shí)間微信：用戶下單后開場計(jì)算支付有效時(shí)間回調(diào)通知地址notifyurlVARCHARY支付成功失敗的通知地址1.交易終端ipcreateipVARCHARY交易終端IP支付成功跳轉(zhuǎn)路徑；form表單跳轉(zhuǎn)路徑callbackUrlVARCHARN形式提交商戶后臺；子商戶公眾號標(biāo)識subAppIdVARCHARY子商戶公眾號標(biāo)識子商戶公眾號下關(guān)子商戶公眾號下關(guān)注的用戶subOpenIdVARCHARY注的用戶openidopenid微信子商戶號w*SubMchIdVARCHARN微信支付分配的子商戶號是否開具電子發(fā)票receiptVARCHARN是否開具電子發(fā)票1:原生公眾號(返回json串給是否原生公眾號isRawVARCHARYjsapi拉起支付)備注e*tend1VARCHARN備注信息，測試系統(tǒng)必填簽名signVARCHARYRSA簽名4、返回協(xié)議參數(shù)：參數(shù)名參數(shù)數(shù)據(jù)類型必填說明返回的錯(cuò)誤碼，000000代表返回狀態(tài)rspCodeVARCHARY成功，其它為失敗返回信息rspMsgVARCHARY返回信息"payCode":"{\"sign\":\"D9F4C32B8F20D348DDFA85C95B291E55\",\"timestamp\":\"1476774382\",\"noncestr\":\"368c7e90e49948支付碼信息payCodeVARCHARY4e901edbbd501a8dd9\",\"partnerid\":\"15233133\",\"prepayid\":\"w*33454fd6f1dc\",\"package\":\"Sign=W*Pay\",\"appid\":\"w*b5d8ad7674532882\"}")簽名signVARCHARYRSA簽名1.請求提交方法：{"payType":"ZFBZF","orderId":"WE1124567810","merchantCode":","totalAmount":"2","subject":"firsttest","body":"testproduct","terminalId":"1213412134","e*tend1":"test",6.35:8088/payservice/pay/notifytestsucc","createip":"192.168.0.1"callbackUrl":"118.178.126.35:8088/payservice/pay/callbackurl"subAppId":"w*a3dbb6050f553164"subOpenId":"9efi3dbb6050f653164"}返回值：{"rspCode":"000000","rspMsg":"OK","payCode":{"timeStamp":"74","signType":"MD5","package":"prepay_id=w*2657a0","paySign":"6B0EEA6AE668593A6A290F8247CE46B7","nonceStr":"05571626a6f6415f8cb11c91e64b8450","appId":"w*a3dbb6050f353164"}，"sign":"Ek7H4c6f5OgechohLFr*cgPoGC/vVy0Bg5*DzYGVIReHYaFtEBfSU*hS*Cf/rD1.MhM+DZKJaw5jhTU1mE1ijEQoguj6c6gKDSg6f*uEEwbKODlQDW9cHRF*MVki2THe*o*/g8KgipUiEW5HOdNNm4LcwQe8YC+8gauHcKE*SW7Rw="}3、支付異步通知1、接入U(xiǎn)RL：過程1中請求參數(shù)notifyurl值2、接入方式：POST方式3、通知請求協(xié)議參數(shù)：參數(shù)名參數(shù)數(shù)據(jù)類型必填說明訂單號orderidVARCHARY商戶請求訂單號商戶編碼merchantidVARCHARY商戶編碼交易金額totalAmountVARCHARY交易金額，單位：元交易成功時(shí)間payTimeVARCHARY支付成功的時(shí)間交易狀態(tài)：INIT-初始化SUCCESS-成功交易狀態(tài)trade_stateVARCHARYUSERPAYING-等待用戶支付NOTPAY-未支付ERROR-支付失敗transcation_i支付系統(tǒng)部交易號支付系統(tǒng)訂單號VARCHARYd簽名signVARCHARYRSA簽名4、返回協(xié)議參數(shù)：參數(shù)名參數(shù)數(shù)據(jù)類型必填說明返回的錯(cuò)誤碼，000000代表返回狀態(tài)rspCodeVARCHARY成功，其它為失敗。返回成功后，將不會再次通知。返回信息rspMsgVARCHARY返回信息簽名signVARCHARYRSA簽名1.5、接入實(shí)例：請求提交方法：{"orderid":"WE1124567810","merchantid":","totalAmount":"2","payTime":"433",trade_state":"SUCCESS","transcation_id":"BJ55124",}返回值：{"rspCode":"000000","rspMsg":"OK","sign":"Ek7H4c6f5OgechohLFr*cgPoGC/vVy0Bg5*DzYGVIReHYaFtEBfSU*hS*Cf/rDMhM+DZKJaw5jhTU1mE1ijEQoguj6c6gKDSg6f*uEEwbKODlQDW9cHRF*MVki2THe*o*/g8KgipUiEW5HOdNNm4LcwQe8YC+8gauHcKE*SW7Rw="}6、特別說明：①支付異步通知過程在整個(gè)支付流程中一定存在。商戶系統(tǒng)在收到異步通知過程后，需向接口返回rspCode為“000000〞。支付接口根據(jù)該返回值判斷商戶系統(tǒng)是否已經(jīng)收到結(jié)果。假設(shè)返回結(jié)果不是“000000〞，支付系統(tǒng)會再次反復(fù)向notifyurl發(fā)送結(jié)果，直到商戶返回“000000〞或者到達(dá)重復(fù)發(fā)送次數(shù)。②當(dāng)支付系統(tǒng)在異步通知過程中返回在線支付結(jié)果時(shí)，商戶系統(tǒng)在收到數(shù)據(jù)后，應(yīng)該通過sign值判斷是否是有效的返回?cái)?shù)據(jù)，防止數(shù)據(jù)在網(wǎng)絡(luò)傳輸過程中被惡意篡改。7、本卷須知①在收到支付接口訂單下行異步通知結(jié)果時(shí)，商戶系統(tǒng)需首先驗(yàn)證訂單通知的合法性，如果不合法，則不要更新商戶系統(tǒng)上的訂單狀態(tài)。1.②商戶系統(tǒng)訂單狀態(tài)和訂單實(shí)際金額務(wù)必以此次接口訂單異步通知的結(jié)果為準(zhǔn)。③商戶系統(tǒng)在成功提交訂單后，在未沒有收到此接口異步通知結(jié)果時(shí)，請不要更新商戶系統(tǒng)上的訂單狀態(tài)④在交易異步通知過程中商戶系統(tǒng)返回結(jié)果值rspCode“00000〞回支付接口時(shí)，“000000〞并不是將支付接口在交易異步通知的結(jié)果原樣返回。商戶系統(tǒng)返回值“000000〞時(shí)表示商戶系統(tǒng)已經(jīng)成功接收到了結(jié)果〔不管結(jié)果是什么，總之是收到了〕，而其他值表示因?yàn)?些原因商戶系統(tǒng)并不認(rèn)為支付接口的返回是有效的。支付接口在收到商戶系統(tǒng)的返回后，如果返回的值為“000000〞支付接口將不再次發(fā)送結(jié)果，否則支付接口會根據(jù)同商戶的約定再次發(fā)送結(jié)果。4、交易查詢1、接入U(xiǎn)RL：118.178.126.35:8088/payservice/pay/query2、接入方式：POST方式，JSON格式3、請求協(xié)議參數(shù)：參數(shù)名參數(shù)數(shù)據(jù)類型必填說明訂單號orderIdVARCHARY商戶請求訂單號merchantCo商戶編碼商戶編碼VARCHARYde簽名signVARCHARYRSA簽名4、返回協(xié)議參數(shù)：參數(shù)名參數(shù)數(shù)據(jù)類型必填說明返回的錯(cuò)誤碼，000000代表返回值rspCodeVARCHARY成功，其它為失敗返回信息rspMsgVARCHARY返回信息訂單號orderIdVARCHARY商戶請求訂單號支付通道payTypeVARCHARY支付通道交易金額totalAmountVARCHARY交易金額交易時(shí)間orderTimeVARCHARY訂單生成時(shí)間交易狀態(tài)statusVARCHARY交易狀態(tài)：1.INIT-初始化USERPAYING-等待用戶支付SUCCESS-成功NOTPAY-未支付ERROR-支付失敗交易標(biāo)題，顯示在微信或支付交易標(biāo)題subjectVARCHARY寶支付頁面交易描述descVARCHARY交易描述門店編號storeIdVARCHARY門店編號終端編號terminalIdVARCHARY終端編號簽名signVARCHARYRSA簽名5、接入實(shí)例：請求提交方法：{"orderId":"WE1124567810","merchantCode":",}返回值：{"rspCode":"000000","rspMsg":"OK","orderId":"WE1124567810","payType":"ZFBZF","totalAmount":"2","status":"SUCCESS","subject":"firsttest","desc":"testproduct","storeid":"333333","terminalId":"1213412134"1.}5、對賬查詢1、接入U(xiǎn)RL：118.178.126.35:8088/payservice/pay/settlement2、接入方式：POST方式3、請求協(xié)議參數(shù)：參數(shù)名參數(shù)數(shù)據(jù)類型必填說明merchantCo商戶編碼商戶編碼VARCHARYde對賬日期settleDateVARCHARY對賬日期簽名signVARCHARYRSA簽名4、返回協(xié)議參數(shù)：參數(shù)名參數(shù)數(shù)據(jù)類型必填說明返回的錯(cuò)誤碼，000000代表返回值rspCodeVARCHARY成功，其它為失敗返回信息rspMsgVARCHARY返回信息對賬單contentVARCHARY對賬單容簽名signVARCHARYRSA簽名5、對賬單格式：請求提交方法：hzf001||87623|950|2.00|20210811|S|000000|success|0.00|ZFBZF|0|*1|每個(gè)字段以“|〞分割,字段含義參見下表對賬流水只包含狀態(tài)為成功的交易域字段名稱類型要求備注1agentNumVARCHAR(32)M代理商編號2merchantCodeVARCHAR(32)M商戶編號3transcationIdVARCHAR(32)M平臺流水號4orderIdVARCHAR(32)M代理商請求訂單號5amountNumberic(1M交易金額〔保存兩位〕2,2)6settleDateCHAR(8)M對賬日期1.respTyperespCode9respMsg

CHAR(1)MS成功;CHAR(6)M響應(yīng)碼VARCHAR(25O響應(yīng)描述6)10feeNumberic(1M商戶手續(xù)費(fèi)〔保存兩位〕2,2)11payWayVARCHAR(3M2)12storeIdVachar2(32)0商戶的門店編號13terminalIdVachar2(32)0商戶機(jī)具終端編號6、接入實(shí)例：請求提交方法：{"merchantCode":","settleDate":"20210624",}返回值：{"rspCode":"000000","rspMsg":"OK","content":"hzf001||87623|950|2.00|20210811|S|000000|success|0.00|ZFBZF|0|*1|",}第三章簽名說明1、簽名算法為了保證網(wǎng)絡(luò)數(shù)據(jù)的傳輸平安，防止數(shù)據(jù)在傳輸過程中被截取、篡改等，在調(diào)用API時(shí)雙方約定使用S和RSA加密算法對通訊數(shù)據(jù)進(jìn)展加解密處理。RSA通用加密算法，加密后需要轉(zhuǎn)換為Base64，解密前需要將Base64加密串轉(zhuǎn)換為RSA的字節(jié)數(shù)組。RSA簽名算法描述如下:1.1：將所有參數(shù)名稱〔不包含sign本身〕按照字母順序排序，從a-z