开放平台
第一步：创建应用
要在您的应用中使用支付宝开放产品的接口能力，您需要先去蚂蚁金服开放平台（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 |
第四步：接口调用
调用流程
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 |
要查询的活动状态，不填默认返回所有类型。可填写：
|
| 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 |
原始活动号，商户排查问题时提供的活动依据。 |
关于沙箱
如何接入沙箱
沙箱环境是开放平台提供给开发者调试接口的环境，具体操作步骤见 沙箱接入指南。
蚂蚁现金红包沙箱接入注意点
- 蚂蚁现金红包涉及到的创建、领取、查询、修改活动操作均支持沙箱接入；在沙箱联调成功后，必须在线上进行测试与验收，返回的业务码以及业务逻辑以线上逻辑为准。
- 商户账号、用户账号请直接使用沙箱的测试账号：点击开发者中心-沙箱环境-沙箱账号。
- 联调前，需先对接收单类产品，如即时到账、手机网站支付、APP支付、当面付等，并完成一笔收单交易，以便沙箱商家账户余额有足够资金进行红包付款。
- 现金红包后台列表页面暂不支持沙箱，沙箱环境也无法查看对账单，请以线上实际效果为准。
