支付接口 · xxpaypro安裝部署教程

# 支付接口 ## 1. 統一下單 > 接口描述業務通過統一下單接口可以發起任意三方支付渠道的支付訂單。業務系統不必關心該如何調用三方支付，統一下單接口會根據業務系統選擇的支付渠道ID，選擇對應支付渠道的支付產品，發起下單請求，然后響應給業務系統支付請求所需參數。 > 接口鏈接 URL地址：{payUrl}/pay/create\_order > 請求參數字段名變量名必填類型示例值描述商戶IDmchId是String(30)20001222支付中心分配的商戶號應用IDappId否String(30)cbsgB1T0SL6tfflFYoBX商戶應用ID支付產品IDproductId是String(24)8001商戶訂單號mchOrderNo是String(30)20160427210604000490商戶生成的訂單號支付金額amount是int100支付金額,單位分幣種currency是String(3)cny三位貨幣代碼,人民幣:cny客戶端IPclientIp否String(32)210.73.10.148客戶端IP地址設備device否String(64)ios10.3.1客戶端設備異步回調地址notifyUrl是String(128)<http://shop.xx.com/notify.htm>支付結果異步回調URL同步請求地址returnUrl否String(128)<http://shop.xx.com/return.htm>支付結果同步請求URL商品主題subject是String(64)xxpay測試商品1商品主題商品描述信息body是String(256)xxpay測試商品描述商品描述信息支付通道子賬戶IDpayPassAccountId否String(256)指定通道子賬號ID指定通道子賬號ID附加參數extra否String(512){“openId”:”o2RvowBf7sOVJf8kJksUEMceaDqo”}特定渠道發起時額外參數擴展參數1param1否String(64)支付中心回調時會原樣返回擴展參數2param2否String(64)支付中心回調時會原樣返回請求時間reqTime是String(30)20190723141000請求接口時間， yyyyMMddHHmmss格式接口版本version是String(3)1.0接口版本號，固定：1.0簽名sign是String(32)C380BEC2BFD727A4B6845133519F3AD6簽名值，詳見簽名算法> 響應結果字段名變量名必填類型示例值描述返回狀態碼retCode是String(16)00-處理成功，其他-處理有誤，詳見錯誤碼返回信息retMsg否String(128)簽名失敗具體錯誤原因，例如：簽名失敗、參數格式校驗錯誤##### 以下字段在retCode=0 時有返回字段名變量名必填類型示例值描述支付訂單號payOrderId是String(30)P01201907231119090520000返回支付系統訂單號支付方式payMethod是String(16)formJump支付方式，目前包含兩種： formJump-表單跳轉，codeImg-二維碼圖片，wxApp-微信app支付，alipayApp-支付寶app支付，wxJSApi-微信公眾號支付支付表單地址payUrl否text……payMethod=formJump時存在該參數；一般為支付表單內容支付跳轉地址payJumpUrl否text支付跳轉地址，可直接重定向的URL表單提交方式payAction否String(16)GET指定表單提交方式: POST/GET二維碼地址codeUrl否String(16)<https://qr.alipay.com/bax08687odiyi06c>payMethod=codeImg時存在該參數；二維碼內容地址二維碼圖片地址codeImgUrl否String(16)[http://pay.xxpay.org/api/qrcode\_img\_get?url=https://qr.alipay.com/bax08687z006c&width=200&height=200](http://pay.xxpay.org/api/qrcode_img_get?url=https://qr.alipay.com/bax08687z006c&width=200&height=200)payMethod=codeImg時存在該參數；二維碼圖片地址支付自定義參數payParams否String(16)支付自定義參數，當payMethod為支付寶app、微信app或微信公眾號支付時，該參數有值，取appStr字段是否需要查單needQuery否Booleantrue如果返回true則表示商戶需要主動發起訂單查詢當前訂單狀態orderStatus否String(16)2當前訂單狀態: -2:訂單已關閉,0-訂單生成,1-支付中,2-支付成功,3-業務處理完成,4-已退款（2和3都表示支付成功,3表示支付平臺回調商戶且返回成功后的狀態）簽名信息sign是String(128)CCD9083A6DAD9A2DA9F668C3D4517A84簽名信息> 響應數據示例 URL方式響應數據： ``` <pre class="calibre25">``` { "payJumpUrl": "http://170.33.8.116:8182/payurl?mchOrderId=Pnull202011171714049724732&amount=686.00", "payMethod": "formJump", "payUrl": "<script>window.location.href = http://170.33.8.116:8182/payurl?mchOrderId=Pnull202011171714049724732&amount=686.00</script>", "retCode": "0", "sign": "3251661E4B84AAB6BAA1A6A025F40036" } ``` ``` APP支付時響應數據： ``` <pre class="calibre25">``` { "payMethod": "alipayApp", "payParams": { "appStr": "trade_no=2020111704200341411064884895&biz_sub_type=peerpay_trade&presessionid=&app=tb&channel=&type2=gulupay&bizcontext={\"biz_type\":\"share_pp_pay\",\"type\":\"qogirpay\"}" }, "retCode": "0", "sign": "6734227C78A110D7F9BF94BB9A217D3E" } ``` ``` ## 2. 查詢支付訂單 > 接口描述業務系統通過查詢支付訂單接口獲取最新的支付訂單狀態，并根據狀態結果進一步處理業務邏輯。 > 接口鏈接 URL地址：{payUrl}/pay/query\_order > 請求參數字段名變量名必填類型示例值描述商戶IDmchId是String(30)1000000010支付中心分配的商戶號支付訂單號payOrderId是String(30)P20160427210604000490支付中心生成的訂單號，與mchOrderNo二者傳一即可商戶訂單號mchOrderNo是String(30)20160427210604000490商戶生成的訂單號，與payOrderId二者傳一即可是否執行回調executeNotify否Booleantrue是否執行回調，如果為true，則支付中心會再次向商戶發起一次回調，如果為false則不發起請求時間reqTime是String(30)20190723141000請求接口時間， yyyyMMddHHmmss格式接口版本version是String(3)1.0接口版本號，固定：1.0簽名sign是String(32)C380BEC2BFD727A4B6845133519F3AD6簽名值，詳見簽名算法> 響應結果字段名變量名必填類型示例值描述返回狀態碼retCode是String(16)00-處理成功，其他-處理有誤，詳見錯誤碼返回信息retMsg否String(128)簽名失敗具體錯誤原因，例如：簽名失敗、參數格式校驗錯誤##### 以下字段在retCode=0 時有返回字段名變量名必填類型示例值描述商戶IDmchId是String(30)20001222支付中心分配的商戶號應用IDappId否String(30)cbsgB1T0SL6tfflFYoBX商戶應用ID支付產品IDproductId是String(24)8001支付訂單號payOrderId是String(30)P01201907231119090520000返回支付系統訂單號商戶訂單號mchOrderNo是String(30)20160427210604000490商戶生成的訂單號支付金額amount是int100支付金額,單位分幣種currency是String(3)cny三位貨幣代碼,人民幣:cny訂單狀態status是String(3)2當前訂單狀態: -2:訂單已關閉,0-訂單生成,1-支付中,2-支付成功,3-業務處理完成,4-已退款（2和3都表示支付成功,3表示支付平臺回調商戶且返回成功后的狀態）渠道用戶channelUser否String渠道用戶渠道訂單號channelOrderNo否String wx20170910211043fb206e92260071822007對應的第三方支付訂單號渠道數據包channelAttach否String渠道數據包支付成功時間paySuccTime否Long1505049094262支付成功時間，精確到毫秒簽名sign是String(32)C380BEC2BFD727A4B6845133519F3AD6簽名值，詳見簽名算法## 3. 支付結果通知 > 接口描述當訂單支付成功時，支付中心會向商戶的notifyUrl地址發起回調，通知訂單狀態。 > 接口鏈接該鏈接是通過統一下單接口提交的參數notifyUrl設置，如果無法訪問鏈接，業務系統將無法接收到支付中心的通知。 > 通知參數字段名變量名必填類型示例值描述支付訂單號payOrderId是String(30)P20160427210604000490支付中心生成的訂單號商戶IDmchId是String(30)20001222支付中心分配的商戶號應用IDappId否String(30)cbsgB1T0SL6tfflFYoBX商戶應用ID支付產品IDproductId是String(24)8001商戶訂單號mchOrderNo是String(30)20160427210604000490商戶生成的訂單號支付金額amount是int100支付金額,單位分入賬金額income是int100入賬金額,單位分狀態status是int1支付狀態,-2:訂單已關閉,0-訂單生成,1-支付中,2-支付成功,3-業務處理完成,4-已退款（2和3都表示支付成功,3表示支付平臺回調商戶且返回成功后的狀態）渠道訂單號channelOrderNo否String(64)wx2016081611532915ae15beab0167893571三方支付渠道訂單號擴展參數1param1否String(64)支付中心回調時會原樣返回擴展參數2param2否String(64)支付中心回調時會原樣返回支付成功時間paySuccTime是long精確到毫秒通知類型backType是int1通知類型，1-前臺通知，2-后臺通知通知請求時間reqTime是String(30)20190723141000通知請求時間，yyyyMMddHHmmss格式簽名sign是String(32)C380BEC2BFD727A4B6845133519F3AD6簽名值，詳見簽名算法> 返回結果業務系統處理后同步返回給支付中心，返回字符串 success 則表示成功，返回非success則表示處理失敗，支付中心會再次通知業務系統。（通知頻率為60/120/180/240/300,單位：秒） `注意：返回的字符串必須是小寫，且前后不能有空格。` ## 4.~創建收銀臺(廢棄)~ > 接口描述業務通過創建收銀臺接口得到收銀臺地址URl，用戶打開收銀臺URL進入支付流程。 > 接口鏈接創建PC收銀臺接口地址：{payUrl}/cashier/pc\_build > 請求參數字段名變量名必填類型示例值描述商戶IDmchId是long20001222分配的商戶號應用IDappId否String(32)0ae8be35ff634e2abe94f5f32f6d5c4f該商戶創建的應用對應的ID支付產品IDproductId是int8000支付產品ID商戶訂單號mchOrderNo是String(30)20160427210604000490商戶生成的訂單號支付金額amount是int100支付金額,單位分支付結果前端跳轉URLreturnUrl否String(128)<http://www.baidu.com/return.htm>支付結果回調URL支付結果后臺回調URLnotifyUrl是String(128)<http://www.baidu.com/notify.htm>支付結果回調URL商品主題subject是String(64)xxpay測試商品1商品主題商品描述信息body是String(256)xxpay測試商品描述商品描述信息請求時間reqTime是String(30)20190723141000請求接口時間， yyyyMMddHHmmss格式接口版本version是String(3)1.0接口版本號，固定：1.0簽名sign是String(32)C380BEC2BFD727A4B6845133519F3AD6簽名值，詳見簽名算法> 響應結果字段名變量名必填類型示例值描述返回狀態碼retCode是String(16)00-處理成功，其他-處理有誤，詳見錯誤碼返回信息retMsg否String(128)簽名失敗具體錯誤原因，例如：簽名失敗、參數格式校驗錯誤##### 以下字段在retCode=0 時有返回字段名變量名必填類型示例值描述簽名sign是String(32)C380BEC2BFD727A4B6845133519F3AD6簽名值，詳見簽名算法收銀臺URlpayUrl是String收銀臺地址返回的JSON格式數據如下： ``` <pre class="calibre25">``` { "sign": "5AAD2B9513ADE7E0C76A4BC99E1A92F0", "payUrl": "http://127.0.0.1:3020/api/cashier/pc?mchId=20000000&appId=710ddfebd2154434a8cfee1807b27eea&productId=8000,8001&amount=1&mchOrderNo=1528684776204&subject=XXPAY%E6%94%AF%E4%BB%98%E6%B5%8B%E8%AF%95&body=XXPAY%E6%94%AF%E4%BB%98%E6%B5%8B%E8%AF%95&notifyUrl=http%3A%2F%2Fwww.baidu.com&sign=9849EC1C736C72BCD59558DACA69FD6B", "retCode": "SUCCESS" } ``` ``` ## 5. 支付產品產品ID產品名稱8000網銀支付8001快捷支付8002微信掃碼支付8003微信H5支付8004微信公眾號支付8005微信小程序支付8006支付寶掃碼支付8007支付寶H5支付8008支付寶服務窗支付8009QQ錢包掃碼8010QQ錢包H5支付8011京東掃碼支付8012京東H5支付8013百度錢包8014銀聯二維碼8015充值卡支付8016網銀B2B8017網銀B2C8018支付寶PC支付8019云閃付掃碼8020微信條碼支付（被掃）8021支付寶條碼支付（被掃）8022支付寶APP支付8023微信APP支付8024聚合碼支付## 6. 錯誤碼 RetCode描述0成功9999業務異常，具體錯誤詳見RetMsg字段0100商戶簽名異常0010系統錯誤0011請使用post方法0012post數據為空0013簽名錯誤0014參數錯誤0015商戶不存在0110第三方超時0111第三方異常0112訂單不存在0113訂單已支付0114商品不存在0115價格不對0116物品數量不對0117過程返回2550118DB錯誤0119支付中心沒有對應的渠道0120修改訂單狀態失敗