版本	更改日期	作者	版本变化
1.0	2013-04-22	周颖	初稿
1.1	2013-04-24	周颖	去掉商品名称、商品描述
1.7	2013-06-21	周颖	增加支付币种、汇率
1.8	2013-07-26	周颖	增加币种 修改商品名称、商品描述为1000
1.9	2013-08-20	周颖	api收单版本升级为1.1 2.4   页面回调新增errCode、errMsg 4.2通知商户接口新增errCode、errMsg
2.0	2013-08-21	周颖	网关版本升级为1.2 2.3   商户提交订单接口修改内容：     新增账单地址、收货地址 3.3   商户订单支付接口修改内容： 支付ip改为非空 支付邮箱改为非空 持卡人邮箱改为非空 收货国家、收货州/城市改为非空 姓名改成姓、名及加签字段 新增设备指纹deviceFingerprintID及加签
2.0	2013/9/5	周颖	下单IP改为非空
2.1	2013/10/22	周颖	新增8.api 快递单上传接口
2.2	2013/10/31	周颖	根据运营、风控要求修改以下可空字段为不可空 互联网收款业务： billFirstName billLastName billAdderess billPostalCode billCountry billState billCity billEmail billPhoneNumber shippingFirstName shippingLastName shippingAdderess shippingPostalCode shippingCity shippingEmail shippingPhoneNumber registerUserEmail registerTime registerIp registerTerminal orderIp orderTerminal API收款业务： billName billAdderess billPostalCode billCompany billCountry billState billCity billEmail billPhoneNumber shippingAdderess shippingPostalCode shippingcompany shippingCity shippingEmail shippingPhoneNumber deviceFingerprintID registerUserEmail registerTime registerIp registerTerminal orderIp orderTerminal
2.2	2013/12/10	4.2.1	resultCode 新增新返回类型

 
 

1     文档说明

1.1   功能描述

通过MasaPay的支付渠道，付款者可以直接付款给商户，其中商户网站标价使用乾汇支持的币种，付款者付款用货币类型为相关支付方式支持的币种。

1.2   阅读对象

MasaPay互联网支付商户接口文档是面向具有一定的网站开发能力，了解ASP，PHP，JAVA，ASP.NET等开发语言中的一种及SQL数据库语言的网站开发，维护和管理人员。

2     互联网收款业务

2.1   功能概要

商户提交订单接口实现：商户向MasaPay互联网收单系统提交订单信息和明细信息。
通知商户接口实现：在交易支付成功后，通知商户系统订单支付成功。

2.2   系统交互

图2.1系统交互图

2.3   商户提交订单接口

发起方：商户系统
接收方：MasaPay互联网收单系统
提交方式：POST
生产提交地址：https://mas.masapay.com/mas/receiveMerchantOrder.htm
测试提交地址：https://mas-sandbox.masapay.com/mas/receiveMerchantOrder.htm
提交参数：

	参数	参数名称		数据类型	参数说明		是否可空
	基本参数
	version	版本号		String(4)	网关版本号，此版本为1.2		不可空
	merchantId	商户号		String(32)	商户开户时由MasaPay分配		不可空
	charset	编码字符集		String(10)	如gbk，gb2312，utf-8，Shift-JIS		不可空
	language	语言		String(2)	cn中文 en 英文 ru俄文 jp日文		不可空
	signType	签名方式		String(8)	SHA256，MD5可选		不可空
	业务参数
	merchantOrderNo	商户订单号		String(256)	合作商户网站唯一订单号，确保在商户系统唯一。		不可空
	goodsName	商品名称		String(1000)	商品名称		不可空
	goodsDesc	商品描述		String(2000)	格式为：商品名称1^商品规格1^购买数量1^商品单价1^商品展示网址1|商品名称2^商品规格2^购买数量2^商品单价2^商品展示网址2|……		不可空
	currencyCode	币种		String(3)	CNY人民币，USD美元，EUR欧元，RUB卢布，JPY日元, MOP澳门元, MYR马来西亚, NZD新西兰元, CHF瑞士法郎, THB泰铢, TWD新台币, KRW韩元, INR印度卢比, CAD加元, AUD澳元, HKD港币, GBP英镑, EUR欧元		不可空
	orderAmount	订单金额		String(18)	整型数字 除了日元、韩元为元，其他币种为分		不可空
	payMode	支付方式		String(2)	直连必填 10 国际信用卡 20 本地第三方支付 30 线下汇款 90 银联支付		可空
	orgCode	付款机构代码		String(10)	直连必填 国际信用卡：VISA，MASTER，JCB，AME，DINERSCLUB,DISCOVER 本地第三方支付：WEBMONEY，QIWI，WALLETONE，PAYON 线下汇款：WESTERNUNION , MONEYGRAM 银联支付：UPOP		可空
	payerAuth	是否做收款人信息验证		String(1)	Y验证N不验证，默认不验证		可空
	directFlag	是否直连		String(1)	N非直连D直连E内嵌		不可空
	allowDuplicate	是否可重复支付		String(1)	Y允许N不允许，默认不允许		可空
	submitTime	提交时间		String(14)	年月日时分秒 如：20121117020101		不可空
	expiryTime	失效时间		String(14)	年月日时分秒 如：20121117020101		可空
	pageUrl	前台回调URL		String(256)	用于在用户支付完成后跳转回商户指定的URL		不可空
	bgUrl	通知URL		String(256)	通知商户订单支付结果的地址		不可空
	ext1	扩展字段		String(256)	通知商户订单支付处理结果时回传该参数。不能包含=，&等特殊字符		可空
	ext2	扩展字段		String(256)	通知商户订单支付处理结果时回传该参数。不能包含=，&等特殊字符		可空
	remark	备注		String(256)	用于商户的特定业务信息的传递，只有商户与masapay约定传递此参数才有效。 格式：参数名1^参数值1|参数名2^参数值2|		可空
