下单接口

功能概述

本接口用于协议支付传入商户会员id和绑卡id后进行预下单,本接口调用成功以后需要调用订单支付确认接口。

接口地址

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

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
merchantId 商户编号 varchar(9) 商户在首信易系统的唯一id,可在商户后台查看 M
orderAmount 订单金额 decimal(18) 单位:分,1元=100分 M
orderCurrency 订单币种 varchar(15) 默认CNY(人民币) M
requestId 订单号 varchar(50) 订单号为商户自行拟定,提交的订单号必须在自身平台交易中唯一。首信易支付系统已终态的订单,商户平台不能以相同的订单号再次提交。 M
notifyUrl 通知地址 varchar(200) 服务器通知:当订单状态为终态后首信易服务器会向该地址发送通知,该地址可以带参数,如:http://www.5upay.com/callback.action?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) BANK_CARD-AGREEMENT-P2P 协议支付 C
splitMark 分账标识 固定值 DO_SPLIT 分账 C
NOT_DO_SPLIT 不分帐 默认为不分帐
productDetails 商品信息 Json(数组) 支付商品信息,见下表 M
payer 身份信息 Json 此json可空,但不可将此参数整个去掉,可按以下格式传入接口: “payer”:{“idType“: ”IDCARD”},详见下表 M
clientIp 客户端IP varchar(100) 传递客户端外网IP(需商户收集用户的ip) M
timeout 订单超时时间 Int(4) 此参数用于设置订单的超时时间(需小于等于24小时),如:输入10,该订单将在10min后过期。应根据商户自身场景设置,分钟为单位 O
merchantUserId 商户会员id varchar(30) 可通过传入此参数进行绑卡,每个商户下面唯一,请给每个用户分配一个id用于传入此参数,以便用户下次支付时可用之前绑定过的卡,与绑卡预下单接口传入的merchantUserId一致 O
bindCardId 绑卡id varchar(50) 用户银行卡的绑定id,协议支付绑卡成功后会返回此参数,且此参数也会在下单成功后异步返回。此参数若不为空,首信易将优先读取此参数对应的绑卡信息。此参数若为空则bankCard必填。 O
bankCard 协议支付信息 Json 若不调用绑卡接口可直接输入此信息完成绑卡与预下单操作。绑卡ID为空,此项必填。详见下表 C
partnerId 服务商id varchar(9) 服务商在首信易系统的唯一id,可在商户后台查看 C
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

请求参数(payer,身份信息)

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
name 付款方名称 varchar(100) 付款方名称 C
phoneNum 手机号码 varchar(50) 手机号码 C
idType 证件类型 varchar(20) IDCARD 身份证 C
idNum 证件号码 varchar(100) 目前只接受18位身份证号码 C
bankCardNum 银行卡号 varchar(100) 银行卡号,银联wap支付方式可以选择传递此参数 O
email 邮箱 varchar(50) 邮箱 O

请求参数(bankCard,协议支付信息)

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
name 姓名 varchar(100) 付款方名称 C
mobileNo 手机号码 varchar(50) 银行卡预留手机号 C
idNo 证件号码 varchar(100) 付款方身份证号 C
cardNo 银行卡号 varchar(100) 付款方银行卡号 C

参数示例

{ "callbackUrl": "https://demo.5upay.com/sdk/callback", "clientIp": "10.101.10.10", "hmac": null, "merchantId": "100000050", "notifyUrl": "https://demo.5upay.com/sdk/onlinepay/notify", "orderAmount": "1", "orderCurrency": "CNY", "payer": {}, "paymentModeCode": "BANK_CARD-AGREEMENT-P2P", "productDetails": [{ "amount": "20000", "description": "黑色64G", "name": "IPHONE6", "quantity": "100", "receiver": "张三" }], "remark": "备注", "requestId": "1488794408626", "timeout": "10", "merchantUserId": "1234", "bindCardId": "959e138ad2e290328e8d59fd124c618f" }

请求同步返回参数列表

参数名称 参数中文名称 参数说明
merchantId 商户编号 同请求参数
partnerId 服务商Id 同请求参数
requestId 订单号 同请求参数
status 请求状态 SUCCESS 成功,请求已接收
FAILED 失败
ERROR 错误
paymentOrderId 支付订单id 当status为SUCCESS,协议支付请求成功后会返回此参数,支付确认接口需要传入此参数。
needKaptcha 是否发送短信 当status为SUCCESS,协议支付请求成功后会返回此参数:
true 发送
false 不发送
cardType 银行卡类型 DEBIT_CARD 借记卡
CREDIT_CARD 信用卡
hmac 参数签名 首信易生成的参数签名结果,验签过程请参考解密流程

示例

{ "merchantId": "100000050", "requestId": "1527746602492", "paymentOrderId": "1gde138a36dg90dyh38d59fd12462dtb ", "needKaptcha": "true", "hmac": null, "status": "SUCCESS" }

订单异步返回参数列表

注意:协议支付时,异步通知在调用支付确认接口且订单成功后发送。当订单为分账订单时,订单支付完成后将发送一次异步通知,可能不包含订单可分账金额。订单计费成功后将发送第二次异步通知,告知可分账金额。每次通知都将依赖结果通知机制说明进行响应,请注意返回响应结果

参数名称 参数中文名称 参数说明
merchantId 商户编号 同请求参数
requestId 订单号 同请求参数
partnerId 服务商Id 同请求参数
serialNumber 交易流水号 交易流水号
totalRefundCount 已退款次数 该支付订单共计退款次数
totalRefundAmount 已退款金额 该支付订单共计退款金额
orderCurrency 订单币种 默认人民币CNY
orderAmount 订单金额 单位:分,1元=100分
status 状态 SUCCESS成功
CANCEL取消
FAILED失败
completeDateTime 完成时间 支付完成时间
clearingOrg 清算机构 NUCC 网联
UNION_PAY 银联
paymentModeAlias 支付方式 AGREEMENT_PAY 协议支付
realBankSerialNumber 银行流水号 银行流水号
realBankRequestNumber 银行订单号 银行订单号
bindCardId 绑卡id 用户绑卡id
orderSplitAmount 可分账金额 该笔订单的总可分账金额,固定值,单位:分,当订单的计费类型为“实时”时,可分账金额=订单金额-手续费, 当订单的计费类型非“实时”时,可分账金额=订单金额
canSplitAmount 未分账金额 该笔订单当前的剩余可分账金额,单位:分 未分账金额=可分账金额-已分账金额-待分账资金归集退款金额
errorMessage 错误信息 错误信息
remark 备注 在下单请求中提交的备注信息,返回给商户
hmac 参数签名 首信易生成的参数签名结果,验签过程请参考解密流程

示例

{ "totalRefundCount": "0", "serialNumber": "832f3f1bdab749849fd5bcf46d3ff7e3", "orderAmount": "1000", "orderCurrency": "CNY", "merchantId": "100000050", "bindCardId": "requestId": "1527746602492", "hmac": "c5ab9be868a4b79872739362995b39db", "bindCardId": "959e138ad2e290328e8d59fd124c618f", "remark": "备注", "totalRefundAmount": "0", "status": "SUCCESS" }