营销活动送红包快速接入

第一步:创建应用

要在您的应用中使用支付宝开放产品的接口能力,您需要先去蚂蚁金服开放平台(open.alipay.com),在管理中心中创建登记您的应用,并提交审核,审核通过后会为您生成应用唯一标识(APPID),并且可以申请开通开放产品使用权限,通过APPID您的应用才能调用开放产品的接口能力。需要详细了解开放平台创建应用步骤请参考《开放平台应用创建指南》。

第二步:配置密钥

开发者调用接口前需要先生成RSA密钥,RSA密钥包含应用私钥(APP_PRIVATE_KEY)、应用公钥(APP_PUBLIC_KEY)。生成密钥后在开放平台管理中心进行密钥配置,配置完成后可以获取支付宝公钥(ALIPAY_PUBLIC_KEY)。详情请参考《配置应用环境》。

第三步:搭建和配置开发环境

1.下载服务端SDK 

为了帮助开发者调用开放接口,我们提供了开放平台服务端SDK,包含JAVA、PHP和.NET三个语言版本,封装了签名&验签、HTTP接口请求等基础功能。请先下载对应语言版本的SDK并引入您的开发工程。

各语言版本服务端SDK详细使用说明,请参考《服务端SDK使用说明

2.接口调用配置

在SDK调用前需要进行初始化,代码如下:

AlipayClient alipayClient = new DefaultAlipayClient(URL,APP_ID,APP_PRIVATE_KEY,FORMAT,CHARSET,APP_PUBLIC_KEY,SIGN_TYPE);

关键参数说明:

配置参数 示例值解释 获取方式/示例值
URL 支付宝网关(固定) https://openapi.alipay.com/gateway.do
APPID APPID 即创建应用后生成 获取见上面创建应用
FORMAT 参数返回格式,只支持json json(固定)
APP_PRIVATE_KEY 开发者私钥,由开发者自己生成 获取详见上面配置密钥
CHARSET 编码集,支持GBK/UTF-8 开发者根据实际工程编码配置
ALIPAY_PUBLIC_KEY 支付宝公钥,由支付宝生成 获取详见上面配置密钥
SIGN_TYPE 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 RSA2
TIPS:ISV/开发者可以通过“第三方应用授权”得到商户授权令牌(app_auth_token)作为请求参数传入,实现代商户发起请求的能力;具体方法请参考第三方应用授权

第四步:接口调用

调用流程

SDK接入

1. 创建现金活动接口alipay.marketing.campaign.cash.create

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayMarketingCampaignCashCreateRequest request = new AlipayMarketingCampaignCashCreateRequest();
request.setBizContent("{" +
"    \"coupon_name\":\"XXX周年庆红包\"," +
"    \"prize_type\":\"random\"," +
"    \"total_money\":\"10000000.00\"," +
"    \"total_num\":\"1000\"," +
"    \"prize_msg\":\"XXX送您大红包\"," +
"    \"start_time\":\"NowTime\"," +
"    \"end_time\":\"2016-09-20 22:48:30\"," +
"    \"merchant_link\":\"http://www.koubei.com\"," +
"    \"send_freqency\":\"D3|L10\"" +
"  }");
AlipayMarketingCampaignCashCreateResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

关键入参:

参数名称 参数说明

coupon_name

红包名称,商户通过接口查询自己创建的红包列表和红包详情时可以看到,这是一个内部信息,便于商户识别红包。同时也会显示在商户付款页面。

prize_type

现金红包的发放形式,fixed为固定金额,random为随机金额。

total_money

活动发放的现金总金额,最小金额1.00元,最大金额10000000.00元。

每个红包的最大金额不允许超过200.00元,最小金额不允许低于0.2元。

total_num

红包发放个数,最小1个,最大10000000个。

但不同的发放形式(即prize_type)会使得含义不同:

(1) 若prize_type选择为固定金额,每个用户领取的红包金额为total_money除以total_num得到固定金额。

