alipay.marketing.cashvoucher.template.create(创建资金券模板) 在线调试(沙箱环境)

创建带有资金的券模板

公共参数

请求地址

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

公共请求参数

参数 类型 是否必填最大长度描述示例值
app_id String 32 支付宝分配给开发者的应用ID 2014072300007148
method String 128 接口名称 alipay.marketing.cashvoucher.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
notify_url String 256 支付宝服务器主动通知商户服务器里指定的页面http/https路径。 http://api.test.alipay.net/atinterface/receive_notify.htm
app_auth_token String 40 详见应用授权概述
biz_content String 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档

请求参数

参数 类型 是否必填 最大长度 描述 示例值
voucher_type String 必选 16 券类型。可枚举,暂时只支持"代金券"(FIX_VOUCHER),使用示例voucher_type=FIX_VOUCHER FIX_VOUCHER
voucher_use_scene String 必选 16 券使用场景。可枚举,目前支持“支付宝充值中心话费流量通用现金券”(ALIPAY_RECHARGE),“支付宝缴费业务代金券”(ALIPAY_FEE),“支付宝通用现金代金券”(ALIPAY_COMMON)。场景值会关联当前券的展示模板,默认描述等信息,若需特殊场景接入,请联系技术支持。 ALIPAY_RECHARGE
fund_account String 必选 64 出资人登录账号。用于发券的资金会从该账号划拨到发券专用账户上。当调用创建接口成功后,会返回付款订单页面,仅当前传入资金账号可进行付款,付款完成后券变更为激活状态,可进行发放。 13040045386
brand_name String 必选 12 创建券模板时录入的品牌信息,由商户自定义,在通用模板中展示在券LOGO下方。根据券使用场景的不同,该信息的展示位置可能会有不同。 支付宝
publish_start_time Date 必选 19 发放开始时间,早于该时间不能发券。发放开始时间不能大于当前时间15天。格式为:yyyy-MM-dd HH:mm:ss 2017-01-01 00:00:01
publish_end_time Date 必选 19 发放结束时间,晚于该时间不能发券。券的发放结束时间和发放开始时间跨度不能大于90天。发放结束时间必须晚于发放开始时间。格式为:yyyy-MM-dd HH:mm:ss 2017-01-29 23:59:59
voucher_valid_period String 必选 128 券有效期。有两种类型:绝对时间和相对时间。使用JSON字符串表示。绝对时间有3个key:type、start、end,type取值固定为"ABSOLUTE",start和end分别表示券生效时间和失效时间,格式为yyyy-MM-dd HH:mm:ss。绝对时间示例:{"type": "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": "2017-01-10 00:00:00","end": "2017-01-13 23:59:59"}
floor_amount Price 必选 10 最低额度。设置券使用门槛,只有订单金额大于等于最低额度时券才能使用。币种为人民币,单位为元。该数值不能小于0,小数点以后最多保留两位。 50.0
voucher_description String 可选 509 券使用说明。JSON数组字符串,最多可以有10条,每条最多50字。如果未传入该字段,将填充为默认描述 ["1、本券不可兑换现金,不可找零。","2、每个用户最多可以领取1张。","3、如果订单发生退款,优惠券无法退还。"]
out_biz_no String 必选 64 外部业务单号。用作幂等控制。同一个pid下相同的外部业务单号作唯一键,参数不变的情况下,再次请求返回同样的模板id。请求成功后,修改参数再次提交,需要更换订单号。 20170101000001654bb46ba
amount Price 必选 10 面额。每张代金券可以抵扣的金额。币种为人民币,单位为元。该数值不能小于0.1,小数点以后最多保留两位。 8.8
voucher_quantity Number 必选 10 拟发行券的数量。单位为张。该数值必须是大于0的整数。 1000000
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字符串。目前支持使用模式扩展:{"useMode":"H5","useModeData":{"url":"http://www.yourdomian.com/yourusepage.htm","signKeys":"voucherId,userId,tag","charset":"UTF-8","signType":"RSA2","tag":"this is my tag"}}
其中如果useMode表示自定义的使用模式类型,目前仅支持"H5",表示在券详情页按钮跳转至自定义H5页面,当传入useMode参数后,将会检查useModeData对象数据,其中的url为必传参数;url字段表示客制化使用按钮跳转链接,传入该字段后在券详情使用时点击效果将会跳转此链接,链接将进行白名单过滤,如果无法接入成功请联系技术支持;signKeys字段表示跳转至客制链接时的加签字段,如果不传默认为voucherId,userId,tag;signType为加签类型,目前支持RSA及RSA2,如果不传则不会加签;charset为链接编码格式,不传默认为UTF-8;tag为自定义参数,会直接透传回使用链接;当传入合法加签信息后,券使用链接将为http://www.yourdomain.com/yourusepage.htm?voucherId=当前券id&userId=当前用户id&tag=传入tag&sign=对应算法及key生成的加签数据
{"useMode":"H5","useModeData":{"url":"http://www.yourdomian.com/yourusepage.htm","signType":"RSA2"}}

