订单提交接口

功能概述

首信易支付外卡订单直接提交接口用于在商户端选择外卡支付方式后,通讯采用https协议,商户通过向首信易支付指定的 URL 发送请求参数数据,接收首信易支付同步返回的请求结果,接收异步通知结果并进行查询确认。

接口地址

https://apis.5upay.com/icc/orderApi

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
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
notifyUrl 通知地址 varchar(200) 服务器通知:当订单状态为终态后会向该地址发送五次成功通知,该地址可以带参数,如:“https://www.5upay.com/callback.action?test=test”.注意:如不填 notifyUrl 的参数值支付成功后您的服务器将得不到支付成功的通知。 M
shipInfo 风控送货信息 Json 送货信息,见下表 M
billInfo 风控账单信息 Json 账单信息,见下表 M
terminalNo 终端号 varchar(20) 一个网站对应一个终端号,不超过20 位 M
remark 备注 varchar(300) 商户在首信易为订单进行备注,通过支付结果返回商户 O
firstName 持卡人名 varchar(40) 持卡人名,不可为空值,长度不超过 40 个字符 M
lastName 持卡人姓 varchar(40) 持卡人姓,不可为空值,长度不超过 40 个字符 M
cardNo 卡号 varchar(16) 信用卡卡号,不可为空值,为全数字格式,长度不超过 16 位数字 M
expireM 卡有效期月份 varchar(2) 卡有效期月份,不可为空值,格式为[mm],例如 02 M
expireY 卡有效期年份 varchar(2) 卡有效期年份,不可为空值,格式为[yy],例如 11 M
cardCvv2 卡 CVV2 码 varchar(4) 卡 CVV2 码,不可为空值,对VISA/MASTER/JCB 卡是 3 位数字,AE 卡是 4 位数字 M
ordip 客户支付IP地址 varchar(15) 客户输入持卡人信息时使用的 IP地址。 M
callbackUrl 回调地址 varchar(200) 完成 3D 验证支付后的页面回调,会向该地址进行跳转,如:“https://www.5upay.com/callback.action?test=test”. M
browserInfo 浏览器信息 Json 浏览器信息,见下表 M
projectId 项目编号 varchar(50) 商户可以通过项目编号区分订单业务类型 O
hmac 参数签名 varchar(500) 商户生成的参数签名结果,获取hmac的方法请参考请求加密流程 M

请求参数列表 (送货信息 shipInfo)

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
shipStreet 送货街道地址 String (300) 为送货地址街道部分,总长不超过60 个字符。 M
shipCity 送货城市 String (300) 为送货地址城市部分,总长不超过50 个字符。 M
shipState 送货省/州 String (300) 为送货地址省/州部分(如送货国家为美国或加拿大,应为两位字母代码,代码规范参见附录《州省代码表》) M
shipPost 送货邮编 String (100) 为送货地址邮政编码部分,总长不超过 100 个字符。 M
shipCountry 送货国家 String (20) 为送货国家三位数字代码,代码规范参见附录《国家代码表》 M
shipPhone 送货电话 String (15) 为送货联系电话,总长不超过 15 个字符。 M
shipEmail 送货邮箱 String (100) 为送货联系 Email,总长不超过100 个字符。 M

请求参数列表 (账单信息 billInfo)

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
billStreet 账单街道地址 String (300) 为账单地址街道部分,总长不超过60 个字符。 M
billCity 账单城市 String (300) 为账单地址城市部分,总长不超过50 个字符。 M
billState 账单省/州 String (300) 为账单地址省/州部分(如账单国家为美国或加拿大,应为两位字母代码,代码规范参见附件《州省代码表》) M
billPost 账单邮编 String (100) 为账单地址邮政编码部分,总长不超过 100 个字符。 M
billCountry 账单国家 String (20) 为账单国家三位数字代码,代码规范参见附件《国家代码表》 M
billPhone 账单电话 String (15) 为账单联系电话,总长不超过 15 个字符。 M
billEmail 账单邮箱 String (100) 为账单联系 Email,总长不超过100 个字符。 M

