统一收单接口

功能概述

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

接口地址

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) 非收银台模式需要传入此项，见产品编码 C
authCode 授权码 varchar(50) 钱包账户的授权码，如：微信/支付宝付款码 O
appId appId varchar(100) 此参数传商户自己的appId C
openId openId varchar(100) 此参数传用户自己的微信openId，或者支付宝的buyer_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
merchantUserId 商户会员id varchar(30) 快捷支付可通过传入此参数进行绑卡，每个商户下面唯一，请给每个用户分配一个id用于传入此参数，以便用户下次支付时可用之前绑定过的卡 O
bindCardId 绑卡id varchar(50) 本参数暂未启用 O
reportSerialNo 报备序列号 varchar(50) 报备序列号（可咨询商务经理） C
reportTerminalNo 报备终端号 varchar(8) 使用付款码交易时，此参数必传 C
limitAccType 限定账户类型 varchar(200) 见下表，需要传多个枚举值时用半角 逗号“,”分隔 O
subsidyMark 补贴标识 固定值 DO_SUBSIDY 补贴 O
NOT_DO_SUBSIDY 不补贴,默认为不补贴
subsidyAmount 补贴金额 decimal(18) 单位:分，1元=100分 O
needOpenLink openLink标识 varchar(1) 1 需要返回openLink C
0 不需要返回openLink
默认不需要返回openLink
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 微包余额支付 微包支付

参数示例

{ "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 支付方式 B2C 个人网银
B2B 企业网银
UNION_SCANCODE_PAY 银联扫码
EXPRESS_PAY 快捷支付
CREDIT_EXPRESS_PAY 信用卡快捷支付
DEBIT_EXPRESS_PAY 借记卡快捷支付
ALI_SCANCODE_PAY 支付宝扫码支付
ALIPAY_OFFICIAL_PAY “支付宝生活号支付
WEIXIN_SCANCODE_PAY 微信扫码支付
WEIXIN_OFFICIAL_PAY 微信-公众号支付
MINIAPPS_WEIXIN_PAY 微信-小程序支付
APPLE_PAY 苹果支付
ALIPAY_WAP_PAY 支付宝-WAP
APP_ALIPAY 支付宝APP支付
ALIPAY_B2C_PAY 支付宝B2C支付
MINIAPPS_ALI_PAY “支付宝-小程序支付
SCANCODE-EQRCODE_PAY-ALI 易码付-支付宝
SCANCODE-EQRCODE_PAY-WEIXIN 易码付-微信
SCANCODE-EQRCODE_PAY-WEBOX 易码付-微包
SCANCODE-EQRCODE_PAY-UNION 易码付-云闪付
AGREEMENT_PAY 协议支付
WAP 银联wap支付
APP_UNION 云闪付收银台支付
WEBOX_APP 微包app支付
WEBOX_CSP 微包扫码支付
WEBOX_SVC 微包服务号支付
APP_WEIXIN 微信APP支付
realBankSerialNumber 银行流水号 银行流水号
realBankRequestNumber 银行订单号 银行订单号
bindCardId 绑卡id 用户绑卡id
orderSplitAmount 可分账金额 该笔订单的总可分账金额，固定值，单位：分，当订单的计费类型为“实时”时，可分账金额=订单金额-手续费， 当订单的计费类型非“实时”时，可分账金额=订单金额
canSplitAmount 未分账金额 该笔订单当前的剩余可分账金额，单位：分 未分账金额=可分账金额-已分账金额-待分账资金归集退款金额
errorMessage 错误信息 错误信息
remark 备注 在下单请求中提交的备注信息，返回给商户
hmac 参数签名 首信易生成的参数签名结果，验签过程请参考解密流程

示例

{ "totalRefundCount": "0", "serialNumber": "832f3f1bdab749849fd5bcf46d3ff7e3", "orderAmount": "1000", "orderCurrency": "CNY", "merchantId": "890000593", "requestId": "********", "hmac": "......", "bindCardId": "", "remark": "备注", "totalRefundAmount": "0", "status": "SUCCESS" }