响应参数

参数 类型 是否必填 最大长度 描述 示例值
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");
AlipayMarketingCashvoucherTemplateCreateRequest request = new AlipayMarketingCashvoucherTemplateCreateRequest();
request.setBizContent("{" +
"\"voucher_type\":\"FIX_VOUCHER\"," +
"\"voucher_use_scene\":\"ALIPAY_RECHARGE\"," +
"\"fund_account\":\"13040045386\"," +
"\"brand_name\":\"支付宝\"," +
"\"publish_start_time\":\"2017-01-01 00:00:01\"," +
"\"publish_end_time\":\"2017-01-29 23:59:59\"," +
"\"voucher_valid_period\":\"{\\\"type\\\": \\\"ABSOLUTE\\\", \\\"start\\\": \\\"2017-01-10 00:00:00\\\",\\\"end\\\": \\\"2017-01-13 23:59:59\\\"}\"," +
"\"floor_amount\":50.0," +
"\"voucher_description\":\"[\\\"1、本券不可兑换现金,不可找零。\\\",\\\"2、每个用户最多可以领取1张。\\\",\\\"3、如果订单发生退款,优惠券无法退还。\\\"]\"," +
"\"out_biz_no\":\"20170101000001654bb46ba\"," +
"\"amount\":8.8," +
"\"voucher_quantity\":1000000," +
"\"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\":\"{\\\"useMode\\\":\\\"H5\\\",\\\"useModeData\\\":{\\\"url\\\":\\\"http://www.yourdomian.com/yourusepage.htm\\\",\\\"signType\\\":\\\"RSA2\\\"}}\"" +
"  }");
AlipayMarketingCashvoucherTemplateCreateResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

响应示例

{
    "alipay_marketing_cashvoucher_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_cashvoucher_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 参数有误业务异常参数有误,券张数格式错误 必须是大于0的整数
INVALID_PARAMETER 参数有误参数有误,无效的券面额 1. 面额必须大于0元。2. 代金券面额不能小于最小面额。3. 代金券不能高于最大面额。4. 代金券面额与门槛金额比率不能低于最小比率
INVALID_PARAMETER 参数有误参数有误,无效的门槛金额 门槛金额应大于0元
INVALID_PARAMETER 参数有误参数有误,无效的时间 1.发放开始不能大于当前时间15天。 2.券的发放有效期跨度不能大于90天。
INVALID_PARAMETER 参数有误参数有误,无效的相对时间单位 时间单位必须为天(DAY),小时(HOUR),分钟(MINUTE)
INVALID_PARAMETER 参数有误 请按照文档检查参数
SYSTEM_ERROR 系统繁忙 1.发起业务重试 2.联系技术支持
SYSTEM_ERROR 系统繁忙 1.发起业务重试 2.联系技术支持
SYSTEM_ERROR 系统繁忙 1.发起业务重试 2.联系技术支持
SYSTEM_ERROR 系统繁忙 1.发起业务重试 2.联系技术支持
SYSTEM_ERROR 系统繁忙 1.发起业务重试 2.联系技术支持
INVALID_PARAMETER 参数有误对应券场景不存在 按照文档修改券场景后重试
INVALID_PARAMETER 参数有误传入规则有误 按照说明文档修改传入规则后重试
BIZ_ERROR 业务异常传入业务参数中包含敏感词 请重新修改对应的业务参数
INVALID_PARAMETER 参数有误券有效期格错误 检查券有效期字段,修复后重新传入
INVALID_PARAMETER 参数有误传入的券类型错误 传入的券类型未定义或暂不支持,请修改券类型字段至约定值
INVALID_PARAMETER 参数有误付款账号不存在 传入的付款账户不存在,请修改后重新传入

触发通知类型

通知类型描述默认开启
voucher.use 若在创建券模板时传入了notify_uri字段并且有效,当创建的券产生核销行为时会执行调用 0

触发通知示例

https://www.merchant.com/receive_notify.htm?notify_type=trade_status_sync&notify_id=91722adff935e8cfa58b3aabf4dead6ibe&notify_time=2017-02-16 21:46:15&sign_type=RSA2&sign=WcO+t3D8Kg71dTlKwN7r9PzUOXeaBJwp8/FOuSxcuSkXsoVYxBpsAidprySCjHCjmaglNcjoKJQLJ28/Asl93joTW39FX6i07lXhnbPknezAlwmvPdnQuI01HZsZF9V1i6ggZjBiAd5lG8bZtTxZOJ87ub2i9GuJ3Nr/NUc9VeY=&notify_type=vcc_voucher_flux_notify&status=V_USE&biz_content={"alipay_biz_no":"123","biz_time":"2017-11-11 00:00:00","flux_amount":"5.00","voucher_id":"456":"partnerId":"201732321321"}
onlineServer