订单提交接口
功能概述
首信易支付外卡订单直接提交接口用于在商户端选择外卡支付方式后，通讯采用 https 协议，商户通过向首信易支付指定的 URL 发送请求参数数据，接收首信易支付同步返回的重定向地址，将重定向地址发给客户端让用户进行跳转支付，支付完成以后接收异步通知结果。
接口地址
https://apis.5upay.com/icc/order
| 参数名称 |
参数中文名称 |
类型& 长度 |
参数说明 |
是否必填 |
| merchantId |
商户编号 |
varchar(9) |
商户在首信易系统的唯一身份标识，商户完成首信易系统注册后可登录商户后台商户服务查看。 |
M |
| orderAmount |
订单金额 |
decimal(18) |
以元为单位，保留 2 位小数,例如10.00 |
M |
| orderCurrency |
订单币种 |
varchar(15) |
CNY 为人民币，USD 为美元，EUR 为欧元，GBP 为英镑，JPY 为日元，KRW为韩元， RUB 为卢布，CHF 为瑞士法郎，HKD 为港币，SGD 为新加坡元，MOP 为澳门元，CAD 为加元，NZD 为新西兰元，TWD 为新台币，AUD 为澳大利亚元 |
M |
| requestId |
订单号 |
varchar(50) |
该参数格式为：订单生成日期-商户编号-商户流水号。例如：20170101-888-12345。商户流水号为数字，每日内不可重复，并且不能包括除数字、英文字母和“-”外以其它字符。流水号可为一组也可以用“-”间隔成几组 |
M |
| language |
语言 |
varchar(50) |
tw 繁体中文 zh 简体中文 es 西班牙语 en 英文 de 德语 fr 法语 ko 韩语 ja 日语 it 意大利语 ru 俄语 |
M |
| notifyUrl |
通知地址 |
varchar(200) |
服务器通知：当订单状态为终态后会向该地址发送五次成功通知，该地址可以带参数，如:“https://www.5upay.com/callback.action?test=test”.注意：如不填 notifyUrl 的参数值支付成功后您的服务器将得不到支付成功的通知。 |
M |
| callbackUrl |
回调地址 |
varchar(200) |
页面回调：支付成功后会向该地址进行跳转，如: “https://www.5upay.com/callback.action?test=test”. |
M |
| shipInfo |
风控送货信息 |
Json |
送货信息，见下表 |
O |
| billInfo |
风控账单信息 |
Json |
账单信息，见下表（如果是3D交易商户，此项为必填） |
C |
| terminalNo |
终端号 |
varchar(20) |
一个网站对应一个终端号，不超过20 位 |
M |
| remark |
备注 |
varchar(300) |
商户在首信易为订单进行备注，通过支付结果返回商户 |
O |
| projectId |
项目编号 |
varchar(50) |
商户可以通过项目编号区分订单业务类型 |
O |
| hmac |
参数签名 |
varchar(500) |
商户生成的参数签名结果，获取hmac的方法请参考请求加密流程 |
M |
请求参数列表 （送货信息 shipInfo）
| 参数名称 |
参数中文名称 |
类型& 长度 |
参数说明 |
是否必填 |
| shipStreet |
送货街道地址 |
String (300) |
为送货地址街道部分，总长不超过60 个字符。 |
O |
| shipCity |
送货城市 |
String (300) |
为送货地址城市部分，总长不超过50 个字符。 |
O |
| shipState |
送货省/州 |
String (300) |
为送货地址省/州部分（如送货国家为美国或加拿大，应为两位字母代码，代码规范参见附录《州省代码表》） |
O |
| shipPost |
送货邮编 |
String (100) |
为送货地址邮政编码部分，总长不超过10 个字符。对美国和加拿大此数据项为必填项，其中美国邮编为 5 位数字（格式 NNNNN 例如 12345）或 9 位数字(格式 NNNNN-NNNN,例如 12345-1234)，加拿大邮编为 6 位数字字母格式（格式 ANA NAN,例如 T2P 3C7） |
O |
| shipCountry |
送货国家 |
String (20) |
为送货国家三位数字代码，代码规范参见附录《国家代码表》 |
O |
| shipPhone |
送货电话 |
String (15) |
为送货联系电话，总长不超过 15 个字符。 |
O |
| shipEmail |
送货邮箱 |
String (100) |
为送货联系 Email，总长不超过100 个字符。 |
O |
请求参数列表 （账单信息 billInfo）
| 参数名称 |
参数中文名称 |
类型& 长度 |
参数说明 |
是否必填 |
| billStreet |
账单街道地址 |
String (300) |
为账单地址街道部分，总长不超过60 个字符。 |
C |
| billCity |
账单城市 |
String (300) |
为账单地址城市部分，总长不超过50 个字符。 |
C |
| billState |
账单省/州 |
String (300) |
为账单地址省/州部分（如账单国家为美国或加拿大，应为两位字母代码，代码规范参见附件《州省代码表》） |
C |
| billPost |
账单邮编 |
String (100) |
为账单地址邮政编码部分，总长不超过10 个字符。对美国和加拿大此数据项为必填项，其中美国邮编为 5 位数字（格式 NNNNN 例如 12345）或 9 位数字(格式 NNNNN-NNNN, 例如 12345-1234)，加拿大邮编为 6 位数字字母格式（格式ANA |
C |
| billCountry |
账单国家 |
String (20) |
为账单国家三位数字代码，代码规范参见附件《国家代码表》 |
C |
| billPhone |
账单电话 |
String (15) |
为账单联系电话，总长不超过 15 个字符。 |
C |
| billEmail |
账单邮箱 |
String (100) |
为账单联系 Email，总长不超过100 个字符。 |
C |
参数示例
<![CDATA[
{
"merchantId": "888",
"orderAmount": "1.00",
"orderCurrency": "CNY",
"requestId": "20190813-888-123456",
"notifyUrl": "http://www.baidu.com",
"callbackUrl":" http://www.sina.com ",
"terminalNo": "123456",
"remark": "test",
"hmac": "af291df5d288690d2b7e5d9cf9"
}
]]>
响应参数列表
注：需要解析同步返回的参数，并且跳转 redirectUrl 到收银
| 参数名称 |
参数中文名称 |
参数说明 |
| status |
响应状态 |
响应正常 SUCCESS
|
| 响应异常 ERROR |
| redirectUrl |
重定向地址 |
status 为 SUCCESS，则为用户浏览器访问 |
| merchantId |
商户编号 |
同请求参数 |
| requestId |
订单号 |
同请求参数 |
| hmac |
参数签名 |
商户生成的参数签名结果，获取hmac的方法请参考请求加密流程 |
示例
<![CDATA[
{
"status": "SUCCESS",
"redirectUrl ": "http://www.baidu.com.cn",
"merchantId": "888",
"requestId": "20190813-888-123456",
"hmac": "af291df5d288690d2b7d7bcd9cf9"
}
]]>
实时返回参数列表
注意：此表格的参数为 CallbackUrl 的服务器返回参
| 参数名称 |
参数中文名称 |
参数说明 |
| merchantId |
商户编号 |
同请求参数 |
| requestId |
订单号 |
同请求参数 |
| bankNumber |
银行订单号 |
银行订单号 |
| serialNumber |
交易流水号 |
首信易支付系统交易流水号 |
| pstatus |
支付状态 |
初始化 INIT |
| 成功 SUCCESS |
| 失败 FAILED |
| 处理中 PROCESSING |
| statusDescription |
支付状态说明 |
见平台状态码表 |
| orderAmount |
订单金额 |
同请求参数 |
| orderCurrency |
订单币种 |
同请求参数 |
| submissionTime |
订单提交时间 |
订单提交时间 格式：yyyy-MM-dd HH:mm:ss |
| completeTime |
订单扣款时间 |
支付完成时间 格式：yyyy-MM-dd HH:mm:ss |
| paymentModeAlias |
支付方式 |
返回值为 VISA MASTER AE JCB |
| remark |
备注 |
在下单请求中提交的备注信息，返回给商户 |
| hmac |
参数签名 |
商户生成的参数签名结果，获取hmac的方法请参考请求加密流程 |
示例
<![CDATA[
{
"serialNumber": "8a8a8f5990d911960190d96a19d900fa",
"orderCurrency": "CNY",
"pstatus": "FAILED",
"completeTime": "2024-07-22 15:50:32",
"remark": "备注",
"submissionTime": "2024-07-22 15:48:48",
"statusDescription": "0008",
"orderAmount": "1.00",
"merchantId": "890002159",
"requestId": "20240722-890002159-1721634527089",
"hmac": "NEMt5VymXBNsZFxd/61hqCvSxPlXEYElcPFOPKP2XAQ6Z0ZdbLA==",
"paymentModeAlias": "MASTER"
}
]]>
异步通知参数列表
注意：此表格的参数为 NotifyUrl 的服务器返回参数
| 参数名称 |
参数中文名称 |
参数说明 |
| merchantId |
商户编号 |
同请求参数 |
| requestId |
订单号 |
同请求参数 |
| bankNumber |
银行订单号 |
银行订单号 |
| serialNumber |
交易流水号 |
首信易支付系统交易流水号 |
| orderCurrency |
订单币种 |
同请求参数 |
| orderAmount |
订单金额 |
同请求参数 |
| pstatus |
支付状态 |
成功 SUCCESS |
| 失败 FAILED |
| pstatusDescription |
支付状态说明 |
见平台状态码表 |
| submissionTime |
订单提交时间 |
订单提交时间 格式：yyyy-MM-dd HH:mm:ss |
| completeTime |
订单扣款时间 |
支付完成时间 格式：yyyy-MM-dd HH:mm:ss |
| paymentModeAlias |
支付方式 |
返回值为 VISA MASTER AE JCB |
| remark |
备注 |
同请求参数 |
| status |
响应状态 |
响应正常 SUCCESS
|
| 响应异常 ERROR |
| bankCardNumber |
支付卡号掩码 |
用户支付所用银行卡的卡号掩码格式 |
| bankCardNumberMd5 |
支付卡号MD5 |
用户支付所用银行卡的卡号MD5格式 |
| hmac |
参数签名 |
商户生成的参数签名结果，获取hmac的方法请参考请求加密流程 |
示例
<![CDATA[
{
"serialNumber": "8a8a8f5990d911960190d96a19d900fa",
"orderCurrency": "CNY",
"pstatus": "FAILED",
"completeTime": "2024-07-22 15:50:32",
"remark": "备注",
"submissionTime": "2024-07-22 15:48:48",
"pstatusDescription": "0008",
"orderAmount": "1.00",
"merchantId": "890002159",
"requestId": "20240722-890002159-1721634527089",
"hmac": "Py7KHhB5+6qnB6vtVZDygu0cu51YFGAw==",
"paymentModeAlias": "MASTER",
"bankCardNumber": "457037***4383",
"bankCardNumberMd5": "31c7986898778ea875b8417241f60000",
"status": "SUCCESS"
}
]]>