账单信息
billFirstName		账单名	String(100)			账单名		不可空
billLastName		账单姓	String(100)			账单姓		不可空
billAdderess		账单地址	String(200)			账单地址		不可空
billPostalCode		账单邮编	String(20)			不超过20位		不可空
billCompany		公司名称	String(200)			公司名称		可空
billCountry		账单国家	String(20)			账单国家ISO Standard Country Codes		不可空
billState		账单州省	String(20)			美国、加拿大必填，其他国家可空 two-character state,province, or territory codes.		不可空
billCity		账单城市	String(20)			账单城市		不可空
billEmail		账单邮箱	String(100)			账单邮箱		不可空
billPhoneNumber		账单电话号码	String(20)			纯数字，不超过20位		不可空
收货信息
shippingFirstName		收货人名	String(100)			收货人名		不可空
shippingLastName		收货人姓	String(100)			收货人姓		不可空
shippingAdderess		收货人地址	String(200)			收货人地址		不可空
shippingPostalCode		收货人邮编	String(20)			不超过20位		不可空
shippingCompany		收货人公司名称	String(200)			收货人公司名称		不可空
shippingCountry		收货人国家	String(20)			国家ISO Standard Country Codes		不可空
shippingState		收货人州省	String(20)			美国、加拿大必填，其他国家可空 two-character state,province, or territory codes.		不可空
shippingCity		收货人城市	String(20)			收货人城市		不可空
shippingEmail		收货人邮箱	String(100)			收货人邮箱		不可空
shippingPhoneNumber		收货人电话号码	String(20)			纯数字，不超过20位		不可空
	风控参数
	registerUserId	注册用户ID		String(20)	商户网站客户唯一标识号		可空
	registerUserEmail	用户注册邮箱		String(60)	用户注册邮箱地址		不可空
	registerTime	注册时间		String(14)	年月日时分秒 如：20121117020101		不可空
	registerIp	注册IP		String(20)	如：[202.96.209.16]		不可空
	registerTerminal	注册终端设备		String(20)	00 PC 01手机 02其他		不可空
	orderIp	下单IP		String(20)	付款人下单时IP地址 如：[202.96.209.16]		不可空
	orderTerminal	终端设备		String(20)	付款人下单时终端设备 00 PC 01手机 02其他		不可空
	ext3	扩展		String(256)	扩展字段		可空
	ext4	扩展		String(256)	扩展字段		可空
	signMsg	签名		String(256)	参见签名元素说明		不可空

参与签名元素说明：
version=1.2&merchantId=88800033122&charset=utf-8&language=en&signType=SHA256&merchantOrderNo=10000121&goodsName=女士服装&goodsDesc=商品名称1^商品规格1^购买数量1^商品单价1^商品展示网址1|商品名称2^商品规格2^购买数量2^商品单价2^商品展示网址2&currencyCode=USD&orderAmount=1000&payMode=20&orgCode=WEBMONEY&directFlag=D&allowDuplicate=N&submitTime=20121117020101&expiryTime=20121117030101&pageUrl=https://www.masapay.com&bgUrl=https://www.masapay.com&key={key}
签名方法示例说明：
详情参考附录8.1签名方法示例说明

2.4   页面回调

发起方：互联网收单子系统
接收方：商户系统
通知地址：商户下单时提供的pageUrl+POST请求
参数：

参数	参数名称	数据类型	参数说明	是否可空
业务参数
merchantOrderNo	商户订单号	String(64)	合作商户网站唯一订单号，请确保在商户系统中唯一	不可空
masapayOrderNo	交易流水号	String(16)	MasaPay系统交易流水号	不可空
currencyCode	币种	String(3)	CNY人民币，USD美元，EUR欧元，RUB卢布，JPY日元, MOP澳门元, MYR马来西亚, NZD新西兰元, CHF瑞士法郎, THB泰铢, TWD新台币, KRW韩元, INR印度卢比, CAD加元, AUD澳元, HKD港币, GBP英镑, EUR欧元	不可空
orderAmount	订单金额	String(18)	单位元	不可空
payCurrencyCode	支付币种	String(3)	CNY人民币，USD美元，EUR欧元，RUB卢布，JPY日元, MOP澳门元, MYR马来西亚, NZD新西兰元, CHF瑞士法郎, THB泰铢, TWD新台币, KRW韩元, INR印度卢比, CAD加元, AUD澳元, HKD港币, GBP英镑, EUR欧元	不可空
payAmount	支付金额	String(18)	单位元	不可空
rates	汇率	String(20)	精确到小数点后5位	不可空
resultCode	处理结果	String(4)	10 支付成功 11支付失败12支付中	不可空
errCode	错误代码	String(10)	失败时返回的错误代码	可空
errMsg	错误信息	String(256)	失败时返回的错误信息	可空
signMsg	签名字符串	String(256)	参见签名元素说明	不可空

备注：
最终支付结果请以通知为准。

3     API收款业务

3.1   功能概要

商户提交订单接口实现：商户向MasaPay API收单系统提交订单信息和支付信息。

3.2   系统交互

图3.1系统交互图

3.3   商户订单支付接口

3.3.1        请求

发起方：商户系统
接收方：MasaPay API收单系统
生产提交地址：https://open.masapay.com/masapi/order/ReceiveMerchantOrder?wsdl
测试提交地址：https://open-sandbox.masapay.com/masapi/order/ReceiveMerchantOrder?wsdl
提交参数：

