alipay.marketing.coupon.template.create(创建红包模板) 在线调试(沙箱环境)

创建带有资金的红包模板

公共参数

请求地址

环境HTTPS请求地址
正式环境 https://openapi.alipay.com/gateway.do

公共请求参数

参数 类型 是否必填最大长度描述示例值
app_id String 32 支付宝分配给开发者的应用ID 2014072300007148
method String 128 接口名称 alipay.marketing.coupon.template.create
format String 40 仅支持JSON JSON
charset String 10 请求使用的编码格式,如utf-8,gbk,gb2312等 utf-8
sign_type String 10 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 RSA2
sign String 344 商户请求参数的签名串,详见签名 详见示例
timestamp String 19 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" 2014-07-24 03:07:50
version String 3 调用的接口版本,固定为:1.0 1.0
app_auth_token String 40 详见应用授权概述
biz_content String 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档

请求参数

参数 类型 是否必填 最大长度 描述 示例值
voucher_type String 必选 16 类型。可枚举,暂时只支持"红包"(COUPON),使用示例voucher_type=COUPON。红包可以拆分多次使用,比如:1元红包,可以先用掉0.5元,剩余的0.5元可以继续使用;可以多个红包叠加使用,一笔支付最多叠加10个红包;红包被使用后发生退款,如果红包有效期还在,会退还给用户红包,如果有效期已过,就会将资金退回原红包模板出资账户。 COUPON
voucher_use_scene String 必选 16 红包使用场景。可枚举,目前支持“支付宝通用全场红包”(ALIPAY_COUPON_ALL) ,该场景设置后,使用规则字段允许为空,只要支付宝支付产品支持核销此类型的红包,用户红包就可以核销。“花呗还款红包”(HUABEI_COUPON_REPAYMENT) ,该场景设置后,会自动填充花呗还款对应的规则,无需填入rule_conf,代表仅花呗还款场景可以核销此红包。“支付宝普通红包”(ALIPAY_COUPON_COMMON) 该场景下必须设置一条规则rule_conf。场景值会关联当前红包的展示模板,默认描述等信息。 HUABEI_COUPON_REPAYMENT
fund_account String 必选 64 出资人登录账号。用于发红包的资金会从该账号划拨到发红包专用账户上。当调用创建接口成功后,会返回付款订单页面,仅当前传入资金账号可进行付款,付款完成后红包变更为激活状态,可进行发放。 13040045386
brand_name String 必选 12 创建红包模板时录入的品牌信息,由商户自定义,在通用模板中展示在红包LOGO下方。根据红包使用场景的不同,该信息的展示位置可能会有不同。 支付宝
publish_start_time Date 必选 19 发放开始时间,早于该时间不能发红包。发放开始时间不能大于当前时间15天。格式为:yyyy-MM-dd HH:mm:ss 2018-06-10 00:00:01
publish_end_time Date 必选 19 发放结束时间,晚于该时间不能发红包。红包的发放结束时间和发放开始时间跨度不能大于90天。发放结束时间必须晚于发放开始时间。格式为:yyyy-MM-dd HH:mm:ss 2018-07-29 23:59:59
voucher_valid_period String 必选 128 "ABSOLUTE", "start": "2017-01-10 00:00:00", "end": "2017-01-13 23:59:59"}。相对时间有3个key:type、duration、unit,type取值固定为"RELATIVE",duration表示从发红包时间开始到往后推duration个单位时间为止作为红包的使用有效期,unit表示有效时间单位,有效时间单位可枚举:MINUTE, HOUR, DAY。示例:{"type": "RELATIVE", "duration": 1 , "unit": "DAY" },如果此刻发红包,那么该红包从现在开始生效1(duration)天(unit)后失效。 {"type": "ABSOLUTE", "start": "2018-06-10 00:00:00","end": "2018-07-13 23:59:59"}
floor_amount Price 必选 10 最低额度。设置红包使用门槛,只有订单金额大于等于最低额度时红包才能使用。币种为人民币,单位为元。该数值不能小于等于0,小数点以后最多保留两位,没有则设置为0。 0
voucher_description String 可选 509 红包使用说明。JSON数组字符串,最多可以有10条,每条最多50字。如果未传入该字段,将填充为默认描述 ["1、本红包不可兑换现金,不可转增。","2、可以叠加使用,不限使用次数。"]
out_biz_no String 必选 64 外部业务单号。用作幂等控制。同一个pid下相同的外部业务单号作唯一键,参数不变的情况下,再次请求返回同样的模板id。请求成功后,修改参数再次提交,需要更换订单号 20180601000001654bb46ba
total_amount Price 必选 10 模板总金额。本次发放模板设置的总金额。币种为人民币,单位为元。该数值不能小于1.00元,小数点以后最多保留两位。 100.05
redirect_uri String 可选 1024 重定向地址。支付成功后需要重定向的地址,如果为空则不做重定向。 https://www.yourdomain.com/alipay/pay/success
notify_uri String 可选 128 红包变动异步通知地址,传入此字段后,红包的核销将会进行异步通知,通知具体内容见下方触发异步通知字段描述 https://www.yourdomain.com/reieve/voucher/flux
rule_conf String 可选 1024 规则配置,JSON字符串,格式为K-V模式,当同一个KEY下规则为多个值时,用英文逗号进行分隔。目前支持的规则KEY有:核销商户ID(PID),核销内部门店ID(STORE),指定收款账户(payeeUserId),子产品交易码(bizProduct),缴费机构/类型(CUSTOMBUSINESS),缴费户号(EBPPUSERNUM)。一旦商户设置了规则,当前红包实例必须满足指定规则才能进行核销。 {"PID": "2088512417841101,2088512417841102", "STORE": "123456,678901"}
extension_info String 可选 1024 扩展字段,JSON字符串。目前支持使用模式扩展:{"coupon_AppActiveUrl":"http://www.yourdomain.com"},yourdomain.com需要添加白名单 {"coupon_AppActiveUrl":"http://www.yourdomain.com"}