(2) 若prize_type选择为随机金额,每个用户领取的红包金额为total_money除以total_num得到的平均金额值的0.5~1.5倍。由于金额是随机的,在红包金额全部被领取完时,有可能total_num有所剩余、或者大于设置值的情况。

prize_msg

活动文案,用户在支付宝App的账单中看到的账单里的红包描述。

start_time

活动开始时间,必须大于活动创建的时间。

(1) 填写固定时间,格式为:yyyy-MM-dd HH:mm:ss,例如:2016-08-10 22:28:30

(2) 填字符串NowTime

end_time

活动结束时间,必须大于活动开始时间,格式为:yyyy-MM-dd HH:mm:ss,活动有效时间最长为6个月,过期后需要创建新的活动。

merchant_link

商户打款后的跳转链接,从支付宝收银台打款成功后的跳转链接。不填时,打款后停留在支付宝支付成功页。商户实际跳转会自动添加crowdNo作为跳转参数。示例: http://www.alipay.com?crowdNo=XXX 

send_freqency

对于用户参与当前活动次数、频率的限制。支持日(D)、周(W)、月(M)、终身(L)维度的限制。其中日(D)、周(W)、月(M)最多只能选择一个,终身(L)为必填项。多个配置之间使用“|”进行分隔。终身(L)次数限制最大为100,日(D)、周(W)、月(M)频率设置必须小于等于终身(L)的次数。整个字段不填时默认值为L1。

配置次数限制后,触发接口需要填入out_biz_no来实现多次领取。

关键出参:

参数名称 参数说明

crowd_no

生成的现金红包活动号。

pay_url

活动创建后的付款链接,返回的是urlencode编码后的字符串。需要先进行urldecode解码,然后在浏览器中进行访问,会先进行支付宝登录引导,然后商户进行付款

origin_crowd_no

原始活动号,商户排查问题时提供的活动依据。

2.  触发现金红包活动接口alipay.marketing.campaign.cash.trigger

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayMarketingCampaignCashTriggerRequest request = new AlipayMarketingCampaignCashTriggerRequest();
request.setBizContent("{" +
"    \"user_id\":\"2088102164186692\"," +
"    \"crowd_no\":\"3DpriXtAGxmDPi7QyeoKeX8wwS3qbKCcnigowys220Lxs\"," +
"    \"login_id\":\"username@gmail.com\"," +
"    \"out_biz_no\":\"201702101356\"" +
"  }");
AlipayMarketingCampaignCashTriggerResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

关键入参:

参数名称 参数说明

crowd_no

现金红包活动号。

user_id

用户唯一标识userId。user_id与login_id至少有一个非空;都非空时,以user_id为准。

login_id

用户登录账号名:邮箱或手机号。user_id与login_id至少有一个非空,都非空时,以user_id为准。

out_biz_no

领取红包的外部业务号,只由可由字母、数字、下划线组成。同一个活动中不可重复,相同的外部业务号会被幂等并返回之前的结果。不填时,系统会使用默认固定的外部业务号。

关键出参:

参数名称 参数说明

trigger_result

是否中奖结果状态,如果为true时返回的结果中的其他字段非空,否则返回的其他字段为空。

prize_amount

现金红包金额,发奖成功时非空,千分位格式,保留两位小数。

repeat_trigger_flag

一个用户只能领取一次。用户是否重复领取,如果重复领取,返回的是之前的中奖结果,如果是首次领取,则走发放流程。

partner_id

发送红包商户签约PID,发奖成功时非空。

error_msg

用户领取失败的错误信息返回的描述。

coupon_name

红包名称,创建活动时设置,用于账单列表和详情、红包列表和详情的展示。

prize_msg

活动文案,用户在支付宝App的账单中看到的红包描述。

merchant_logo

商户头像logo的图片url地址,会自动读取支付宝账户头像,若没有头像则为空。用于账单和红包列表、详情的展示。

biz_no

支付宝业务号,发奖成功时返回,调用者可提供此字符串进行问题排查与核对等。

out_biz_no