请求参数列表 (浏览器信息 browserInfo)

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
acceptHeader 浏览器头信息 String (300) 从持卡人浏览器发送到 3DS 请求者的 HTTP ACCEPT 标头的确切内容。与 ACCEPT 标头不同的任何其他标头都将被拒绝。例如:application/json,text/plain,text/html,*/*。 M
javaEnabled 是否支持Java String (10) 布尔值,表示持卡人浏览器执行Java 的能力。 可以通过使用JavaScript 访问导航器的属性navigator.javaEnabled 来检索该值。例如:var javaEnabled=navigator.javaEnabled();//java_enabled M
terminalType 终端类型 String (2) 持卡人浏览器类型:枚举如下:01 PC 端 02 手机端例如:持卡人使用电脑浏览器传 01
language 浏览器语言 String (40) 表示 IETF BCP47 中定义的浏览器语言的值。请注意,根据上述 IETF BCP47,将仅提交一种浏览器语言标签。 子标签中也允许使用数字字符,将代表区域。例如:en-GB、zh-guoyu、fil-PH、gsw、es-419、de-1996 等。可以通过访问以下属性来检索该值 带有 JavaScript 的导航器,navigator.language。例如:var language=navigator.language;//language M
colorDepth 浏览器像素 String (10) 表示用于显示图像的调色板位深度的值,以每像素位为单位。 使用screen.colorDepth 属性从持卡人浏览器获取。 根据 EMVCo 规范的值可以是 1、4、8、15、16、24、32、48 之一。如果确定了不支持的color_depth,则需要提交小于实际值的最接近的支持值 . 如果获取的值为 30,根据 EMVCo 规范不支持,则必须提交 24。例如:var color_depth=String(window.screen.colorDepth);//color_depth M
screenHeight 屏幕高度 String (10) 持卡人屏幕的总高度(以像素为单位)。例如:var screen_height=String(window.screen.height);// M
screenWidth 屏幕宽度 String (10) 持卡人屏幕的总宽度(以像素为单位)。例如:var screen_width=String(window.screen.width);//screen_width M
timeZoneoffset 时区差 String (100) UTC 时间与持卡人浏览器本地时间之间的时差,以分钟为单位。 请注意,如果本地时区落后于 UTC,则偏移量为正,如果领先则为负。 如果 UTC -5 小时,则提交 300 或+300,如果 UTC +2 小时,则提交-120。 可以使用 Javascript getTimezoneOffset() 方法通过Date 对象检索该值。例如:var time_zone_offset=new Date().getTimezoneOffset();//time_zone_offset M
userAgent 浏览器版本 String (300) HTTP 用户代理标头的确切内容例如: var userAgent=navigator.userAgent;//userAgent M

参数示例

{ "merchantId": "888", "orderAmount": "1.00", "orderCurrency": "CNY", " requestId": "20190813-888-123456", "notifyUrl": "http://www.baidu.com", "terminalNo": "123456", "remark": "test", "firstName": "ming", "lastName": "li", "cardNo": "424557668", "expireM": "02", "expireY": "12", "cardCvv2": "356", "ordip": "127.0.0.1", "hmac": "af291df5d288690d2b7d7bcff7dc5a74447ce1502c1edcc9293051bb6a517d68", }

响应参数列表

注:注意:当响应处理正常即 status 参数值为 SUCCESS 的情况下,报文才包括商户编号、订单编号等信息。

参数名称 参数中文名称 参数说明
status 响应状态 响应正常 SUCCESS
响应异常 ERROR
merchantId 商户编号 同请求参数
paymentModeAlias 支付方式名称 返回值为 VISA MASTER AE JCB
requestId 订单号 同请求参数
bankNumber 银行订单号 银行订单号
serialNumber 交易流水号 首信易支付系统交易流水号
pstatus 支付状态 初始化 INIT
成功 SUCCESS
失败 FAILED
处理中 PROCESSING
pstatusDescription 支付状态说明 见平台状态码表
threedsUrl 3D 验证URL status 为 SUCCESS,pstatus 为 PROCESSING,则为用户浏览器访问的 3D 挑战地址
orderAmount 订单金额 同请求参数
orderCurrency 订单币种 同请求参数
submissionTime 订单提交时间 订单提交时间 格式:yyyy-MM-dd HH:mm:ss
completeTime 订单完成时间 支付完成时间 格式:yyyy-MM-dd HH:mm:ss
remark 备注 在下单请求中提交的备注信息,返回给商户
hmac 参数签名 商户生成的参数签名结果,获取hmac的方法请参考请求加密流程

示例

{ "status": "SUCCESS", "merchantId": "888", "paymentModeAlias": "MASTER", "requestId": "20190813-888-123456", "bankNumber": "3456789098", "serialNumber": "123456", "pstatus": "SUCCESS", "pstatusDescription": "0000", "orderAmount": "1.00", "orderCurrency": "CNY", "submissionTime": "2019-08-13 01:12:30", "completeTime": "2019-08-13 01:12:31", "remark": "test", "hmac": " af291df5d288690d2b7d7bcff7dc5a74447ce1502c1edcc9293051bb6a517d68", }

实时返回参数列表

注意:此表格的参数为 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" }