下单提交接口

功能概述

商户发送购汇下单请求参数给首信易支付，并接收同步返回的支付信息，用支付信息拉起对应支付方式，并在订单终态后接收异步通知结果。

接口地址

https://apis.5upay.com/foreignExchange/order

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
merchantId 商户编号 varchar(9) 商户在首信易系统的唯一id，可在商户后台查看 M
orderAmount 订单金额 varchar(18) 单位:分，1 元=100 分 M
orderCurrency 订单币种 固定值 CNY 人民币、USD 美元、JPY 日元、EUR 欧元、CHF 瑞士法郎、GBP 英镑、CAD 加拿大元、AUD 澳大利亚元、HKD 港币 M
requestId 订单号 varchar(50) 订单号为商户自行拟定，提交的订单号必须在自身平台交易中唯一。首信易支付系统已付或撤销的订单，商户平台不能以相同的订单号再次提交。 M
amount 购汇金额 varchar(18) 单位:分，1 元=100 分，购汇金额=购汇金额-手续费，为空时则自动购汇减去手续费后的全部金额 O
currency 购汇币种 固定值 CNY 人民币、USD 美元、JPY 日元、EUR 欧元、CHF 瑞士法郎、GBP 英镑、CAD 加拿大元、AUD 澳大利亚元、HKD 港币 M
forUse 购汇用途 固定值 GOODSTRADE 货物贸易 M
PLANETICKET 机票
HOTELACCOMMODATION 酒店住宿
STUDYABROAD 留学
SOFTWARE 软件
MEETING 会议
EXHIBITION 会展
TRAVEL 旅游
LOGISTICS 物流
listPriceToken 锁定牌价标识 varchar(32) 商户用外币标价，请求首信易锁定牌价接口给其一个牌价，在一定的时间内给首信易请求，把外币根据当时给的牌价换成人民币，若不为空，则商户将外币标价按照首信易提供的牌价换算成人民币的金额进行交易 O
notifyUrl 通知地址 varchar(200) 服务器通知：订单终态后会向该地址发送通知，该地址可以带参数(发送机制见1.4 )， 如 : “www.5upay.com/callback.actio n?test=test” M
callbackUrl 回调地址 varchar(200) 页面回调：支付成功后会向该地址进行跳转，callbackUrl返回的参数只有：merchantId,requestId.callbackUrl返回格式示例：https://demo.5upay.com/sdk/callback?requestId=1446633831896&merchantId=890000593 M
remark 备注 varchar(300) 商户在首信易为订单进行备注，通过支付结果返回商户 O
paymentModeCode 支付方式编码 varchar(50) 见产品编码 C
appId 微信 appId varchar(100) 此参数传商户自己的微信appId C
openId 微信 openId varchar(100) 此参数传用户的微信openId C
productDetails 商品信息 Json 数组 见下表，商品信息 M
payer 申报信息 Json 见下表，申报信息 M
cashierVersion 收银台类型 固定值 STANDARD 标准版 C
merchantUserId 商户会员 ID varchar(30) 用户在商户网站的会员ID(至少两位，只允许大小写字母、数字) C
bindCardId 绑卡 ID varchar(100) 首信易返给商户的绑卡对应信息 C
clientIp clientIp varchar(100) 如果设置了 clientIp（参数传本机ip），此订单将不能在其他 ip 继续支付 C
timeout 订单超时时间 varchar(10) 此参数用于设置订单的超时时间（只能设置在二十四小时内），如： 输入 10，该订单将在 10 分钟后过期，分钟为单位。 O
ticketInfos 机票信息 Json 数组 见下表，机票信息 C
studyAbroadInfo 留学信息 Json 见下表，留学信息 C
hotelInfos 酒店信息 Json 数组 见下表，酒店信息 C
softwareInfo 软件 Json 见下表，软件信息 C
meetingInfo 会议信息 Json 见下表，会议信息 C
exhibitionInfo 会展信息 Json 见下表，会展信息 C
travelInfos 旅游信息 Json 数组 见下表，旅游信息 C
logisticsInfos 物流信息 Json 数组 见下表，物流信息 C
fileName 凭证文件名 varchar(200) 凭证文件名，包括后缀，不允许包含中文，例如:testFile.zip。需提前将凭证文件上传至SFTP的/fe/proof/目录下 C
subOrders 子订单 Json 数组 见子订单表，订单币种非CNY时，不支持传入此参数。传入此参数后，报关接口只支持以子订单号报关 O
hmac 参数签名 varchar(500) 商户生成的参数签名结果，获取hmac的方法请参考请求加密流程 M

