探討在線支付平臺支付接口的設計

1.      支付接口.... 2

1.1.       支付請求參數... 2

1.2.       支付返回參數... 3

2.      退款接口.... 4

1.3.       退款請求參數... 4

1.4.       退款返回參數... 4

3.      查詢接口.... 5

1.5.       查詢請求參數... 5

1.6.       查詢返回參數... 5

 

1.      支付接口

1.1.      支付請求參數

基本參數說明，以下：

 

參數	名稱	說明
MerchantID	商戶編號	必填，由支付平臺提供，如：100000
TransactionID	客戶端流水號	必填，40位長度，商戶提交的客戶端流水號必須惟一
OrderID	商戶訂單號	必填，50位長度
Amount	交易金額	必填，實際交易金額，正數(小數只能保留2位)，如：1234.56
CurrencyCode	幣種代碼	必填，CNY人民幣/USD美圓
ReturnUrl	支付完成跳轉地址	選填，200位長度 瀏覽器重定向到的頁面
NotifyUrl	後臺通知的地址	選填，200位長度 支付成功，後臺主動通知的地址
Description	商品描述	選填，500位長度
PaymentCatalog	支付類別	選填，500位長度，以「,」分隔，爲空則顯示全部支付類別，按照設置的順序顯示，如「1,2,3」
PaymentWay	支付方式	選填，500位長度，以「,」分隔，爲空則顯示全部支付方式，按照設置的順序顯示，如「ICBC,CCB,PayPal」
MerchantData	商戶私有信息	選填，500位長度，原樣返回
Language	語言	必填，ZH簡體中文，HK繁體中文，EN英文
UserID	用戶標識	必填，100位長度，用戶在商戶站點註冊的帳戶標識
UserName	用戶名稱	必填，100位長度，用戶在商戶站點註冊的帳戶名稱
Sign	簽名	必填，32位長度

 

生成簽名的步驟：

1)      使用&鏈接各參數名稱/值對，最終格式示例以下：

MerchantID=000001&TransactionID=1234567890&OrderID=1234567890

&Amount=1234.56&CurrencyCode=CNY

&ReturnUrl=http://xxx/MerchantDemo/PayReturn.aspx

&NotifyUrl=http://xxx/MerchantDemo/PayNotify.aspx

&Description=絢麗奪目的Retina 顯示屏&PaymentCatalog=1,2,3&PaymentWay=

&MerchantData=test&Language=ZH&UserID=testuser&UserName=測試用戶

2)      調用在線支付平臺公共方法（.NET）SecurityUtil.CreateSign生成簽名

 

商戶站點以POST方式將支付請求發送到在線支付平臺，FORM表單示例以下：

<form name="sendOrder" method="POST" action="http://xxx/Gateway/Pay.aspx">

<input type="hidden" name="MerchantID" value="000001"/>

<input type="hidden" name="TransactionID" value="1234567890"/>

<input type="hidden" name="OrderID" value="1234567890"/>

<input type="hidden" name="Amount" value="1234.56"/>

<input type="hidden" name="CurrencyCode" value="CNY"/>

<input type="hidden" name="ReturnUrl" value="http://xxx/MerchantDemo/PayReturn.aspx"/>

<input type="hidden" name="NotifyUrl" value="http://xxx/MerchantDemo/PayNotify.aspx"/>

<input type="hidden" name="Description" value="絢麗奪目的Retina 顯示屏"/>

<input type="hidden" name="PaymentCatalog" value="1,2,3"/>

<input type="hidden" name="PaymentWay" value=""/>

<input type="hidden" name="MerchantData" value="test"/>

<input type="hidden" name="Language" value="ZH"/>

<input type="hidden" name="UserID" value="testuser"/>

<input type="hidden" name="UserName" value="testuser"/>

<input type="hidden" name="Sign" value="FC8A5AA8D05A5DF5C7AB2C245212EB2C"/>

</form>

1.2.      支付返回參數

支付返回參數說明，以下：

 

參數	名稱	說明
MerchantID	商戶編號	原樣返回
TransactionID	客戶端流水號	原樣返回
OrderID	商戶訂單號	原樣返回
Amount	訂單金額	原樣返回
CurrencyCode	幣種代碼	原樣返回
PaymentRequestID	支付平臺流水號
MerchantData	商戶私有信息	原樣返回
PaymentCatalog	支付類別	原樣返回
PaymentWay	支付方式	原樣返回
Status	支付狀態信息	Y（成功）/ N（失敗）
Result	結果描述	當失敗時，爲失敗的描述信息
UserID	用戶標識	原樣返回
UserName	用戶名稱	原樣返回
Sign	簽名	必填，32位長度

