统一下单接口

功能概述

汇元通杰易收订单提交接口用于在商户端选择支付方式后，通讯采用 https 协议，商户通过向汇元通指定的 URL 发送请求参数数据，支付完成以后接收异步通知结果。

接口地址

https://apis.geoswift.com/cp/order

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
merchantId 商户编号 varchar(9) 商户在汇元通系统的唯一身份标识，商户完成汇元通系统注册后可登录商户后台商户服务查看。 M
partnerId 服务商 ID varchar(9) 服务商编号 C
orderAmount 订单金额 decimal(18) 当订单币种为 JPY、KRW、VND 时，订单金额以元为单位，其他币种以分单位，1 元=100 分 M
orderCurrency 订单币种 varchar(8) CNY 人民币 M
USD 美元
JPY 日元
EUR 欧元
GBP 英镑
CAD 加拿大元
AUD 澳大利亚元
HKD 港币
RUB 卢布
KRW 韩元
VND 越南盾
NZD 新西兰元
requestId 订单号 varchar(50) 订单号为商户自行拟定，提交的订单号必须在自身平台交易中唯一。汇元通系统已付或撤销的订单，商户平台不能以相同的订单号再次提交。 M
settlementCurrency 结算币种 varchar(8) CNY 人民币 M
USD 美元
JPY 日元
EUR 欧元
GBP 英镑
CAD 加拿大元
AUD 澳大利亚元
HKD 港币
NZD 新西兰元
SGD 新加坡元
forUse 贸易背景 varchar(50) GOODSTRADE 货物贸易 M
PLANETICKET 机票
HOTELACCOMMODATION 酒店住宿
STUDYABROAD 留学
OTHER 其他
gatewayType 网关类型 varchar(6) ALL 混合 O
DEBIT 借记卡
CREDIT 贷记卡
支付方式为银联在线支付时选传,默认 ALL
subject 商品摘要 varchar(64) 商品摘要 M
notifyUrl 通知地址 varchar(200) 服务器通知：当订单状态为终态后Geoswift服务器会向该地址发送五次成功通知，该地址可以带参数，如:http://www.geoswift.com/notify.action?test=test。
注意：如不填notifyUrl的参数值支付成功后您的服务器将得不到支付成功的通知。		 M
callbackUrl 回调地址 varchar(200) 页面回调：支付成功后会向该地址进行跳转，如:http://www.geoswift.com/callback.action?test=test。 M
remark 备注 varchar(300) 商户在汇元通为订单进行备注，通过支付结果返回商户 O
paymentModeCode 支付方式编码 varchar(50) ONLINE_PAY-ALI_PAY-P2P 支付宝web支付-直连 M
ONLINE_PAY-UNION_PAY-P2P 银联在线支付-直连
SCANCODE-WEIXIN_PAY-P2P 微信扫码支付-直连
SCANCODE-WEIXIN_PAY 微信扫码支付-非直连
APP-ALI_PAY-P2P 支付宝APP支付-直连
APP-WEIXIN_PAY-P2P 微信APP支付-直连
MINIAPPS-WEIXIN_PAY-P2P 微信小程序支付-直连
isDirect 是否直连 固定值 true 是 M
false 否
goodstrades 商品信息 Json数组 见下表，限制最多50条信息 C
clientIp clientIp varchar(100) 如果设置了clientIp（参数传本机ip），此订单将不能在其他ip继续支付，微信扫码支付和微信小程序支付时必传 C
timeout 订单超时时间 Long(1440) 单位为分钟，默认1440分钟 O
authCode 支付宝授权码 varchar(32) 此参数传在支付宝注册的授权码，支付宝app支付必传 C
openId 用户标识openId varchar(30) 用户标识openId，微信app支付和微信小程序支付时必传 C
appId 微信appId varchar(30) 微信APPID，微信app支付和微信小程序支付时必传 C
ticketInfo 机票信息 Json 当forUse为PLANETICKET时必传，见下表，此项只能传一条数据 C
studyAbroadInfo 留学信息 Json 当forUse为STUDYABROAD时必传，见下表，此项只能传一条数据 C
studentIdType 学生证件类型 varchar(32) IDCARD 身份证 C
PASSPORT 护照
OTHER 其他
若支付方式编码为ONLINE_PAY-ALI_PAY-P2P 或 APP-ALI_PAY-P2P 时，此项仅支持 IDCARD
studentIdNo 学生证件号 varchar(32) 学生证件号 C
studentPhoneNo 学生电话 varchar(16) 学生电话 C
studentEmail 学生邮箱 varchar(128) 学生邮箱 C
payerIdType 付款人证件类型 varchar(32) IDCARD 身份证 C
PASSPORT 护照
OTHER 其他
payerIdNo 付款人证件号 varchar(32) 付款人证件号 C
payerName 付款人姓名(英文) varchar(64) 付款人英文姓名 C
payerNameZh 付款人姓名(中文) varchar(32) 付款人中文姓名 C
payerPhoneNo 付款人联系电话 varchar(16) 付款人联系电话 C
payerFirstName 付款人名(英) varchar(64) 付款人英文名 C
payerLastName 付款人姓(英) varchar(64) 付款人英文姓 C
payerStudentRelation 付款人与留学生关系 varchar(20) 当贸易背景为留学、支付方式编码为ONLINE_PAY-ALI_PAY-P2P或 APP-ALI_PAY-P2P 时，此项必传 C
SELF 本人
PARENTS 父母
GRANDPARENTS 祖父母
SPOUSE 配偶
SIBLINGS 兄弟姐妹
hotelInfo 酒店信息 Json 当forUse为HOTELACCOMMODATION时必传，见下表，此项只能传一条数据 C
otherInfo 其他 Json 当forUse为OTHER时必传，见下表，此项只能传一条数据 C
hmac 参数签名 varchar(500) 商户生成的参数签名结果，获取hmac的方法请参考请求加密流程 M

