统一收单接口

功能概述

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

接口地址

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

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
merchantId 商户编号 varchar(9) 商户在首信易系统的唯一id,可在商户后台查看 M
orderAmount 订单金额 varchar(18) 单位:分,1元=100分 M
orderCurrency 订单币种 varchar(15) 默认CNY(人民币) M
requestId 订单号 varchar(50) 订单号为商户自行拟定,提交的订单号必须在自身平台交易中唯一。首信易支付系统已付或撤销的订单,商户平台不能以相同的订单号再次提交。 M
partnerId 服务商id varchar(9) 服务商在首信易系统的唯一id,可在商户后台查看 C
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) WEBOX-APP_PAY-P2P 微包支付 C
openId openId varchar(100) 此参数传用户的钱包ID C
productDetails 商品信息 Json(数组) 支付商品信息,见下表 M
splitMark 分账标识 固定值 DO_SPLIT 分账 C
NOT_DO_SPLIT 不分帐 不传默认为不分帐
payer 身份信息 Json 此json可空,但不可将此参数整个去掉,可按以下格式传入接口: “payer”:{“idType“: ”IDCARD”},详见下表 M
clientIp 客户端IP varchar(100) 传递客户端外网IP(需商户收集用户的ip) M
timeout 订单超时时间 Int(4) 此参数用于设置订单的超时时间(需小于等于24小时),如:输入10,该订单将在10min后过期。应根据商户自身场景设置,分钟为单位 O
reportSerialNo 报备序列号 varchar(50) 报备序列号(可咨询商务经理) C
limitAccType 限定账户类型 varchar(200) 见下表,需要传多个枚举值时用半角 逗号“,”分隔 O
subsidyMark 补贴标识 固定值 DO_SUBSIDY 补贴 O
NOT_DO_SUBSIDY 不补贴,默认为不补贴
subsidyAmount 补贴金额 decimal(18) 单位:分,1元=100分 O
isBackUsersSign 返回用户标识 固定值 1 需要返回用户标识 O
0 不需要返回用户标识
传空时默认不返回
此参数用来指定交易成功后是否需要返回用户标识。用户标识可作为支付人的唯一标识,当前仅对微信、支付宝、微包支付有效。
location 位置信息 Json 近场支付场景必传,见位置信息表 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

请求参数(limitAccType,限定账户类型)

limitAccType 枚举 枚举说明 使用场景
DISABLE_CREDIT_CARD 禁止使用信用卡 微包支付、网关支付
ALIPAY_HB_FQ_NUM_3 花呗分期期数,3 期 支付宝花呗分期支付
ALIPAY_HB_FQ_NUM_6 花呗分期期数,6 期 支付宝花呗分期支付
ALIPAY_HB_FQ_NUM_12 花呗分期期数,12 期 支付宝花呗分期支付
WEBOX_BALANCE_PAY 微包余额支付 微包支付

请求参数(location,位置信息)

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
lng 经度 varchar(10) 商户经营位置经度,需使用WGS84国际通用坐标系 C
lat 纬度 varchar(10) 商户经营位置纬度,需使用WGS84国际通用坐标系 C

参数示例

{ "callbackUrl": "https://**.***.com/**/***", "clientIp": "10.101.10.10", "hmac": null, "merchantId": "890000593", "notifyUrl": "https://**.***.com/**/***", "orderAmount": "1", "orderCurrency": "CNY", "payer": { "bankCardNum": "6222**********5702", "email": "****@**.com", "idNum": "*****", "idType": "IDCARD", "name": "付款人姓名", "phoneNum": "******" }, "paymentModeCode": "BANK_CARD-B2C-ICBC-P2P", "productDetails": [{ "amount": "20000", "description": "黑色64G", "name": "IPHONE6", "quantity": "100", "receiver": "张三" }], "remark": "备注", "requestId": "1488794408626", "timeout": "10" }

请求同步返回参数列表

参数名称 参数中文名称 参数说明
merchantId 商户编号 同请求参数
requestId 订单号 同请求参数
partnerId 服务商Id 同请求参数
status 请求状态 SUCCESS 成功,请求已接收
FAILED 失败
ERROR 错误(此状态的返回参数见异常情况说明)
REDIRECT 重定向
realBankRequestNumber 银行订单号 银行订单号
payeeInfo 收款人信息 当status为SUCCESS,此项只有在支付方式为线下银行汇款时返回见下表payeeInfo
redirectUrl 重定向地址 当status为REDIRECT时,用户重定向访问的地址
walletId 钱包Id 微包钱包id(微包扫码支付时返回此参数)
scanCode Base64二维码 当status为SUCCESS,Base64格式的二维码,需商户转换成图片,此项为扫码直连返回的参数。
scanCodeUrl 二维码链接 当status为SUCCESS,此项为扫码直连返回的参数
appParams App调用码 当status为SUCCESS,此项只有app支付才会返回,利用此项调用移动端sdk。
jsString 微信调起支付数据签名字段 此json数据为微信返回,预下单成功后会返回此json,利用此项调用微信支付。
wechatId 微信原始ID 当status为REDIRECT,此项在小程序非直连支付方式情况下返回,利用此项原始APP可唤起小程序支付。注:走渠道小程序支付才会返回,下单时不用传APPID参数
tradeNo 支付宝交易号 当status为SUCCESS,此项在支付宝小程序、生活号预下单成功以后会返回,使用此项调用支付宝支付
token 微包支付调用token 当status为SUCCESS,此项在微包支付、微包扫码付或微包服务号支付预下单成功以后会返回,使用此项调用微包支付或微包服务号支付
openLink openLink 当status为REDIRECT,此项在微信小程序非直连支付方式且needOpenLink为1时返回,浏览器端的JavaScript通过执行location.href = openlink可唤起微信小程序支付 注:走渠道小程序支付才会返回,下单时不用传APPID参数
hmac 参数签名 首信易生成的参数签名结果,验签过程请参考解密流程

