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

时间:2024-03-09 17:54:46

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

签名