外部业务号,回填请求中的out_biz_no,调用者可用于日志记录与核对等。

3. 更改现金活动状态接口alipay.marketing.campaign.cash.status.modify

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayMarketingCampaignCashStatusModifyRequest request = new AlipayMarketingCampaignCashStatusModifyRequest();
request.setBizContent("{" +
"    \"crowd_no\":\"HHV-vl7IKtHddoWgpHTOdL_KQRIpfQbl47xfRmmPBlDMnSZ96O-zxUfKlHp5cxmx\"," +
"    \"camp_status\":\"PAUSE\"" +
"  }");
AlipayMarketingCampaignCashStatusModifyResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

关键入参:

参数名称 参数说明

crowd_no

现金红包活动号。

camp_status

修改后的活动状态,PAUSE或者READY。只有PAUSE或者READY状态的活动可以被修改。

4. 现金活动列表查询接口alipay.marketing.campaign.cash.list.query

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayMarketingCampaignCashListQueryRequest request = new AlipayMarketingCampaignCashListQueryRequest();
request.setBizContent("{" +
"    \"camp_status\":\"PAID\"," +
"    \"page_size\":\"10\"," +
"    \"page_index\":\"1\"" +
"  }");
AlipayMarketingCampaignCashListQueryResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

关键入参:

参数名称 参数说明

camp_status

要查询的活动状态,不填默认返回所有类型。可填写:

  • ALL:所有类型的活动
  • CREATED:已创建未打款
  • PAID:已打款
  • READY:活动已开始
  • PAUSE:活动已暂停
  • CLOSED:活动已结束
  • SETTLE:活动已清算

page_size

分页查询时每页返回的记录条数,最大为50。

page_index

分页查询时的页码,从1开始。

关键出参:

参数名称 参数说明

page_size

分页查询时每页返回的记录条数,最大为50。

camp_list

活动列表。包括现金活动号、名称、状态。

page_index

分页的页码,起始从1开始。

total_size

活动总个数。

5. 现金活动详情查询接口alipay.marketing.campaign.cash.detail.query

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayMarketingCampaignCashDetailQueryRequest request = new AlipayMarketingCampaignCashDetailQueryRequest();
request.setBizContent("{" +
"    \"crowd_no\":\"POYb84lfiKVdIfERAYsqPL_KQRIpfQbl47xfRmmPBlDMnSZ96O-zxUfKlHp5cxmx\"" +
"  }");
AlipayMarketingCampaignCashDetailQueryResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

关键入参:

参数名称 参数说明

crowd_no

要查询的现金红包活动号。

关键出参:

参数名称 参数说明

crowd_no

现金红包活动号。

coupon_name

现金红包名称。

prize_msg

活动文案,用户在支付宝App的账单中看到的红包描述。

prize_type

现金红包的发放形式,fixed为固定金额,random为随机金额。

start_time

活动开始时间。

end_time

活动结束时间。

total_amount

活动总金额。

send_amount

活动已发放金额。

total_num

红包总个数。

origin_crowd_no

原始活动号,商户排查问题时提供的活动依据。

关于沙箱

如何接入沙箱

沙箱环境是开放平台提供给开发者调试接口的环境,具体操作步骤见 沙箱接入指南

蚂蚁现金红包沙箱接入注意点

  1. 蚂蚁现金红包涉及到的创建、领取、查询、修改活动操作均支持沙箱接入;在沙箱联调成功后,必须在线上进行测试与验收,返回的业务码以及业务逻辑以线上逻辑为准。
  2. 商户账号、用户账号请直接使用沙箱的测试账号:点击开发者中心-沙箱环境-沙箱账号
  3. 联调前,需先对接收单类产品,如即时到账、手机网站支付、APP支付、当面付等,并完成一笔收单交易,以便沙箱商家账户余额有足够资金进行红包付款。
  4. 现金红包后台列表页面暂不支持沙箱,沙箱环境也无法查看对账单,请以线上实际效果为准。
onlineServer