payeeInfo 收款人信息

参数名称 参数中文名称 参数说明
accountNumber 收款人账号 收款人银行账号
bankUnionNumber 联行号 联行号
branchBank 开户行 开户行名称
payee 收款人名称 收款人名称
postscriptNumber 汇款附言 汇款附言 注:专属账号汇款不返回此参数
remittancesAddress 汇入地址 汇入地址

示例

{ "redirectUrl": "https://***.*****.com/****/**", "merchantId": "890000593", "requestId": "1**********8", "hmac": "null", "status": "REDIRECT" }

订单异步返回参数列表

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

参数名称 参数中文名称 参数说明
merchantId 商户编号 同请求参数
requestId 订单号 同请求参数
partnerId 服务商Id 同请求参数
serialNumber 交易流水号 交易流水号
totalRefundCount 已退款次数 该支付订单共计退款次数
totalRefundAmount 已退款金额 该支付订单共计退款金额
orderCurrency 订单币种 默认人民币CNY
orderAmount 订单金额 单位:分,1元=100分
status 状态 SUCCESS成功
CANCEL取消
FAILED失败
completeDateTime 完成时间 支付完成时间
clearingOrg 清算机构 NUCC 网联
UNION_PAY 银联
paymentModeAlias 支付方式 WEBOX_APP 微包app支付
realBankSerialNumber 银行流水号 银行流水号
realBankRequestNumber 银行订单号 银行订单号
bindCardId 绑卡id 用户绑卡id
orderSplitAmount 可分账金额 该笔订单的总可分账金额,固定值,单位:分,当订单的计费类型为“实时”时,可分账金额=订单金额-手续费, 当订单的计费类型非“实时”时,可分账金额=订单金额
canSplitAmount 未分账金额 该笔订单当前的剩余可分账金额,单位:分 未分账金额=可分账金额-已分账金额-待分账资金归集退款金额
errorMessage 错误信息 错误信息
remark 备注 在下单请求中提交的备注信息,返回给商户
cardType 卡类型 DEBIT_CARD 借记卡
CREDIT_CARD 信用卡
用户实际支付的卡类型
支付渠道支持同步该信息时,交易成功后返回此参数
usersSign 用户标识 下单时指定需要返回用户标识,交易成功后返回此参数。当前只对微信、支付宝、微包支付方式生效
finalPaymentType 支付类型 BANK_CARD 银行卡
BALANCE 余额
用户实际支付的支付类型
收单商户与我司申请开通相关配置,交易成功后返回此参数
payerNameMd5 支付人名称MD5 实际支付用户的名称MD5格式
收单商户与我司申请开通相关配置,且支付渠道支持同步该信息时,交易成功后返回此参数
bankCardNumberMd5 支付卡号MD5 用户实际支付所用银行卡的卡号MD5格式
收单商户与我司申请开通相关配置,支付类型为银行卡,且支付渠道支持同步该信息时,交易成功后返回此参数
bankCardNumber 支付卡号掩码 用户实际支付所用银行卡的卡号掩码格式
收单商户与我司申请开通相关配置,支付类型为银行卡,且支付渠道支持同步该信息时,交易成功后返回此参数
bankCode 支付银行编码 用户实际支付所用银行卡的所属银行编码
收单商户与我司申请开通相关配置,支付类型为银行卡,且支付渠道支持同步该信息时,交易成功后返回此参数
hmac 参数签名 首信易生成的参数签名结果,验签过程请参考解密流程

示例

{ "bankCardNumber": "623058***6188", "bankCardNumberMd5": "d53bb12384640f96af54655115d2f114", "bankCode": "PINGANBANK", "cacheId": "a1076ae5b64567f68d31d45962d781b5", "cardType": "DEBIT_CARD", "clearingOrg": "UNION_PAY", "completeDateTime": "2023-12-29 11:13:01", "finalPaymentType": "BANK_CARD", "merchantId": "89****593", "orderAmount": "1", "orderCurrency": "CNY", "usersSign": "bc306ae84da567f68d31d4596537885d", "payerNameMd5": "ffe57baabbe47aed7394004c790ef5da", "paymentModeAlias": "SCANCODE-EQRCODE_PAY-WEBOX", "realBankRequestNumber": "122766625976234N", "requestId": "170381***8406", "serialNumber": "a1078584b6cb40f68d31d45962d781b5", "status": "SUCCESS", "totalRefundAmount": "0", "totalRefundCount": "0" }