请求参数列表 （productDetails，商品信息）

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
name 商品名称 varchar(500) 商品名称 M
quantity 商品数量 long 商品数量 M
amount 商品金额 long 单位:分，1 元=100 分 M
receiver 收款人 varchar(200) 收款人名称 O
description 商品描述 varchar(500) 商品描述 O
logisticsNumber 物流单号 varchar(120) 物流单号(tradeType 为纳 入海关时必填) C
logisticsCompany 物流公司 varchar(200) 物流公司名称(tradeType 为纳入海关时必填) C
tradeType 贸易类型 固定值 末纳入海关 M
纳入海关
invoiceNumber 发票号 varchar(35) 发票号 C
contractNumber 合同号 varchar(20) 合同号 C

请求参数列表 （payer，申报信息）

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
name 付款人姓名 varchar(100) 付款人姓名 M
idType 证件类型 固定值 IDCARD 身份证 M
idNum 证件号码 varchar(18) 证件号 M
bankCardNum 银行卡号 varchar(20) 银行卡号 M
phoneNum 手机号码 varchar(20) 手机号码 M
email 邮箱 varchar(50) 邮箱 O
nationality 付款人国籍 varchar(3) 该字段可依照：国家列表 O

请求参数列表 （ticketInfos，机票信息）

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
airlineName 航空公司名称 varchar(100) 航空公司名称 C
crewName 乘机人姓名 varchar(400) 乘机人姓名 C
flight 航班号 varchar(100) 航班号 C
freightSpaceClass 舱位等级 varchar(40) 舱位等级 C
fromTo 始发地/目的地 varchar(200) 始发地和目的地采用 3 位英文代码格式，中间用 "-"分隔，例如 : DXB-HKG C
departureArrivalTime 起飞时间/到达时间 varchar(200) 起飞时间和到达时间采用[yyyymmdd hh24:min]格式，中间用"-"分隔，例 如:2017060110:12-20170601 12:30 C

请求参数列表 （studyAbroadInfo，留学信息）

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
name 学生名称 varchar(100) 学生姓名 C
schoolName 学校名称 varchar(200) 缴费学校名称 C
studentNumber 学生证件号码 varchar(40) 学生证件号码，可传身份证号、护照号、学生证号或其他证件号码 C
schoolWeb 学校网址 varchar(150) 缴费学校网址 O
schoolCity 学校城市 varchar(100) 学校城市 O
major 入学专业 varchar(100) 学生入学专业 O
academicDegree 学历学位 varchar(100) 博士及以上、硕士、本科、预科、高中、初中、小学、其他培训(以上仅供参考， 如有其他情况请按照实际 情况传参) O
studyAbroadTime 留学期限 varchar(10) 一年及以下 O
一年以上
不传默认一年以上

请求参数列表 （hotelInfos，酒店信息）

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
hotelName 酒店名称 varchar(100) 酒店名称 C
hotelAddress 酒店地址 varchar(200) 酒店地址 C
registrantName 登记人姓名 varchar(100) 登记人姓名 C
checkInDate 入住日期 varchar(10) 格式：YYYY-MM-DD C
checkOutDate 退房日期 varchar(10) 格式：YYYY-MM-DD C
roomType 房间类型 varchar(40) 房间类型 C