参数	参数名称	数据类型		参数说明	是否可空
基本参数
version	版本号	String(4)		网关版本号，此版本为1.2			不可空
merchantId	商户号	String(32)		商户开户时由MasaPay分配			不可空
charset	编码字符集	String(10)		如gbk，gb2312，utf-8，Shift-JIS			不可空
language	语言	String(2)		cn中文 en 英文 ru俄文 jp日文			不可空
signType	签名方式	String(8)		SHA256，MD5可选			不可空
业务参数
merchantOrderNo	商户订单号	String(256)		合作商户网站唯一订单号，确保在商户系统唯一。			不可空
goodsName	商品名称	String(1000)		商品名称			不可空
goodsDesc	商品描述	String(2000)		格式为：商品名称1^商品规格1^购买数量1^商品单价1^商品展示网址1|商品名称2^商品规格2^购买数量2^商品单价2^商品展示网址2|……			不可空
currencyCode	币种	String(3)	CNY人民币，USD美元，EUR欧元，RUB卢布，JPY日元, MOP澳门元, MYR马来西亚, NZD新西兰元, CHF瑞士法郎, THB泰铢, TWD新台币, KRW韩元, INR印度卢比, CAD加元, AUD澳元, HKD港币, GBP英镑, EUR欧元			不可空
orderAmount	订单金额	String(18)	整型数字 除了日元、韩元为元，其他币种为分			不可空
payerAuth	是否做收款人信息验证	String(1)		Y验证N不验证，默认不验证			可空
allowDuplicate	是否可重复支付	String(1)		Y允许N不允许，默认不允许			可空
submitTime	提交时间	String(14)		年月日时分秒 如：20121117020101			不可空
expiryTime	失效时间	String(14)		年月日时分秒 如：20121117020101			可空
bgUrl	通知URL	String(256)		通知商户订单支付结果的地址			不可空
ext1	扩展字段	String(256)		通知商户订单支付处理结果时回传该参数。不能包含=，&等特殊字符			可空
ext2	扩展字段	String(256)		通知商户订单支付处理结果时回传该参数。不能包含=，&等特殊字符			可空
remark	备注	String(256)		用于商户的特定业务信息的传递，只有商户与masapay约定传递此参数才有效。 格式：参数名1^参数值1|参数名2^参数值2|			可空
支付参数
payMode	支付方式	String(2)		10 国际信用卡			不可空
orgCode	付款机构代码	String(10)		国际信用卡： VISA，MASTER，JCB，AME，DINERSCLUB,DISCOVER			不可空
cardNumber	持卡人卡号	String(19)		纯数字，不超过19位			不可空
cardHolderFirstName	持卡人名	String(100)		持卡人名			不可空
cardHolderLastName	持卡人姓	String(100)		持卡人姓			不可空
cardExpirationMonth	卡有效月份	String(2)		纯数字，不超过2位			不可空
cardExpirationYear	卡有效年份	String(4)		纯数字，不超过4位			不可空
securityCode	安全码	String(3)		纯数字，不超过3位			不可空
cardHolderEmail	持卡人邮箱	String(100)		持卡人邮箱			不可空
cardHolderPhoneNumber	持卡人手机	String(20)		纯数字，不超过20位			可空
payExt1	支付扩展1	String(100)		备用			可空
payExt2	支付扩展2	String(100)		备用			可空
账单信息
billName	账单姓名	String(100)		账单姓名			不可空
billAdderess	账单地址	String(200)		账单地址			不可空
billPostalCode	账单邮编	String(20)		不超过20位			不可空
billCompany	公司名称	String(200)		公司名称			不可空
billCountry	账单国家	String(20)		账单国家ISO Standard Country Codes			不可空
billState	账单州省	String(20)		美国、加拿大必填，其他国家可空 two-character state,province, or territory codes.			不可空
billCity	账单城市	String(20)		账单城市			不可空
billEmail	账单邮箱	String(100)		账单邮箱			不可空
billPhoneNumber	账单电话号码	String(20)		纯数字，不超过20位			不可空
收货信息
shippingName	收货人姓名	String(100)		收货人姓名			不可空
shippingAdderess	收货人地址	String(200)		收货人地址			不可空
shippingPostalCode	收货人邮编	String(20)		不超过20位			不可空
shippingCompany	收货人公司名称	String(200)		收货人公司名称			不可空
shippingCountry	收货人国家	String(20)		国家ISO Standard Country Codes			不可空
shippingState	收货人州省	String(20)		美国、加拿大必填，其他国家可空 two-character state,province, or territory codes.			不可空
shippingCity	收货人城市	String(20)		收货人城市			不可空
shippingEmail	收货人邮箱	String(100)		收货人邮箱			不可空
shippingPhoneNumber	收货人电话号码	String(20)		纯数字，不超过20位			不可空
风控信息
deviceFingerprintID	设备指纹ID	String(60)		1、设备指纹ID即为session_token session_token生成规则： m+merchantId+merchantOrderNo+ submitTime 2、在页面js里引入下面url  sandbox环境： https://h.online-metrix.net/fp/check.js?org_id=1snn5n9w&session_id=masapay1{session_token} 生产环境 https://h.online-metrix.net/fp/check.js?org_id=k8vif92e&session_id=masapay2{session_token}			不可空
payerName	付款人姓名	String(60)		付款人姓名			可空
payerMobile	付款人手机	String(20)		付款人手机号			可空
payerEmail	付款人邮箱	String(60)		付款人邮箱			可空
registerUserId	注册用户ID	String(20)		商户网站客户唯一标识号			可空
registerUserEmail	用户注册邮箱	String(60)		商户网站用户注册邮箱地址			不可空
registerTime	注册时间	String(14)		年月日时分秒 如：20121117020101			不可空
registerIp	注册IP	String(20)		如：[202.96.209.16]			不可空
registerTerminal	注册终端设备	String(20)		00 PC 01手机 02其他			不可空
orderIp	下单IP	String(20)		付款人下单时IP地址 如：[202.96.209.16]			不可空
orderTerminal	终端设备	String(2)		付款人下单时终端设备 00 PC 01手机 02其他			不可空
ext3	扩展	String(256)		扩展字段			可空
ext4	扩展	String(256)		扩展字段			可空
signMsg	签名	String(256)		参见签名元素说明			不可空

参与签名元素说明：
version=1.2&merchantId=88800033122&charset=utf-8&language=en&signType=SHA256&merchantOrderNo=10000121&goodsName=女士服装&goodsDesc=商品名称1^商品规格1^购买数量1^商品单价1^商品展示网址1|商品名称2^商品规格2^购买数量2^商品单价2^商品展示网址2&currencyCode=USD&orderAmount=1000 &allowDuplicate=N&submitTime=20121117020101&expiryTime=20121117030101& bgUrl=https://www.masapay.com&payMode=10&orgCode=visa&cardNumber=4000000000000000&cardHolderFirstName=jerry&cardHolderLastName=jin &cardExpirationMonth=09&cardExpirationYear=14&securityCode=780&cardHolderEmail=test@masapay.com&cardHolderPhoneNumber=13788888888 &deviceFingerprintID=HJH*098&*GYUJHG& shippingCountry =US&key={key}
签名方法示例说明：
详情参考附录8.1签名方法示例说明

3.3.2        返回

以XML 格式将数据返回给商户。