支付結果信息會按照必定的規律發送到商戶站點指定的後臺通知的地址（經過 POST 方式發送），直到達到指定次數或者商戶站點返回成功信息「Y」給在線支付平臺。

 

使用&鏈接各返回參數名稱/值對，最終格式示例以下：

MerchantID=000001&TransactionID=1234567890&OrderID=1234567890&Amount=1234.56

&CurrencyCode=CNY&PaymentRequestID=000001101128093059000001

&MerchantData=test&PaymentCatalog=1,2,3&PaymentWay=&Status=Y

&Result=支付成功！&UserID=testuser&UserName=測試用戶

而後使用商戶密鑰進行簽名，並生成FORM表單。

 

在線支付平臺經過POST方式發送支付結果信息到商戶站點，FORM表單示例以下：

<form name="sendOrder" method="POST" action="http://xxx/MerchantDemo/PayNotify.aspx」/>

<input type="hidden" name="MerchantID" value="000001」/>

<input type="hidden" name="TransactionID" value="1234567890」/>

<input type="hidden" name="OrderID" value="1234567890」/>

<input type="hidden" name="Amount" value="1234.56」/>

<input type="hidden" name="CurrencyCode" value="CNY」/>

<input type="hidden" name="PaymentRequestID" value="000001101128093059000001」/>

<input type="hidden" name="MerchantData" value="test」/>

<input type="hidden" name="PaymentCatalog" value="1,2,3」/>

<input type="hidden" name="PaymentWay" value="」/>

<input type="hidden" name="Status" value="Y」/>

<input type="hidden" name="Result" value="支付成功！」/>

<input type="hidden" name="UserID" value="testuser」/>

<input type="hidden" name="UserName" value="testuser"/>

<input type="hidden" name="Sign" value="8CCC53AD8FC4F376E1055A049AE2C87F」/>

</form>

商戶站點調用在線支付平臺提供的方法（.NET）SecurityUtil.VerifySign驗證簽名，並檢查訂單號是否已處理，幣種、金額等是否與原始訂單一致等，而後進行後續處理。

2.      退款接口

1.3.      退款請求參數

參數	名稱	說明
MerchantID	商戶編號
TransactionID	客戶端流水號
RefundAmount	退款金額
CurrencyCode	幣種代碼
RefundReason	退款說明
Sign	簽名

1.4.      退款返回參數

回覆正文一行一項，格式爲參數名稱/值對（key=value），其中value 是 URL 編碼的字符串。須要對此回覆數據進行適當解析，而後進行 URL解碼。

參數	名稱	說明
MerchantID	商戶編號
TransactionID	客戶端流水號
RefundAmount	退款金額
CurrencyCode	幣種代碼
Status	返回結果	0（失敗）/ 1（成功）
Result	結果描述
Sign	簽名

3.      查詢接口

有兩種方式進行查詢：按日期段查詢、按訂單號查詢。

1.5.      查詢請求參數

按日期段查詢參數，將對查詢結果進行分頁, 每頁50條記錄：

參數	名稱	說明
MerchantID	商戶編號
BeginDate	開始日期
EndDate	結束日期
PageIndex	當前頁	從0開始
Sign	簽名

 

按訂單號查詢參數：

參數	名稱	說明
MerchantID	商戶編號
TransactionID	客戶端流水號
Sign	簽名

1.6.      查詢返回參數

回覆正文一行一項，格式爲參數名稱/值對（key=value），其中value 是 URL 編碼的字符串。須要對此回覆數據進行適當解析，而後進行 URL解碼。

 

按日期段查詢返回參數：

參數	名稱	說明
MerchantID	商戶編號
ResultData	結果數據	JSON格式
Sign	簽名

 

按訂單號查詢返回參數：

參數	名稱	說明
MerchantID	商戶編號
TransactionID	客戶端流水號
OrderID	商戶訂單號
Amount	訂單金額
CurrencyCode	幣種代碼
PaymentRequestID	支付平臺流水號
Description	商品描述
PaymentCatalog	支付類別
PaymentWay	支付方式
MerchantData	商戶私有信息
Status	狀態	0（未支付）/ 1（已支付）
RefundAmount	已退款金額
UserID	用戶標識
UserName	用戶名稱
Sign	簽名