请求参数列表 （softwareInfo，软件信息）

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
softwareName 软件名称 varchar(100) 软件名称 C
softwarePerson 软件购买人ID varchar(200) 软件购买人ID C
softwareCount 软件数量 varchar(100) 软件数量 C
softwareDate 软件服务有效期 varchar(10) 软件服务有效期 C
softwareWeb 软件官网 varchar(10) 软件官网 C
softwareCode 软件产品编号 varchar(40) 软件产品编号 C
softwareIp IP 地址 varchar(40) IP 地址 C

请求参数列表 （meetingInfo，会议信息）

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
meetingName 会议名称 varchar(100) 会议名称 C
meetingCountry 开会国家 varchar(50) 开会国家 C
meetingArea 开会地区 varchar(100) 开会地区 C
meetingPeople 参会人 varchar(100) 参会人 C
meetingCount 参会人数 varchar(10) 参会人数 C
meetingStartDate 会议开始日期 varchar(10) 会议开始日期 YYYY-MM-DD C
meetingEndDate 会议结束日期 varchar(10) 会议结束日期 YYYY-MM-DD C

请求参数列表 （exhibitionInfo，会展信息）

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
exhibitionName 展览名称 varchar(100) 展览名称 C
exhibitionCountry 展览国家 varchar(50) 展览国家 C
exhibitionArea 展览地区 varchar(100) 展览地区 C
exhibitionPeople 参展人 varchar(100) 参展人 C
exhibitionCount 参展人数量 varchar(10) 参展人数量 C
exhibitionStartDate 展览开始日期 varchar(10) 展览开始日期 YYYY-MM-DD C
exhibitionEndDate 展览结束日期 varchar(10) 展览结束日期 YYYY-MM-DD C

请求参数列表 （travelInfos，旅游信息）

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
subItem 旅游子项 固定值 GROEPTRAVEL 跟团游 C
RENTALCARS 租车
RENTING 租房
country 目的地国家/地区 varchar(20) 跟团游：目的地 C
租车：取车地
租房：房屋所在地
productName 产品名称 varchar(100) 产品名称+类型 例如：跟团游：泰国 7 日跟团游 租车：豪华 SUV 租房：新大阪和式合法民宿 C
startDateTime 开始时间 varchar(10) 跟团游：出发日期 租车：取车日期 租房：入住日期 YYYY-MM-DD O
name 联系人姓名 varchar(50) 跟团游：下单时所填的联系人姓名 O
租车：下单时所填的驾驶员姓名
租房：下单时所填的预定人姓名
peopleNum 人数 varchar(10) 跟团游：本次旅游的人数 O
租车：本次租车的人数
租房：本次租房的人数

请求参数列表 （logisticsInfos，物流信息）

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
country 收件国家/地区 varchar(20) 收件国家/地区 C
goodsType 商品类型 varchar(10) 所寄商品类型 如：衣服、食品… C
mailType 邮寄类型 varchar(10) 如：空运、海运… C
logisticsNumber 物流单号 varchar(50) 物流单号 O
name 收件人姓名 varchar(50) 收件人姓名 O

请求参数列表 （subOrders，子订单）

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
requestId 子订单号 varchar(100) 子订单号 O
orderAmount 订单金额 varchar(100) 子订单金额，单位：分 O

参数示例