响应参数

参数 类型 是否必填 最大长度 描述 示例值
template_id String 必填 32 红包模板ID 20140601000730010040000000EB
fund_order_no String 必填 32 资金订单号,模板支付时需要 2017011910002001200202502849
confirm_uri String 必填 256 模板支付确认链接 https://promocenter.alipay.com/voucher/templatePayment.htm?templateId= 20140601000730010040000000EB

请求示例

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayMarketingCouponTemplateCreateRequest request = new AlipayMarketingCouponTemplateCreateRequest();
request.setBizContent("{" +
"\"voucher_type\":\"COUPON\"," +
"\"voucher_use_scene\":\"HUABEI_COUPON_REPAYMENT\"," +
"\"fund_account\":\"13040045386\"," +
"\"brand_name\":\"支付宝\"," +
"\"publish_start_time\":\"2018-06-10 00:00:01\"," +
"\"publish_end_time\":\"2018-07-29 23:59:59\"," +
"\"voucher_valid_period\":\"{\\\"type\\\": \\\"ABSOLUTE\\\", \\\"start\\\": \\\"2018-06-10 00:00:00\\\",\\\"end\\\": \\\"2018-07-13 23:59:59\\\"}\"," +
"\"floor_amount\":0," +
"\"voucher_description\":\"[\\\"1、本红包不可兑换现金,不可转增。\\\",\\\"2、可以叠加使用,不限使用次数。\\\"]\"," +
"\"out_biz_no\":\"20180601000001654bb46ba\"," +
"\"total_amount\":100.05," +
"\"redirect_uri\":\"https://www.yourdomain.com/alipay/pay/success\"," +
"\"notify_uri\":\"https://www.yourdomain.com/reieve/voucher/flux\"," +
"\"rule_conf\":\"{\\\"PID\\\": \\\"2088512417841101,2088512417841102\\\", \\\"STORE\\\": \\\"123456,678901\\\"}\"," +
"\"extension_info\":\"{\\\"coupon_AppActiveUrl\\\":\\\"http://www.yourdomain.com\\\"}\"" +
"  }");
AlipayMarketingCouponTemplateCreateResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

响应示例

{
    "alipay_marketing_coupon_template_create_response": {
        "code": "10000",
        "msg": "Success",
        "template_id": "20140601000730010040000000EB",
        "fund_order_no": "2017011910002001200202502849",
        "confirm_uri": "https://promocenter.alipay.com/voucher/templatePayment.htm?templateId= 20140601000730010040000000EB"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

异常示例

{
    "alipay_marketing_coupon_template_create_response": {
        "code": "20000",
        "msg": "Service Currently Unavailable",
        "sub_code": "isp.unknow-error",
        "sub_msg": "系统繁忙"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

业务错误码

公共错误码

错误码错误描述解决方案
INVALID_PARAMETER 参数有误业务异常参数有误,日期数据格式错误 日期格式必须为 yyyy-MM-dd HH:mm:ss
INVALID_PARAMETER 参数有误无效的相对时间单位 时间单位必须为天(DAY),小时(HOUR),分钟(MINUTE)
INVALID_PARAMETER 参数有误 请按照文档检查参数
SYSTEM_ERROR 系统繁忙 1.发起业务重试
SYSTEM_ERROR 系统繁忙 1.发起业务重试
SYSTEM_ERROR 系统繁忙 1.发起业务重试
SYSTEM_ERROR 系统繁忙 1.发起业务重试
SYSTEM_ERROR 系统繁忙 1.发起业务重试
INVALID_PARAMETER 参数有误参数有误传入规则有误 按照说明文档修改传入规则后重试
BIZ_ERROR 业务异常业务异常传入业务参数中包含敏感词 请重新修改对应的业务参数
INVALID_PARAMETER 参数有误有效期格错误 检查红包有效期字段,修复后重新传入
INVALID_PARAMETER 参数有误传入的红包类型错误 传入的红包类型未定义或暂不支持,请修改红包类型字段至约定值
INVALID_PARAMETER 参数有误付款账号不存在 传入的付款账户不存在,请修改后重新传入
INVALID_PARAMETER 参数有误无效的时间 1.发放开始不能大于当前时间15天。 2.红包的发放有效期跨度不能大于90天。
INVALID_PARAMETER 参数有误对应红包场景不存在 按照文档修改红包场景后重试
INVALID_PARAMETER 参数有误门槛金额设置有误 应大于等于0元
INVALID_PARAMETER 参数有误模板总金额有误 1. 金额必须大于1元。2. 金额不能超过当前业务最高限额,参考最高限额,10000000元
onlineServer