以上参数值中不能包含以下特殊字符’”&<>()

请求参数（goodstrades，商品信息）

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
name 商品名称 varchar(200) 商品名称 C
count 商品数量 Int(6) 商品数量，最大值为999999 C

请求参数（ticketInfo，机票信息）

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
flight 航班号 varchar(100) 多个航班号使用“，”分隔 C
departureArrivalTime 起飞时间 varchar(14) yyyymmdd hh:min 格式，例如:20170601 10:12 C
arrivalTime 到达时间 varchar(14) yyyymmdd hh:min 格式，例如:20170601 10:12 O

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

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
url 入学信息或入学通知书url varchar(200) 入学信息或入学通知书的图片链接url C
studentChineseName 学生姓名中文 varchar(32) 中文姓名 O
studentName 学生姓名英文 varchar(64) 非中文 例如:zhangsan C
schoolName 学校名称 varchar(128) 非中文 C
studentNo 学号 varchar(64) 非中文 O
schoolCountry 学校所在国家 varchar(3) 见国家编码 C
payAmount 缴费金额 Long 当缴费币种为 JPY、KRW、VND 时，缴费金额以元为单位，其他币种以分单位，1 元=100 分 C
payCurrency 缴费币种 varchar(8) 全币种，参考附录货币列表 C
schoolNo 学校编号 varchar(64) 非中文,支付宝留学业务时必填,其他业务时非必填 C
studentFirstName 学生名(英) varchar(64) 学生英文名 C
studentLastName 学生姓(英) varchar(64) 学生英文姓 C

请求参数（hotelInfo，酒店信息）

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
hotelName 酒店名称 varchar(100) 酒店名称 C
checkInDate 入住日期 varchar(10) yyyy-MM-dd 例如:2017-06-01 C
checkOutDate 退房日期 varchar(10) yyyy-MM-dd 例如:2017-06-01 C

请求参数（otherInfo，其它信息）

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
description 描述信息 varchar(200) 描述信息 C

参数示例