{ "merchantId": "100000050", "orderAmount": "60000", "orderCurrency": "CNY", "requestId": "1528444599548", "amount": "100", "currency": "USD", "forUse": "GOODSTRADE", "notifyUrl": "http://127.0.0.1:14900/5upay/foreignexchange/OrderNotify.ashx", "callbackUrl": "http://127.9.0.1:14900/5upay/Callback.ashx", "remark": "备注", "payer": { "name": "付款人姓名", "idType": "IDCARD", "idNum": "13******26", "bankCardNum": "62*******02", "phoneNum": "139********67", "email": "cc@cc.com", "nationality": "156" }, "productDetails": [{ "name": "产品名称", "quantity": 100, "amount": 200.0, "receiver": "收款人姓名", "description": "产品描述" }], "hmac": "UZYjA/bik4TNL9aYSHajULOJxDSJkFyYfDNFxJxYCG1Zyi9s16uvSRmj07M3ax76JG 6STpWc/kyb36mWmg8X8gduvd39NupWK/zJErbgYffOmOd6YpmrvTQhbPioxLN8Ras9J9zkL7uQ3 cTOaLAHOeAQh7Aps3EFJ8MMh+sY4UwIl25h3PEkbBy2sBoug+ZpgLYDXTULrBY7OQ7cLTczfe5D OxJHLGSMpinHaVFOvQaodR8yZdAygDyfDPm16mKDBBV9NsRsGc0pNXZq+gz0hvTq1dLw+WygTVH 8VPFN01bPVHQjxJd3M041kE9ABF/vAP1ExXtSNCevRrAjyyRi4Q==" }

请求同步返回参数列表

参数名称 参数中文名称 参数说明
merchantId 商户编号 同请求参数
requestId 订单号 同请求参数
status 请求状态 SUCCESS 成功
FAILED 失败
ERROR 错误
REDIRECT 重定向
redirectUrl 重定向地址 当status为REDIRECT时，用户浏览器访问的地址
scanCode Base64 二维码 当status为SUCCESS时 ，Base64 格式的二维码，需要转换成图片，此项为扫码直连返回的参数
appParams App 调用码 当status 为SUCCESS时，此项只有 App 支付才会返回，利用此项调用移动端SDK
jsString 微信调起支付数据签名字段 当status 为SUCCESS时，此json数据为微信返回，预下单成功后会返回此json，利用此项调用微信支付。
payeeInfo 收款人信息 当status为SUCCESS时，此项只有在支付方式为线下银行汇款时返回，见下表，收款人信息
hmac 参数签名 商户生成的参数签名结果，获取hmac的方法请参考请求加密流程

返回参数（payeeInfo，收款人信息）

参数名称 参数中文名称 参数说明
accountNumber 收款人账号 收款人银行账号
bankUnionNumber 联行号 联行号
branchBank 开户行 开户行名称
payee 收款人名称 收款人名称
postscriptNumber 汇款附言 汇款附言
remittancesAddress 汇入地址 汇入地址

示例

{ "redirectUrl": "https://5upay.ehking.com/cashier/receipt/index/2c93a983638692180163b4cb9a8f05b4", "merchantId": "890000593", "requestId": "1527746602492", "hmac": "UZYjA/bik4TNL9aYSHajULOJxDSJkFyYfDNFxJxYCG1Zyi9s16uvSRmj07M3 ax76JG6STpWc/kyb36mWmg8X8gduvd39NupWK/zJErbgYffOmOd6YpmrvTQhbPioxLN8R as9J9zkL7uQ3cTOaLAHOeAQh7Aps3EFJ8MMh+sY4UwIl25h3PEkbBy2sBoug+ZpgLYDXT ULrBY7OQ7cLTczfe5DOxJHLGSMpinHaVFOvQaodR8yZdAygDyfDPm16mKDBBV9NsRsGc0 pNXZq+gz0hvTq1dLw+WygTVH8VPFN01bPVHQjxJd3M041kE9ABF/vAP1ExXtSNCevRrAjyyRi4Q==", "status": "REDIRECT" }

订单异步返回参数列表

