探讨在线支付平台支付接口的设计
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 |
签名 |
|