订单提交接口

功能概述

首信易支付外卡订单直接提交接口用于在商户端选择外卡支付方式后,通讯采用 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

参数示例

{ "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的方法请参考请求加密流程

示例

{ "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的方法请参考请求加密流程

示例

{ "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
hmac 参数签名 商户生成的参数签名结果,获取hmac的方法请参考请求加密流程

示例

{ "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", "status": "SUCCESS" }