{ "appId": "", "authCode": "", "callbackUrl": "https://qa-sdk-v2.geoswift.com/cp/callbackUrl", "clientIp": "43.254.91.131", "forUse": "STUDYABROAD", "gatewayType": "DEBIT", "goodstrades": [], "hmac": "QZfqFCZshGKsV9G99XOuX9b+NpW5TOEgD0d1hxJTAnDgB6V2JEyiGHDb diWf7yNZUdruKx7Q1P6bwv6dhu05o13wYfp0S7zC7GP0aolLdjYqjNbR2n4gXinH7Tr1B3 GyOEJ2B6SDa3xEebBl8cd7m/Msng3jYbB1NznHkIQec329Xuh19kr0SQB+xdMAbX7Dzt dDweNMEnH+5pJLgbDjSyMocF9jBkhShvX5g1VdBpfK05ZTqRNaGcLrLgwMh4QlPtJhvq TBtOiko23ZtIylinHiVaaXnbsR9WGg5fsmtRly3Cf6LW/XbJUuyh6O92eArAV1CXOEuKy04 +qIkSW0bQ==", "isDirect": "true", "merchantId": "G90008005", "notifyUrl": "https://qa-sdk-v2.geoswift.com/cp/notify", "openId": "", "orderAmount": 100, "orderCurrency": "CNY", "partnerId": "", "payerFirstName": "tester", "payerIdNo": "130733200211111120", "payerIdType": "IDCARD", "payerLastName": "guo", "payerName": "tester", "payerNameZh": "guo", "payerPhoneNo": "1**********7", "paymentModeCode": "ONLINE_PAY-UNION_PAY-P2P", "remark": "1234", "requestId": "1630985841101", "settlementCurrency": "CNY", "studentEmail": "2**********7@qq.com", "studentIdNo": "130733200211141210", "studentIdType": "IDCARD", "studentPhoneNo": "1**********7", "studyAbroadInfo": { "payAmount": 1, "payCurrency": "CNY", "schoolCountry": "USA", "schoolName": "English", "schoolNo": "0310", "studentChineseName": "123", "studentFirstName": "123", "studentLastName": "123", "studentName": "slass", "studentNo": "1234567", "url": "urlaaa111" }, "subject": "苹果手机", "timeout": "10" }

请求同步返回参数列表

参数名称 参数中文名称 参数说明
merchantId 商户编号 商户在汇元通系统的唯一身份标识，商户完成汇元通系统注册后可登录商户后台商户服务查看。
partnerId 服务商ID 服务商编号
requestId 订单号 订单号为商户自行拟定，提交的订单号必须在自身平台交易中唯一。汇元通系统已付或撤销的订单，商户平台不能以相同的订单号再次提交。
bankRequestNumber 真实银行流水号 请求银行流水号
status 请求状态 成功 SUCCESS
失败 FAILED
错误 ERROR
重定向 REDIRECT
appParams App调用码 支付方式为微信/支付宝 app 时会返回调用码，利用此项调用官方微信/支付宝 sdk，完成支付。注：支付宝 app 时支持调起支付宝 h5 页面，调起方法见支付宝官方 sdk：https://global.alipay.com/docs/ac/app/download
redirectUrl 重定向地址 支付状态为重定向，则用户浏览器访问的地址；银联在线、微信扫码支付-非直连和支付宝 web 支付时会返回
scanCodeUrl 二维码链接 微信扫码支付直连时，返回二维码链接
jsString 微信调起支付数据签名字段 此json数据为微信返回,利用此项调用微信支付
serialNumber 交易流水号 交易流水号
errorMessage 错误信息 错误信息
orderStatus 订单状态 INIT 初始化
CANCEL 取消
PROCESSING 处理中
SUCCESS 成功
FAILED 失败
hmac 参数签名 汇元通生成的参数签名结果，验签过程请参考解密流程

示例

{ "redirectUrl": "https://qa-gs-cashier.geoswift.com/receipt/redirect/index /2c9980957a2c66a2017a2d17967b005b/2c9980957a2c66a2017a2d1796d1005e", "serialNumber": "2c9980727a2c6c68017a2d1795490029", "merchantId": "G90008005", "requestId": "16242538053223", "orderStatus": "PROCESSING", "status": "REDIRECT", "hmac": "uFzGnMExQgcCbxDjDbgjitCVK6+iD3qvxhQfk3DuDyfaJcXyiobyh8XBC4/jLpgF SidLjxYXdnX9bP4iom3wStOOh05ohGWvYbdLHh31bKMmjITouKH05SfUOIno15vrENfUu8wbr f0lIOx3tslTg2LAeAd+s9ekEVBq5ZvW06gKfOtmRzAtVTtT+weUxDo/R/vs7jK16rN3Gi4Jd6 YVmbPJFJCtkeGZJY1CkdfFFlYFoyIPY3/XvGUnw8KgAkQ8KlZIgzjWqBfiLyO7gcSWC1nybBK tGTqdux2a/vinahPNcRdmN+BBauk65qaAEZnNaTLFsUtmc/b724P0PKKKKQ==" }