参数名称 参数中文名称 参数说明
merchantId 商户编号 同请求参数
requestId 订单号 同请求参数
serialNumber 交易流水号 首信易系统交易流水号
totalRefundCount 已退款次数 已退款次数
totalRefundAmount 已退款金额 已退款金额
orderCurrency 订单币种 见货币列表
orderAmount 订单金额 订单金额，单位为分
remark 备注 备注
payment 支付信息 JSON 见下表，支付信息， 注：支付成功后返回此参数。
foreignExchange 购汇信息 JSON 见下表，购汇信息，注：购汇成功后返回此参数。
clearingOrg 清算机构 NUCC 网联
UNION_PAY 银联
paymentModeAlias 支付方式 B2C 个人网银
B2B 企业网银
UNION_SCANCODE_PAY 银联扫码
EXPRESS_PAY 快捷支付
CREDIT_EXPRESS_PAY 信用卡快捷支付
DEBIT_EXPRESS_PAY 借记卡快捷支付
ALI_SCANCODE_PAY 支付宝扫码支付
WEIXIN_SCANCODE_PAY 微信扫码支付
WEIXIN_OFFICIAL_PAY微信-公众号支付
APPLE_PAY 苹果支付
ALIPAY_WAP_PAY 支付宝-WAP
APP_ALIPAY APP支付宝支付
OFFLINE-P2P 线下银行汇款
realBankSerialNumber 银行流水号 银行流水号
needReview 是否需要审核 true 是 false 否
reviewStatus 审核状态 INIT 待上传
UPLOADED 待审核
CANCEL 取消
SUCCESS 审核通过
REFUSE 审核拒绝
reviewRemark 审核说明 审核拒绝时返回
subOrders 子订单 见子订单表
hmac 参数签名 商户生成的参数签名结果，获取hmac的方法请参考请求加密流程

返回参数（payment，支付信息）

参数名称 参数中文名称 参数说明
amount 支付金额 单位:分，1 元=100 分
currency 支付币种 见货币列表
status 支付状态 SUCCESS 成功
FAILED 失败
ERROR 错误
completeDateTime 支付完成时间 支付完成时间
bindCardId 绑卡id 首信易返给商户的绑卡唯一标识

返回参数（foreignExchange，购汇信息）

参数名称 参数中文名称 参数说明
amount 购汇金额 单位:分，1 元=100 分
currency 购汇币种 见货币列表
status 购汇状态 SUCCESS 成功
FAILED 失败
ERROR 错误
listprice 交易牌价 商户牌价
deductionAmount 购汇扣减额 单位:分，1 元=100 分
completeDate Time 购汇完成时间 购汇完成时间

返回参数（subOrders，子订单）

参数名称 参数中文名称 参数说明
requestId 子订单号 子订单号
orderAmount 订单金额 子订单金额，单位：分
serialNumber 子订单流水号 子订单流水号

示例

{ "merchantId": "100000050", "requestId": "1487151097417", "serialNumber": "ba3567eef3f743b2a5282c37b6250bb9", "totalRefundCount": "0", "totalRefundAmount": "0", "orderCurrency": "CNY", "orderAmount": "100", "remark": " 备 注 ", "payment": { "amount": "100", "currency": "CNY", "status": "SUCCESS", "completeDateTime": "2018-05-15 17:40:07" }, "foreignExchange": { "amount": "10", "currency": "USD", "status": "SUCCESS", "listprice": "68916", "deductionAmount": "69", "completeDateTime": "2018-05-15 17:59:31" }, "hmac":"UZYjA/bik4TNL9aYSHajULOJxDSJkFyYfDNFxJxYCG1Zyi9s16uvSRmj07M3ax 76JG6STpWc/kyb36mWmg8X8gduvd39NupWK/zJErbgYffOmOd6YpmrvTQhbPioxLN8Ras9 J9zkL7uQ3cTOaLAHOeAQh7Aps3EFJ8MMh+sY4UwIl25h3PEkbBy2sBoug+ZpgLYDXTULrB Y7OQ7cLTczfe5DOxJHLGSMpinHaVFOvQaodR8yZdAygDyfDPm16mKDBBV9NsRsGc0pNXZq +gz0hvTq1dLw+WygTVH8VPFN01bPVHQjxJd3M041kE9ABF/vAP1ExXtSNCevRrAjyyRi4Q==" }