参数	参数名称	数据类型	参数说明	是否可空
基本参数
version	版本号	String(4)	网关版本号，此版本为1.2	不可空
charset	编码字符集	String(10)	如：gbk，gb2312，utf-8，Shift-JIS	不可空
language	语言	String(2)	zh中文 en 英文 ru俄文 jp日文	不可空
errCode	错误代码	String(10)	失败时返回的错误代码	可空
errMsg	错误信息	String(256)	失败时返回的错误信息	可空
signType	签名方式	String(8)	SHA256，MD5可选	不可空
业务参数
merchantOrderNo	商户订单号	String(64)	合作商户网站唯一订单号，请确保在商户系统中唯一	不可空
masapayOrderNo	交易流水号	String(16)	MasaPay系统交易流水号	不可空
submitTime	提交时间	String(14)	商户提交订单的时间，年月日时分秒 如：20121117020101	不可空
dealTime	交易完成时间	String(14)	MasaPay交易完成时间，年月日时分秒，如：20121117020101	不可空
currencyCode	币种	String(3)	CNY人民币USD美元EUR欧元RUB卢布JPY日元	不可空
orderAmount	订单金额	String(18)	整型数字 除了日元、韩元为元，其他币种为分	不可空
payCurrencyCode	支付币种	String(3)	CNY人民币USD美元EUR欧元RUB卢布JPY日元	不可空
rates	汇率	String(20)	精确到小数点后5位	不可空
paidAmount	实际支付金额	String(18)	整型数字 除了日元、韩元为元，其他币种为分	不可空
payMode	支付方式	String(2)	10 国际信用卡	不可空
orgCode	付款机构代码	String(10)	国际信用卡：VISA，MASTER，JCB，AME，DINERSCLUB	可空
resultCode	处理结果	String(2)	00 已受理10 支付成功 11支付失败	不可空
riskLevel	风险等级	String(2)	00无风险，01风控拒绝，02可疑 03交易滞留	可空
riskOccurCount	风险订单累计数量	String(4)	风险订单累计数量	可空
riskDesc	风险描述	String(256)	风险备注	可空
ext1	扩展字段	String(256)	回传原订单商户提交的ext1	可空
ext2	扩展字段	String(256)	回传原订单商户提交的ext2	可空
signMsg	签名字符串	String(256)	参见签名元素说明	不可空

参与签名元素说明：
version=1.2&charset=utf-8&language=en&signType=SHA256&merchantOrderNo=10000121&masapayOrderNo=880111123&submitTime=20121117020101&dealTime=20121117030101&currencyCode=USD&orderAmount=1000&payCurrencyCode=CNY&rates=6.21321&paidAmount=1000&payMode=20&orgCode=WEBMONEY&resultCode=10&riskLevel=00& riskOccurCount=10&riskDesc=norisk&key={key}
签名方法示例说明：
详情参考附录8.1签名方法示例说明
 

4     通知商户支付结果

4.1   功能概要

通知商户接口实现：在交易支付成功后，通知商户系统订单支付成功。

4.2   通知商户接口

4.2.1        回调商户URL

发起方：互联网收单子系统
接收方：商户系统
通知地址：商户下单时提供的bgUrl + POST请求
参数：

参数	参数名称	数据类型		参数说明	是否可空
基本参数
version	版本号	String(4)		网关版本号，此版本为1.2	不可空
charset	编码字符集	String(10)		如：gbk，gb2312，utf-8，Shift-JIS	不可空
language	语言	String(2)		cn中文 en 英文 ru俄文 jp日文	不可空
signType	签名方式	String(8)		SHA256，MD5可选	不可空
业务参数
merchantOrderNo	商户订单号	String(64)		合作商户网站唯一订单号，请确保在商户系统中唯一	不可空
masapayOrderNo	交易流水号	String(16)		MasaPay系统交易流水号	不可空
submitTime	提交时间	String(14)		商户提交订单的时间，年月日时分秒 如：20121117020101	不可空
dealTime	交易完成时间	String(14)		MasaPay交易完成时间，年月日时分秒，如：20121117020101	不可空
currencyCode	币种	String(3)	CNY人民币，USD美元，EUR欧元，RUB卢布，JPY日元, MOP澳门元, MYR马来西亚, NZD新西兰元, CHF瑞士法郎, THB泰铢, TWD新台币, KRW韩元, INR印度卢比, CAD加元, AUD澳元, HKD港币, GBP英镑, EUR欧元		不可空
orderAmount	订单金额	String(18)	整型数字 除了日元、韩元为元，其他币种为分		不可空
payCurrencyCode	支付币种	String(3)		CNY人民币USD美元EUR欧元RUB卢布JPY日元	不可空
rates	汇率	String(20)		精确到小数点后5位	不可空
paidAmount	实际支付金额	String(18)		整型数字 除了日元、韩元为元，其他币种为分	不可空
payMode	支付方式	String(2)		直连必填 10 国际信用卡 20 本地第三方支付 30 线下汇款 90 银联支付	不可空
orgCode	付款机构代码	String(10)		直连必填 国际信用卡：VISA，MASTER，JCB，AME，DINERSCLUB 本地第三方支付：WEBMONEY，QIWI，WALLETONE，PAYON 线下汇款：WESTERNUNION , MONEYGRAM 银联支付：UPOP	可空
resultCode	处理结果	String(2)		10 支付成功 11支付失败 12 DM审核中	不可空
errCode	错误代码	String(10)		失败时返回的错误代码	可空
errMsg	错误信息	String(256)		失败时返回的错误信息	可空
riskLevel	风险等级	String(2)		00无风险，01风控拒绝，02可疑 03交易滞留	可空
riskOccurCount	风险订单累计数量	String(4)		风险订单累计数量	可空
riskDesc	风险描述	String(256)		风险备注	可空
ext1	扩展字段	String(256)		回传原订单商户提交的ext1	可空
ext2	扩展字段	String(256)		回传原订单商户提交的ext2	可空
signMsg	签名字符串	String(256)		参见签名元素说明	不可空