订单异步返回参数列表

参数名称 参数中文名称 参数说明
merchantId 商户编号 商户在汇元通系统的唯一身份标识，商户完成汇元通系统注册后可登录商户后台商户服务查看。
partnerId 服务商ID 服务商编号
requestId 订单号 订单号为商户自行拟定，提交的订单号必须在自身平台交易中唯一。汇元通系统已付或撤销的订单，商户平台不能以相同的订单号再次提交。
bankRequestNumber 真实银行流水号 请求银行流水号
serialNumber 交易流水号 汇元通系统交易流水号
totalRefundCount 已退款次数 已退款次数
totalRefundAmount 已退款金额 已退款金额,当退款币种为 JPY、KRW、VND 时，已退款金额以元为单位，其他币种以分单位，1元=100分
orderAmount 订单金额 订单金额，当订单币种为 JPY、KRW、VND 时，订单金额以元为单位，其他币种以分单位，1元=100分
orderCurrency 订单币种 见货币列表
settlementAmount 结算金额 结算金额，当结算币种为 JPY、KRW、VND 时，结算金额以元为单位，其他币种以分单位，1 元=100 分
settlementCurrency 结算币种 见货币列表
status 支付状态 CANCEL 取消
SUCCESS 成功
FAILED 失败
exchangeRate 汇率 小数点后保留6位
feeAmount 手续费 手续费金额，当手续费币种为 JPY、KRW、VND 时，手续费金额以元为单位，其他币种以分单位，1 元=100 分
feeCurrency 手续费币种 见货币列表
gatewayType 网关类型 ALL 混合
DEBIT 借记卡
CREDIT 贷记卡
支付方式为银联在线支付时返回
completeDate Time 完成时间 支付完成时间
paymentModeCode 支付方式 ONLINE_PAY-ALI_PAY-P2P 支付宝 web 支付-直连
ONLINE_PAY-UNION_PAY-P2P 银联在线支付-直连
SCANCODE-WEIXIN_PAY-P2P 微信扫码支付-直连
APP-ALI_PAY-P2P 支付宝 APP 支付-直连
APP-WEIXIN_PAY-P2P 微信 APP 支付-直连
SCANCODE-WEIXIN_PAY 微信扫码支付-非直连
MINIAPPS-WEIXIN_PAY-P2P 微信小程序支付-直连
remark 备注 备注
needReview 是否需要核查 true 需要
false 不需要
errorMessage 错误信息 错误信息
hmac 参数签名 汇元通生成的参数签名结果，验签过程请参考解密流程

示例

{ "completeDateTime": "2021-06-21 13:54:04", "needReview": "true", "feeCurrency": "CNY", "remark": "", "paymentModeCode": "ONLINE_PAY-UNION_PAY-P2P", "gatewayType": "ALL", "orderAmount": "110", "exchangeRate": "100.000000", "merchantId": "G90008005", "requestId": "16242538053223", "totalRefundCount": "0", "serialNumber": "2c9980727a2c6c68017a2d1795490029", "orderCurrency": "CNY", "errorMessage": "null-null", "feeAmount": "11", "settlementCurrency": "CNY", "settlementAmount": "110", "totalRefundAmount": "0", "status": "SUCCESS", "hmac": "0mbgZQaTrBFhrEm6uRUW8VnxvZl8Mja4ecCEqNiP3Si8iJrZOL zQs5U0T5PJc/LmZpp6k10Ft85R8akvZBno9kz1EDugCFXvzDHyW+ai8+xuy qZhMNDlLS4GnWoiST4L3yIfIHy3WECBhgzfFi6N74dWBAHbeoc/vK89t7Fz xtd3ZzagsKOLov8iQ7mTlR27MSkSylv0HLIA1iVjBOUYJVAL53uGWxJNJne BUKpl9jQD8If8rpBJKN4Pa5UADbvXcq6oF7YIgYX/X125Pu4zq14+UtDozp ppgNcri6kB3vkQnlU6iGlAgO08bmjMfDlT/Qd+/ZltcaGi2CnhXNDmfw==" }