# 聚合支付统一下单
## 基本信息
- **API ID**: 59c31fc3295046118fab5bc605c65b8d
- **API 分组**: aggpay
- **请求路径**: `/rest/v1.0/aggpay/pre-pay`
- **请求方法**: POST
- **描述**:
- **安全需求**: YOP-RSA2048-SHA256, YOP-SM2-SM3
- **最后更新时间**: 2025-09-03 18:01:38
## 请求参数
### application/x-www-form-urlencoded
| 参数名 | 参数说明 | 类型 | 是否必填 | 描述 | 示例值 |
| ------ | ------ | ------ | ------ | ------ | ------ |
| parentMerchantNo | 发起方商户编号 | string | 否 | 发起方商户编号。
*标准商户收付款方案中此参数与收款商户编号一致；
*平台商户收付款方案中此参数为平台商商户编号；
*服务商解决方案中，①标准商户收款时，该参数为标准商户商编 ②平台商收款或平台商入驻商户收款时，该参数为平台商商编。
如果商户使用先下单再支付模式，已传入token，则本字段可以不传值，否则必须传值
| 10012426765 |
| merchantNo | 商户编号 | string | 否 | 商户编号 收单主体商编，平台商或服务商下的子商户，普通特约商户 如果商户使用先下单再支付模式，已传入token，则本字段可以不传值，否则必须传值
| 10012426765 |
| orderId | 商户收款请求号 | string | 否 | 商户收款请求号
商户系统内部生成的订单号，需要保持在同一个商户下唯一
未传入token时必填
| ORDER202401010515217305372872 |
| orderAmount | 订单金额 | number | 否 | 订单金额
业务上是必须参数，单位： 元， 两位小数， 最低 0.01
未传入token时必填
| 0.01 |
| expiredTime | 订单截止时间 | string | 否 | 订单截止时间
格式"yyyy-MM-dd HH:mm:ss"不传默认一天
| sample_expiredTime |
| notifyUrl | 支付结果通知地址 | string | 否 | 接收支付结果的通知地址
请参考结果通知详情
| https://notify.merchant.com/xxx |
| redirectUrl | 页面回调地址 | string | 否 | 页面回调地址。如使用易宝收银台需要上送前端页面回调地址
| https://notify.merchant.com/xxx |
| memo | 对账备注 | string | 否 | 对账备注
商户自定义参数，会展示在交易对账单中,支持85个字符（中文或者英文字母）
| sample_memo |
| goodsName | 商品名称 | string | 否 | 商品名称，简单描述订单信息或商品简介，用于展示在收银台页面或者支付明细中
未传入token时必填
特殊说明：
1、当商品名称超过85个字符时，易宝会默认保留前85个字符
2、由于微信渠道侧限制，如微信支付时该字段将自动截取前42个字符送渠道
| 旺仔牛奶 |
| fundProcessType | 分账订单标记 | string | 否 | 分账订单标记
可选项如下:
DELAY_SETTLE:需要分账
REAL_TIME:不需要分账
REAL_TIME_DIVIDE:实时分账;需同时传入divideDetail
| REAL_TIME |
| payWay | 支付方式 | string | 是 | 可选项如下:
USER_SCAN:用户扫码
MINI_PROGRAM:小程序支付
WECHAT_OFFIACCOUNT:微信公众号
ALIPAY_LIFE:支付宝生活号
JS_PAY:JS支付
SDK_PAY:SDK支付
H5_PAY:H5支付
UNCONSCIOUS_PAY:云微无感支付
DIRECT_PAY:云微直接支付
| USER_SCAN |
| channel | 渠道类型 | string | 是 | 渠道类型
可选项如下:
WECHAT:微信
ALIPAY:支付宝
UNIONPAY:银联云闪付
DCEP:数字人民币
| ALIPAY |
| scene | 场景 | string | 否 | 场景channel为WECHAT时，可选值ONLINE/OFFLINE/BAOXIAN/GONGYI/DC_SEPARATION/DIGITAL/REGISTRATION/PRIVATE_EDUCATION/DIRECT/STORE_ASST/GONGJIAO；
channel为ALIPAY时，可选值OFFLINE/LARGE/REGISTRATION；
channel为UNIONPAY时非必填；
可选项如下:
ONLINE:线上
OFFLINE:线下
BAOXIAN:保险
GONGYI:公益
DC_SEPARATION:借贷分离
DIGITAL:数娱
REGISTRATION:报名(需要先优惠费率报名成功，否则会阻断交易)
PRIVATE_EDUCATION:民办教育
DIRECT:直连
LARGE:特殊
STORE_ASST:门店助手
GONGJIAO:公缴
| OFFLINE |
| promotionType | 活动类型 | string | 否 | | WECHAT_B2B |
| appId | 微信公众号ID | string | 否 | 微信公众号ID/微信小程序ID/支付宝小程序ID/微信SDK的移动应用ID
商家的公众号id，需保证传入的openId是基于该appId获取，微信公众号、微信小程序和支付宝小程序支付需要
| wx012574bf7bc1836d |
| userId | 用户ID | string | 否 | 用户ID用户标识，微信公众号/微信小程序为用户的openId，支付宝生活号/支付宝小程序/银联JS支付为用户的userId 微信公众号/小程序、支付宝生活号/小程序支付时必填；银联JS支付时，与userAuthCode二选一必填
详见聚合统一下单各userid获取方法
| 2088176118911271 、olkcn7obuausx40U8TjVj-5QEdT7 |
| userIp | 用户IP | string | 是 | 用户真实IP地址
已获批开通账户通的平台商，若accountLinkInfo不为空，此userIp必须与accountLinkInfo中的token所包含的IP一致
| 127.12.1.60 |
| channelSpecifiedInfo | 渠道指定支付信息 | string | 否 | 渠道指定支付信息，json格式
参考渠道指定支付信息
| {"hbFqNum":"3","hbFqSellerPercent":"0","sysServiceProviderId":""} |
| channelPromotionInfo | 渠道优惠信息 | string | 否 | 渠道优惠信息
订单需参与渠道指定优惠时传入，如微信单品券
渠道优惠信息JSON说明</a >
| sample_channelPromotionInfo |
| identityInfo | 限制付款人信息 | string | 否 | 限制付款人信息
特殊行业需要支付实名场景下使用，如保险的特殊险种需要付款人和投保人实名。支持微信、支付宝，详见：
聚合限制付款人信息json说明
| {"identityVerifyType":"Y","payerIdType":"IDENTITY_CARD","payerNumber":"234512198006252456","payerName":"名字"} |
| limitCredit | 是否限制贷记卡 | string | 否 | 是否限制贷记卡
Y:仅借记卡可以支付
N:借贷记卡均可支付
| N |
| uniqueOrderNo | 易宝订单号 | string | 否 | 易宝订单号
如果商户使用先下单再支付模式，请传入下单接口返回的易宝订单号
同时传入易宝订单号和token，将以易宝订单号为准
| 1012202101070000001989946571 |
| token | token | string | 否 | 对应参数通过易宝接口“交易下单”的响应获取。如果商户使用先下单再支付模式，请传入下单接口返回的token。
| 83BCDF29CFACB4411533080B67864EF8C907CCDC5E10A707C285FEA10CDB8221 |
| csUrl | 清算回调地址 | string | 否 | 清算成功服务器回调地址，不传则不通知。详见清算结果通知
| sample_csUrl |
| accountLinkInfo | 合作银行信息 | string | 否 | 合作银行信息：
JSON字符串；已获批开通账户通的平台商可传入此字段，否则请勿传值
accountProvider:合作银行
token:商户与银行约定令牌
| {accountProvider":"BOL","token":"xxx"} |
| ypPromotionInfo | 易宝营销信息 | string | 否 | 易宝营销信息json格式；需要参加易宝营销活动的可传入此值；如需参加营销活动，请先联系易宝运营进行配置，否则传入不生效，按无营销活动支付
amount:营销金额（自定义补贴商户时，不需要传参）
type:营销类型
营销类型枚举值：
CUSTOM_REDUCTION:自定义用户支付立减
用户支付金额=订单金额-自定义立减金额
订单入账金额=订单金额
CUSTOM_ALLOWANCE:自定义补贴商户（自定义补贴商户需要在支付清算完成后，发起调用补贴申请）
用户支付金额=订单金额
订单入账金额=订单金额+自定义补贴金额
| 自定义支付立减：[{"amount":"0.01","type":"CUSTOM_REDUCTION"}],自定义补贴商户[{"type":"CUSTOM_ALLOWANCE"}] |
| bankCode | 银行编码 | string | 否 | 银行编码
渠道类型（channel）为数字人民币（DCEP）时必填
BOC:中国银行
ICBC:工商银行
银行编码与名称
| BOC |
| businessInfo | 自定义参数信息 | string | 否 | 自定义参数信息
业务自定义信息json说明
| sample_businessInfo |
| userAuthCode | userAuthCode | string | 否 | 用户授权码，银联JS支付时，与userId二选一必填
| sample_userAuthCode |
| channelActivityInfo | 渠道活动信息 | string | 否 | 渠道活动信息，可供支付宝扫码点餐场景使用
food_order_type：扫码点餐场景码
枚举值：
SELF_PICK:门店自提
TAKE_OUT:餐饮外卖
QR_FOOD_ORDER:扫码点餐
P_QR_FOOD_ORDER:点餐后付
LINE_UP:排队订单
FOOD_ORDER:餐厅预订
| {"food_order_type":"QR_FOOD_ORDER"} |
| terminalId | terminalId | string | 否 | 若交易为线下面对面场景，通过终端发起，请传入终端ID（ID由商户自定义，与终端一一对应）
| sample_terminalId |
| terminalSceneInfo | 商家终端场景信息 | string | 否 | 商家终端场景信息，非必传，可不传。具体请参考示例值
| {"storeId":"门店id","storeName":"门店名称","operatorId":"商户操作员编号","alipayStoreId":"支付宝的店铺编号","areaCode":"门店行政区划码","address":"门店详细地址"} |
| ypAccountBookNo | 记账簿编号 | string | 否 | 记账簿编号
支持收款至预收账户
记账簿编号不为空时，fundProcessType必须上送REAL_TIME
| sample_ypAccountBookNo |
| terminalInfo | 终端信息 | string | 否 | 终端信息
需要在商户后台查询网点信息和交易账单上需要展示网点信息的商户，需要传入此值，否则请勿传值！！！
shopName：网点名称
shopCustomerNumber：网点编号
| {"shopName":"网点名称","shopCustomerNumber":"网点编号"} |
| productInfo | 易宝营销产品信息 | string | 否 | 易宝营销产品信息
本次订单可用的单品券id列表，最大长度512
| [{"id":"random_reduction_pro"}] |
| divideDetail | 分账明细 | string | 否 | 分账明细
fundProcessType为实时分账时，必传。JSON格式：
ledgerNo 分账接收方
amount 分账金额
实时分账的情况下，分账商编无需传入收单商编，除去分给他人的金额，订单剩余可分账金额均会分账给收单商户。
| [{"amount":"金额","ledgerNo":"分账商编","divideDetailDesc":"分账说明"}] |
| divideNotifyUrl | 分账通知地址 | string | 否 | 分账通知地址
分账成功服务器回调地址，不传则不通知
| sample_divideNotifyUrl |
| feeSubsidyInfo | 手续费补贴信息 | string | 否 | 手续费补贴信息
JSON ARRAY格式，只支持上传1条
手续费补贴信息json说明
| [{"subsidyMerchantNo":"10080009498","subsidyAccountType":"FEE_ACCOUNT","subsidyType":"ABSOLUTE","subsidyProportion":"","subsidyCalculateType":"SINGLE_PERCENT","subsidyPercentFee":"0.6","subsidyFixedFee":"","subsidySingleMaxFee":""}] |
| agreementId | 协议ID | string | 否 | 易宝商户自己生成的协议号
微信代扣、云微无感支付需传入此字段
| sample_agreementId |
| creditOrderId | 信用分请求号 | string | 否 | 信用分请求号payWay：CREDIT_PAY时，必传
| sample_creditOrderId |
| payMedium | 支付媒介 | string | 否 | PRECONSUME:预消费
| sample_payMedium |
| receiverAccountType | 接收方账户类型 | string | 否 | DIVIDE_PENDING_ACCOUNT:分账在途账户
支付机构在微信侧的外部商户订单号，用于服务商用于点金计划商户小票功能
| sample_bankOrderId |
| └─ prePayTn | 预支付标识信息 | string | 预支付标识信息 prePayTn使用方式
| sample_prePayTn |
### 响应示例
#### application/json
```json
{
"" : "{}",
"code" : "sample_code",
"orderId" : "sample_orderId",
"bankOrderId" : "sample_bankOrderId",
"prePayTn" : "sample_prePayTn",
"message" : "sample_message",
"uniqueOrderNo" : "sample_uniqueOrderNo"
}
```
## 错误码
| 子错误码 | 子错误码描述 | 解决方案 |
| ------ | ------ | ------ |
| 00000 | 请求成功 | 请求成功
|
| 00001 | 参数错误 | 根据提示检查入参信息
|
| 00011 | 商户状态或信息异常 | 联系技术支持或易宝运营
|
| 00012 | 产品未开通 | 请开通产品后重试
|
| 00013 | 超过额度，请分多笔支付 | 请根据提示信息修改重新请求
|
| 00015 | 云闪付报备失败，请联系服务商 | |
| 00101 | 相同订单号请求信息不同 | 同一订单号重复提交请传入相同订单信息
|
| 00102 | 订单已经成功 | 请更换单号或请求订单查询接口
|
| 00105 | 订单处理中 | 请调用订单查询接口查询支付结果
|
| 00201 | 下单失败 | 请根据提示信息修改重新请求
|
| 00202 | 风控拦截 | 请联系技术支持或易宝运营
|
| 00204 | 支付渠道下单失败
（支付渠道指：银联／网联／微信／支付宝／云闪付） | 请根据提示信息修改重新请求或联系技术支持或易宝运营
|
| 00205 | 支付渠道付款码查询userid异常 | 支付渠道付款码查询userid异常
|
| 00206 | 营销处理失败 | 请根据提示信息修改重新请求或联系技术支持或易宝运营
|
| 00210 | 签约关系不存在 | 请签约成功调用此接口
|
| 00240 | 渠道受理失败:FREQUENCY_LIMITED:频率限制 | |
| 00241 | 渠道受理失败:REQUEST_BLOCKED:当前商户需补齐相关资料后，才可进行相应的支付交易，请商户联系对接的微信支付服务商 | |
| 00242 | 渠道受理失败:ACQ.SECONDARY_MERCHANT_NOT_CONFIRMED:当前商户未认证，请通知商户在支付宝搜索“支付宝商家认证助手”小程序，完成认证后开通交易 | |
| 00244 | 渠道受理失败:690001:请进行appid配置，如已配置请联系易宝运营处理 | |
| 00245 | 渠道受理失败:NOAUTH:此商家涉嫌违规，收款功能已被限制，暂无法支付。商家可以登录微信商户平台/微信支付商家助手小程序查看原因和解决方案。 | |
| 00246 | 渠道受理失败:ACQ.PERM_LIMIT_ERROR:该商户存在交易风险，已被限制收款，请商户前往支付宝安全中心查看详情 | |
| 00248 | 渠道受理失败:690020:指定报备商户号未找到可分流的记录 | |
| 00249 | 渠道受理失败:690026:未找到可用的报备记录 | |
| 00250 | 渠道受理失败:690027:未找到指定报备商户号可用的报备记录 | |
| 02007 | 商户订单已存在,请勿重复支付 | |
| 99999 | 系统异常 | 联系技术支持或易宝运营
|
| BANK_CHANNEL_ORDER_ERROR | 渠道受理失败:600425:APPID不能为空 | |
## 结果通知
| 通知编码 | 通知名称 | 通知描述 | 通知参数参考 |
| ------ | ------ | ------ | ------ |
| trade.pay-result | 支付结果通知 | 支付结果通知
| https://open.yeepay.com/docs-v3/notify/trade.pay-result.md |
| trade.liquidation-result | 清算结果通知 | | https://open.yeepay.com/docs-v3/notify/trade.liquidation-result.md |
## 示例代码
### JAVA
```java
package com.yeepay.yop.sdk.example;
import com.yeepay.yop.sdk.service.common.YopClient;
import com.yeepay.yop.sdk.service.common.YopClientBuilder;
import com.yeepay.yop.sdk.service.common.request.YopRequest;
import com.yeepay.yop.sdk.service.common.response.YopResponse;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
public class Example {
// 该Client线程安全，请使用单例模式，多次请求共用
private static final YopClient client = YopClientBuilder.builder().build();
private static final Logger LOGGER = LoggerFactory.getLogger(Example.class);
public static void main(String[] args) {
YopRequest request = new YopRequest("/rest/v1.0/aggpay/pre-pay", "POST");
request.addParameter("parentMerchantNo", "10012426765");
request.addParameter("merchantNo", "10012426765");
request.addParameter("orderId", "ORDER202401010515217305372872");
request.addParameter("orderAmount", "0.01");
request.addParameter("expiredTime", "2019-10-01 00:00:00");
request.addParameter("notifyUrl", "https://notify.merchant.com/xxx");
request.addParameter("redirectUrl", "https://notify.merchant.com/xxx");
request.addParameter("memo", "memo_example");
request.addParameter("goodsName", "旺仔牛奶");
request.addParameter("fundProcessType", "REAL_TIME");
request.addParameter("payWay", "USER_SCAN");
request.addParameter("channel", "ALIPAY");
request.addParameter("scene", "OFFLINE");
request.addParameter("promotionType", "WECHAT_B2B");
request.addParameter("appId", "wx012574bf7bc1836d");
request.addParameter("userId", "2088176118911271 、olkcn7obuausx40U8TjVj-5QEdT7");
request.addParameter("userIp", "127.12.1.60");
request.addParameter("channelSpecifiedInfo", "{\"hbFqNum\":\"3\",\"hbFqSellerPercent\":\"0\",\"sysServiceProviderId\":\"\"}");
request.addParameter("channelPromotionInfo", "channelPromotionInfo_example");
request.addParameter("identityInfo", "{\"identityVerifyType\":\"Y\",\"payerIdType\":\"IDENTITY_CARD\",\"payerNumber\":\"234512198006252456\",\"payerName\":\"名字\"}");
request.addParameter("limitCredit", "N");
request.addParameter("uniqueOrderNo", "1012202101070000001989946571");
request.addParameter("token", "83BCDF29CFACB4411533080B67864EF8C907CCDC5E10A707C285FEA10CDB8221");
request.addParameter("csUrl", "csUrl_example");
request.addParameter("accountLinkInfo", "{accountProvider\":\"BOL\",\"token\":\"xxx\"}");
request.addParameter("ypPromotionInfo", "自定义支付立减：[{\"amount\":\"0.01\",\"type\":\"CUSTOM_REDUCTION\"}],自定义补贴商户[{\"type\":\"CUSTOM_ALLOWANCE\"}]");
request.addParameter("bankCode", "BOC");
request.addParameter("businessInfo", "businessInfo_example");
request.addParameter("userAuthCode", "userAuthCode_example");
request.addParameter("channelActivityInfo", "{\"food_order_type\":\"QR_FOOD_ORDER\"}");
request.addParameter("terminalId", "terminalId_example");
request.addParameter("terminalSceneInfo", "{\"storeId\":\"门店id\",\"storeName\":\"门店名称\",\"operatorId\":\"商户操作员编号\",\"alipayStoreId\":\"支付宝的店铺编号\",\"areaCode\":\"门店行政区划码\",\"address\":\"门店详细地址\"}");
request.addParameter("ypAccountBookNo", "ypAccountBookNo_example");
request.addParameter("terminalInfo", "{\"shopName\":\"网点名称\",\"shopCustomerNumber\":\"网点编号\"}");
request.addParameter("productInfo", "[{\"id\":\"random_reduction_pro\"}]");
request.addParameter("divideDetail", "[{\"amount\":\"金额\",\"ledgerNo\":\"分账商编\",\"divideDetailDesc\":\"分账说明\"}]");
request.addParameter("divideNotifyUrl", "divideNotifyUrl_example");
request.addParameter("feeSubsidyInfo", "[{\"subsidyMerchantNo\":\"10080009498\",\"subsidyAccountType\":\"FEE_ACCOUNT\",\"subsidyType\":\"ABSOLUTE\",\"subsidyProportion\":\"\",\"subsidyCalculateType\":\"SINGLE_PERCENT\",\"subsidyPercentFee\":\"0.6\",\"subsidyFixedFee\":\"\",\"subsidySingleMaxFee\":\"\"}]");
request.addParameter("agreementId", "agreementId_example");
request.addParameter("creditOrderId", "creditOrderId_example");
request.addParameter("payMedium", "payMedium_example");
request.addParameter("receiverAccountType", "receiverAccountType_example");
try {
YopResponse response = client.request(request);
LOGGER.info("result:{}", response.getResult());
} catch (Exception ex) {
LOGGER.error("Exception when calling, ex:", ex);
}
}
}
```