参与签名元素说明：
version=1.2&charset=utf-8&language=en&signType=SHA256&merchantOrderNo=10000121&masapayOrderNo=880111123&submitTime=20121117020101&dealTime=20121117030101&currencyCode=USD&orderAmount=1000&payCurrencyCode=CNY&rates=6.21321&paidAmount=1000&payMode=20&orgCode=WEBMONEY&resultCode=10&riskLevel=00& riskOccurCount=10&riskDesc=norisk&key={key}
签名方法示例说明：
详情参考附录8.1签名方法示例说明

4.2.2        商户应答

MasaPay后台通过bgUrl通知商户，商户系统处理后，需要以字符串形式返回MasaPay系统，内容如下：

返回	说明
OK	处理成功,MasaPay系统收到此结果后不再进行补发通知
无返回或其它字符	处理不成功, MasaPay收到此结果,系统通过补单机制再次通知

 
 

5     API收款订单查询业务

5.1   功能概要

商户查询接口实现：在商户网站查询在MasaPay某段时间的交易记录或某笔交易记录。

5.2   系统交互

5.3   商户查询接口

5.3.1        请求

生产提交地址：https://open.masapay.com/masapi/order/QueryMerchantOrder?wsdl
测试提交地址：https://open-sandbox.masapay.com/masapi/order/QueryMerchantOrder?wsdl
输入参数：

参数	参数名称	数据类型	参数说明	是否可空
基本参数
version	版本号	String(4)	网关版本号，此版本为1.2	不可空
merchantId	商户号	String(32)	商户开户时由MasaPay分配	不可空
charset	编码字符集	String(10)	如gbk，gb2312，utf-8，Shift-JIS	不可空
language	语言	String(2)	cn中文 en 英文 ru俄文 jp日文	不可空
signType	签名方式	String(8)	SHA256，MD5可选	不可空
业务参数
queryType	查询方式	String(1)	0按MasaPay系统交易流水号单笔查询 1 按商户订单号查询 2按交易结束时间批量查询,只返回成功订单	不可空
masapayOrderNo	交易流水号	String(16)	查询方式为0时必填	可空
merchantOrderNo	商户订单号	String(64)	查询方式为1时必填	可空
startTime	订单提交开始时间	String(14)	查询方式为2时必填 年月日时分秒如：20121117020101	可空
endTime	订单提交结束时间	String(14)	查询方式为2时必填 年月日时分秒如：20121117020101限制时间段14天内，跨度24小时	可空
signMsg	签名字符串	String(256)	参见签名元素说明	不可空

备注：
如果商户指定了重复提交，根据商户订单号查询将可能会返回多条结果。
参与签名元素说明：
version=1.2&merchantId=88800033122&charset=utf-8&language=en&signType=SHA256&queryType=1&merchantOrderNo=10000121&key={key}
签名方法示例说明：
详情参考附录8.1签名方法示例说明

5.3.2        返回

以XML 格式将数据返回给商户。

参数	参数名称	数据类型	参数说明		是否可空
基本参数
version	版本号	String(4)	网关版本号，此版本为1.2		不可空
merchantId	商户号	String(32)	商户开户时由MasaPay分配		不可空
charset	编码字符集	String(10)	如：gbk，gb2312，utf-8，Shift-JIS		不可空
language	语言	String(2)	cn中文 en 英文 ru俄文 jp日文		不可空
signType	签名方式	String(8)	SHA256，MD5可选		不可空
errCode	错误代码	String(10)	失败时返回的错误代码		可空
errMsg	错误信息	String(256)	失败时返回的错误信息		可空
recordCount	记录集总条数	String(10)	记录集总条数		不可空
signMsg	签名字符串	String(256)	参见签名元素说明		不可空
订单信息(list)
merchantOrderNo	商户订单号	String(60)	商户系统唯一订单号		不可空
masapayOrderNo	交易流水号	String(16)	MasaPay系统交易流水号		不可空
orderAmount	订单金额	String(18)	整型数字 除了日元、韩元为元，其他币种为分		不可空
orderTime	提交时间	String(14)	年月日时分秒如：20121117020101		不可空
dealTime	交易时间	String(14)	年月日时分秒如：20121117020101		不可空
status	订单状态	String(1)	N未支付 S支付成功 F支付失败 I支付中 C已关闭		不可空
payMode	支付方式	String(2)	10 国际信用卡 20 本地第三方支付 30 线下汇款 90 银联支付		可空
orgCode	付款机构代码	String(10)	国际信用卡：VISA，MASTER，JCB，AME，DINERSCLUB 本地第三方支付：WEBMONEY，QIWI，WALLETONE，PAYON 线下汇款：WESTERNUNION , MONEYGRAM 银联支付：UPOP		可空
paidAmount	实际支付金额	String(18)	整型数字 除了日元、韩元为元，其他币种为分		不可空
currencyCode	币种	String(3)	CNY人民币，USD美元，EUR欧元，RUB卢布，JPY日元, MOP澳门元, MYR马来西亚, NZD新西兰元, CHF瑞士法郎, THB泰铢, TWD新台币, KRW韩元, INR印度卢比, CAD加元, AUD澳元, HKD港币, GBP英镑, EUR欧元	不可空
payCurrencyCode	支付币种	String(3)	CNY人民币，USD美元，EUR欧元，RUB卢布，JPY日元, MOP澳门元, MYR马来西亚, NZD新西兰元, CHF瑞士法郎, THB泰铢, TWD新台币, KRW韩元, INR印度卢比, CAD加元, AUD澳元, HKD港币, GBP英镑, EUR欧元		不可空
rates	汇率	String(20)	精确到小数点后5位		不可空
riskLevel	风险等级	String(2)	00无风险，01风控拒绝，02可疑 03交易滞留		可空
riskOccurCount	风险订单累计数量	String(4)	风险订单累计数量		可空
riskDesc	风险描述	String(256)	风险备注		可空
OrdersignMsg	订单签名字符串	String(256)	订单记录的加密元素		不可空

