探讨在线支付平台支付接口的设计

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	签名