参与签名元素说明：
signMsg=SHA256(version=1.2&merchantId=88800033122&charset=utf-8&language=en&signType=SHA256& recordCount=1&key={key}
OrdersignMsg签名元素说明：
merchantOrderNo=10000121&masapayOrderNo=880111123&orderAmount=1000&orderTime=20121117020101&dealTime=20121117020101&status=S&payMode=20&orgCode=WEBMONEY&paidAmount=1000&currencyCode=USD&payCurrencyCode=CNY&rates=6.21321&riskLevel=00& riskOccurCount=10&riskDesc=norisk&key={key}
签名方法示例说明：
详情参考附录8.1签名方法示例说明
 

6     API退款业务

6.1   功能概要

商户退款接口：商户将购买产品或服务的款项全部或部分退还给用户
商户退款通知接口：在退款成功后，通知商户系统退款成功。

6.2   系统交互

6.3   商户退款接口

6.3.1        请求

参数	参数名称	数据类型	参数说明	是否可空
基本参数
version	版本号	String(4)	网关版本号，此版本为1.2	不可空
merchantId	商户号	String(32)	商户开户时由MasaPay分配	不可空
charset	编码字符集	String(10)	如gbk，gb2312，utf-8，Shift-JIS	不可空
language	语言	String(2)	cn中文 en 英文 ru俄文 jp日文	不可空
signType	签名方式	String(8)	SHA256，MD5可选	不可空
业务参数
refundOrderNo	退款订单号	String(30)	商户生成的唯一退款流水号	不可空
merchantOrderNo	原商户订单号	String(64)	原商户支付订单号	不可空
masapayOrderNo	原MasaPay交易流水号	String(16)	原MasaPay交易流水号	可空
refundAmount	退款金额	String(18)	整型数字 除了日元、韩元为元，其他币种为分	不可空
currencyCode	币种	String(3)	CNY人民币，USD美元，EUR欧元，RUB卢布，JPY日元, MOP澳门元, MYR马来西亚, NZD新西兰元, CHF瑞士法郎, THB泰铢, TWD新台币, KRW韩元, INR印度卢比, CAD加元, AUD澳元, HKD港币, GBP英镑, EUR欧元	不可空
refundSubmitTime	退款提交时间	String(14)	年月日时分秒 如：20121117020101	不可空
callbackUrl	回调通知URL	String(256)	通知商户退款订单结果的回调地址	不可空
signMsg	签名字符串	String(256)	参见签名元素说明	不可空

参与签名元素说明：
version=1.2&merchantId=88800033122&charset=utf-8&language=en&signType=SHA256&refundOrderNo=0001&merchantOrderNo=10000121&masapayOrderNo=1231221&refundAmount=100&currencyCode=CNY&refundSubmitTime=20121117020101&callbackUrl=http://www.masapay.com&key={key}
签名方法示例说明：
详情参考附录8.1签名方法示例说明

6.3.2        返回

以XML 格式将数据返回给商户。

参数	参数名称	数据类型	参数说明	是否可空
基本参数
version	版本号	String(4)	网关版本号，此版本为1.2	不可空
merchantId	商户号	String(32)	商户开户时由MasaPay分配	不可空
charset	编码字符集	String(10)	如：gbk，gb2312，utf-8，Shift-JIS	不可空
language	语言	String(2)	cn中文 en 英文 ru俄文 jp日文	不可空
signType	签名方式	String(8)	SHA256，MD5可选	不可空
signMsg	签名字符串	String(256)	参见签名元素说明	不可空
业务参数
resultCode	退款结果	String(2)	10表示退款申请成功 11表示退款申请失败	不可空
errorMsg	错误信息	String(256)	失败时返回的错误信息	可空
refundOrderNo	退款订单号	String(32)	与提交时退款流水号保持一致	不可空

参与签名元素说明：
version=1.2&merchantId=88800033122&charset=utf-8&language=en&signType=SHA256& resultCode=10& refundOrderNo=123213932&key={key}
签名方法示例说明：
详情参考附录8.1签名方法示例说明

6.4   退款通知接口

6.4.1        通知

发起方：互联网收单子系统
接收方：商户系统
通知地址：商户退款时提供的noticeUrl + POST请求
参数：

参数	参数名称	数据类型	参数说明	是否可空
基本参数
version	版本号	String(4)	网关版本号，此版本为1.2	不可空
charset	编码字符集	String(10)	如：gbk，gb2312，utf-8，Shift-JIS	不可空
language	语言	String(2)	cn中文 en 英文 ru俄文 jp日文	不可空
signType	签名方式	String(8)	SHA256，MD5可选	不可空
业务参数
refundOrderNo	退款订单号	String(64)	合作商户网站唯一退款号,确保在商户系统中唯一	不可空
merchantOrderNo	原商户订单号	String(64)	原商户订单号	不可空
masapayOrderNo	原MasaPay交易流水号	String(16)	原MasaPay交易流水号	可空
masapayRefundOrderNo	Masapay退款流水号	String(16)	Masapay退款流水号	不可空
submitTime	提交时间	String(14)	商户提交退款订单的时间，年月日时分秒如：20121117020101	不可空
dealTime	交易完成时间	String(14)	MasaPay退款交易完成时间，年月日时分秒如：20121117020101	不可空
currencyCode	币种	String(3)	CNY人民币，USD美元，EUR欧元，RUB卢布，JPY日元, MOP澳门元, MYR马来西亚, NZD新西兰元, CHF瑞士法郎, THB泰铢, TWD新台币, KRW韩元, INR印度卢比, CAD加元, AUD澳元, HKD港币, GBP英镑, EUR欧元	不可空
refundAmount	退款金额	String(18)	整型数字 除了日元、韩元为元，其他币种为分	不可空
resultCode	处理结果	String(2)	10 退款成功 11退款失败	不可空
ext1	扩展1	String(256)	扩展字段	可空
ext2	扩展2	String(256)	扩展字段	可空
signMsg	签名字符串	String(256)	参见签名元素说明	不可空

参与签名元素说明：
version=1.2&charset=utf-8&language=en&signType=SHA256&refundOrderNo=0001&merchantOrderNo=10000121&masapayOrderNo=12312312&masapayRefundOrderNo=1111111111111111&submitTime=20121117020101&dealTime=20121117020101&currencyCode=CNY&refundAmount=100&resultCode=10&key={key}
签名方法示例说明：
详情参考附录8.1签名方法示例说明

6.4.2        应答

MasaPay后台通过callbackUrl通知商户，商户系统处理后，需要以字符串形式返回MasaPay系统，内容如下：

返回	说明
OK	处理成功,MasaPay系统收到此结果后不再进行补发通知
无返回或其它字符	处理不成功, MasaPay收到此结果,系统通过补单机制再次通知

7     API退款查询业务

7.1   功能概要

在商户自己的网站查询在MasaPay某段时间的交易记录或某笔交易记录。

7.2   系统交互

7.3   退款查询接口

7.3.1        请求

发起方：商户系统
接收方：MasaPay互联网收单系统
生产提交地址：
测试提交地址：
输入参数：

参数	参数名称	数据类型	参数说明	是否可空
基本参数
version	版本号	String(4)	网关版本号，此版本为1.2	不可空
merchantId	商户号	String(32)	商户开户时由MasaPay分配	不可空
charset	编码字符集	String(10)	如gbk，gb2312，utf-8，Shift-JIS	不可空
language	语言	String(2)	cn中文 en 英文 ru俄文 jp日文	不可空
signType	签名方式	String(8)	SHA256，MD5可选	不可空
业务参数
queryType	查询方式	String(1)	0 按商户订单号单笔查询 1 按交易结束时间批量查询，只返回成功订单	不可空
refundOrderNo	退款订单号	String(30)	查询方式为0时必填，商户生成的唯一退款流水号	不可空
startTime	退款提交起始时间	String(14)	查询方式为1时必填，年月日时分秒如：20121117020101	可空
endTime	退款提交结束时间	String(14)	查询方式为1时必填，年月日时分秒如：20121117020101限制查询时间段14天内，跨度24小时	可空
signMsg	签名字符串	String(256)	参见签名元素说明	不可空

参与签名元素说明：
version=1.2&merchantId=88800033122&charset=utf-8&language=en&signType=SHA256&queryType=0&refundOrderNo=0001&key={key}
签名方法示例说明：
详情参考附录8.1签名方法示例说明

7.3.2        返回

以XML 格式将数据返回给商户。

参数	参数名称	数据类型	参数说明		是否可空
基本参数
version	版本号	String(4)	网关版本号，此版本为1.2		不可空
merchantId	商户号	String(32)	商户开户时由MasaPay分配		不可空
charset	编码字符集	String(10)	如：gbk，gb2312，utf-8，Shift-JIS		不可空
language	语言	String(2)	cn中文 en 英文 ru俄文 jp日文		不可空
signType	签名方式	String(8)	SHA256，MD5可选		不可空
errCode	错误代码	String(10)	失败时返回的错误代码		可空
errMsg	错误信息	String(256)	失败时返回的错误信息		可空
recordCount	记录集总条数	String(10)			不可空
signMsg	签名字符串	String(256)	参见签名元素说明		不可空
订单信息(list)
refundOrderNo	退款订单号	String(30)	商户生成的唯一退款流水号		不可空
merchantOrderNo	原商户订单号	String(64)	原商户订单号		不可空
masapayRefundOrderNo	退款流水号	String(16)	MasaPay系统退款流水号		不可空
refundAmount	实际退款金额	String(18)	整型数字 除了日元、韩元为元，其他币种为分		不可空
currencyCode	币种	String(3)	CNY人民币，USD美元，EUR欧元，RUB卢布，JPY日元, MOP澳门元, MYR马来西亚, NZD新西兰元, CHF瑞士法郎, THB泰铢, TWD新台币, KRW韩元, INR印度卢比, CAD加元, AUD澳元, HKD港币, GBP英镑, EUR欧元		不可空
submitTime	退款提交时间	String(14)	年月日时分秒如：20121117020101		不可空
dealTime	退款交易时间	String(14)	年月日时分秒如：20121117020101		不可空
status	订单状态	String(1)	P退款中 S退款成功 F退款失败		不可空
OrdersignMsg	单笔订单签名字符串	String(256)		每笔订单记录的加密元素	不可空

signMsg参与签名元素元素说明：
version=1.2&merchantId=88800033122&charset=utf-8&language=en&signType=SHA256&recordCount=1&key={key}
OrdersignMsg参与签名元素说明：
refundOrderNo=0001&merchantOrderNo=10000121&masapayRefundOrderNo1111111111111111&refundAmount=100&currencyCode=CNY&submitTime=20121117020101&dealTime=20121117020101&status=P&key={key}
签名方法示例说明：
详情参考附录8.1签名方法示例说明
 

8     API快递单上传业务

8.1   功能概要

快递单上传接口实现：商户上传快递单数据。

8.2   快递单上传接口

8.2.1        请求

生产提交地址：https://open.masapay.com/masapi/order/UploadExpressList?wsdl
测试提交地址：https://open-sandbox.masapay.com/ masapi/order/UploadExpressList?wsdl
输入参数：

参数	参数名称			数据类型			参数说明	是否可空
基本参数
version	版本号		String(4)		网关版本号，此版本为1.2			不可空
merchantId	商户号		String(32)		商户开户时由MasaPay分配			不可空
charset	编码字符集		String(10)		如gbk，gb2312，utf-8，Shift-JIS			不可空
language	语言		String(2)		cn中文 en 英文 ru俄文 jp日文			不可空
expressCount	快递单总数		String(10)		上传快递单总数量			不可空
signType	签名方式		String(8)		SHA256，MD5可选			不可空
signMsg	签名字符串			String(256)			参见签名元素说明	不可空
快递单信息list
merchantOrderNo	商户订单号			String(64)			原商户支付订单号	不可空
expressDate	配送时间			String(14)			年月日时分秒如：20121117020101	不可空
etaDate	预计妥投时间			String(14)			年月日时分秒如：20121117020101	不可空
expressNo	快递单号			String(32)			快递公司下单时订单号	不可空
expressCompany	快递公司			String(60)			快递公司名称	不可空
expressUrl	查单网址			String(200)			快递公司查询订单网址	不可空
uploadDate	上传时间			String(14)			年月日时分秒如：20121117020101	不可空
expressSignMsg		单笔快递单签名字符串	String(256)			每笔快递单记录的签名字符串		不可空

备注：
商户可以一次上传多条订单
参与签名元素说明：
signMsg=SHA256(version=1.2&merchantId=88800033122&charset=utf-8&language=en&signType=SHA256&expressCount=1&key={key})
ExpressSignMsg签名元素说明：
merchantOrderNo=10000121&expressDate=20121117020101&etaDate=20121117020101&expressNo=10099900101&expressCompany=顺丰快递&expressUrl=www.masapay.com&key={key}

8.2.2        返回

以XML 格式将数据返回给商户。

参数		参数名称	数据类型		参数说明			是否可空
基本参数
version		版本号	String(4)		网关版本号，此版本为1.2			不可空
merchantId		商户号	String(32)		商户开户时由MasaPay分配			不可空
charset		编码字符集	String(10)		如：gbk，gb2312，utf-8，Shift-JIS			不可空
language		语言	String(2)		cn中文 en 英文 ru俄文 jp日文			不可空
signType		签名方式	String(8)		SHA256，MD5可选			不可空
errCode		错误代码	String(10)		失败时返回的错误代码			可空
errMsg		错误信息	String(256)		失败时返回的错误信息			可空
expressCount	快递单总数		String(10)		成功收到快递单总数量		不可空
signMsg		签名字符串	String(256)		参见签名元素说明			不可空
未成功快递单信息list
merchantOrderNo	商户订单号			String(64)		原商户支付订单号			不可空
expressDate	配送时间			String(14)		年月日时分秒如：20121117020101			不可空
etaDate	预计妥投时间			String(14)		年月日时分秒如：20121117020101			不可空
expressNo	快递单号			String(32)		快递公司下单时订单号			不可空
expressCompany	快递公司			String(60)		快递公司名称			不可空
expressUrl	查单网址			String(200)		快递公司查询订单网址			不可空
uploadDate	上传时间			String(14)		年月日时分秒如：20121117020101			不可空
expressSignMsg		单笔快递单签名字符串	String(256)		每笔快递单记录的签名字符串					不可空

参与签名元素说明：
version=1.2&merchantId=88800033122&charset=utf-8&language=en&signType=SHA256& expressCount =2&key={key}
expressSignMsg签名元素说明：
merchantOrderNo=10000121&expressDate=20121117020101&etaDate=20121117020101&expressNo=10099900101&expressCompany=顺丰快递&expressUrl=www.masapay.com&key={key}
 

9     附录

9.1   签名方法示例说明

9.1.1        商户提交订单接口

签名算法：
SHA256
参与签名元素：
version=1.2&merchantId=88800033122&charset=utf-8&language=en&signType=SHA256&merchantOrderNo=10000121&goodsName=女士服装&goodsDesc=商品名称1^商品规格1^购买数量1^商品单价1^商品展示网址1|商品名称2^商品规格2^购买数量2^商品单价2^商品展示网址2&currencyCode=USD&orderAmount=1000&payMode=20&orgCode=WEBMONEY&directFlag=D&submitTime=20121117020101&expiryTime=20121117030101&pageUrl=https://www.masapay.com&bgUrl=https://www.masapay.com&key=1234567890
使用SHA256对上述签名元素得出的签名结果（二进制转十六进制大写）如下：
AD59678D5389974AB6886A3AAB6133FE0BCF1C0BA56E270B71C941F135F00BC0
提交参数示例：
version=1.2&merchantId=88800033122&charset=utf-8&language=en&signType=SHA256&merchantOrderNo=10000121&goodsName=女士服装&goodsDesc=商品名称1^商品规格1^购买数量1^商品单价1^商品展示网址1|商品名称2^商品规格2^购买数量2^商品单价2^商品展示网址2&currencyCode=USD&orderAmount=1000&payMode=20&orgCode=WEBMONEY&directFlag=D&submitTime=20121117020101&expiryTime=20121117030101&pageUrl=http://www.masapay.com&bgUrl=http://www.masapay.com&ext1=&ext2=&remark=&payerName=&payerMobile=&payerEmail=&registerTime=&registerIp=&registerTerminal=&receiveName&receiveAddress=&receivePostCode=&receiveTel=&orderIp=&orderTerminal=&ext3=&ext4=&signMsg=AD59678D5389974AB6886A3AAB6133FE0BCF1C0BA56E270B71C941F135F00BC0

9.1.2        通知商户接口

签名算法：
SHA256
参与签名元素：
version=1.2&charset=utf-8&language=en&signType=SHA256&merchantOrderNo=10000121&masapayOrderNo=880111123&submitTime=20121117020101&dealTime=20121117030101&currencyCode=USD&orderAmount=1000&paidAmount=1000&payMode=20&orgCode=WEBMONEY&resultCode=10&riskLevel=00&riskDesc=norisk&key=1234567890
使用SHA256对上述签名元素得出的签名结果（二进制转十六进制大写）如下：
AE403619EA1D5F460F1F4819802AF9F647C3A4169BACF3F35ECF081568EC2B94
提交参数示例：
version=1.2&charset=utf-8&language=en&signType=SHA256&merchantOrderNo=10000121&masapayOrderNo=880111123&submitTime=20121117020101&dealTime=20121117030101&currencyCode=US D&orderAmount=1000&paidAmount=1000&payMode=20&orgCode=WEBMONEY&resultCode=10&riskLevel=00&riskDesc=norisk&ext1=&ext2=&signMsg=AE403619EA1D5F460F1F4819802AF9F647C3A4169BACF3F35ECF081568EC2B94

9.2   联系人

联调人员：周颖
联系邮箱：zhouying@masapay.com
联系电话：+86+21-61001361
 

9.3   约定

1、masapay在当返回报文有errorCode的时候，masapay对返回报文不做加签，同时masapay相关交易信息也返回为空。
 

Unitrans世联翻译公司在您身边,离您近的翻译公司,心贴心的专业服务,专业的全球语言翻译与信息解决方案供应商,专业翻译机构品牌。无论在本地,国内还是海外,我们的专业、星级体贴服务，为您的事业加速！世联翻译公司在北京、上海、深圳等国际交往城市设有翻译基地，业务覆盖全国城市。每天有近百万字节的信息和贸易通过世联走向全球！积累了大量政商用户数据，翻译人才库数据，多语种语料库大数据。世联品牌和服务品质已得到政务防务和国际组织、跨国公司和大中型企业等近万用户的认可。 专业翻译公司,北京翻译公司,上海翻译公司,英文翻译,日文翻译,韩语翻译,翻译公司排行榜,翻译公司收费价格表,翻译公司收费标准,翻译公司北京,翻译公司上海。