开放平台
第一步：创建应用
要在您的应用中使用支付宝开放产品的接口能力，您需要先去蚂蚁金服开放平台（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, ALIPAY_PUBLIC_KEY, SIGN_TYPE);
关键参数说明:
| 配置参数 | 示例值解释 | 获取方式/示例值 |
|---|---|---|
| URL | 支付宝网关（固定） | https://openapi.alipay.com/gateway.do |
| APPID | APPID 即创建应用后生成 | 获取见上面创建应用并获取APPID |
| APP_PRIVATE_KEY | 开发者私钥，由开发者自己生成 | 获取详见上面配置密钥 |
| FORMAT | 参数返回格式，只支持json | json（固定） |
| CHARSET | 编码集，支持GBK/UTF-8 | 开发者根据实际工程编码配置 |
| ALIPAY_PUBLIC_KEY | 支付宝公钥，由支付宝生成 | 获取详见上面配置密钥 |
| SIGN_TYPE | 商户生成签名字符串所使用的签名算法类型，目前支持RSA2和RSA，推荐使用RSA2 | RSA2 |
TIPS：ISV/开发者可以通过“第三方应用授权”得到商户授权令牌（app_auth_token）作为请求参数传入，实现代商户发起请求的能力；具体方法请参考
第三方应用授权。
第四步：接口调用
调用流程
- 调用certification.initialize接口进行认证初始化，并获取返回值biz_no。biz_no是本次认证的标识，在后面的认证接口和查询接口会用到。
- 跳转到certification.certify页面接口让用户完成认证，用户完成认证后会跳转回商户回调地址。这个接口支持多种方式接入，可以灵活使用。必须在这个接口的请求中传入return_url才能回跳到商户，return_url也支持多个协议，可以按照需要使用。接入方式和回调协议案例参考下面的demo。
- 可以根据第一步返回的biz_no查询本次认证的状态和结果。
芝麻认证商户接入蚂蚁开放平台流程
使用SDK快速接入
1. 认证初始化接口zhima.customer.certification.initialize：
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
ZhimaCustomerCertificationInitializeRequest request = new ZhimaCustomerCertificationInitializeRequest();
String bizContent = "{"
+ " \"transaction_id\":\"ZGYD201610252323000001234\","
+ " \"product_code\":\"w1010100000000002978\","
+ " \"biz_code\":\"FACE\","
+ " \"identity_param\":\"{\\\"identity_type\\\":\\\"CERT_INFO\\\",\\\"cert_type\\\":\\\"IDENTITY_CARD\\\",\\\"principal_id\\\":\\\"2394276742\\\",\\\"cert_name\\\":\\\"收委\\\",\\\"cert_no\\\":\\\"260104197909275964\\\"}\","
+ " \"ext_biz_param\":\"{}\"" + " }";
request.setBizContent(bizContent);
ZhimaCustomerCertificationInitializeResponse response = alipayClient.execute(request);
if (response.isSuccess()) {
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}
2. 开始认证接口zhima.customer.certification.certify：
a. 生成认证请求URL,必要要传回调地址return_url，回调支持在支付宝APP打开(示例:alipays://www.taobao.com)、在浏览器打开（示例:https://www.taobao.com）、在商户app打开(使用商户schema协议)。
// 获取alipay client
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
ZhimaCustomerCertificationCertifyRequest request = new ZhimaCustomerCertificationCertifyRequest();
// 设置业务参数,必须要biz_no
request.setBizContent("{\"biz_no\":\"ZM201611103000000888800000733621\"}");
// 设置回调地址,必填. 如果需要直接在支付宝APP里面打开回调地址使用alipay协议
// alipay://www.taobao.com 或者 alipays://www.taobao.com,分别对应http和https请求
// 设置业务参数,必须要biz_no
request.setReturnUrl("alipays://www.taobao.com");
// 这里一定要使用GET模式
ZhimaCustomerCertificationCertifyResponse response = alipayClient.pageExecute(request, "GET");
// 从body中获取URL
String url = response.getBody();
System.out.println("generateCertifyUrl url:" + url);
b. 生成如下的认证URL（生成的URL必须包含回调地址）：
https://openapi.alipay.com/gateway.do?alipay_sdk=alipay-sdk-java-dynamicVersionNo&app_id=2015111100758155&biz_content=%7B%22biz_no%22%3A%22ZM201611253000000121200404215172%22%7D&charset=GBK&format=json&method=zhima.customer.certification.certify&return_url=http%3A%2F%2Fwww.taobao.com&sign=MhtfosO8AKbwctDgfGitzLvhbcvi%2FMv3iBES7fRnIXn%2BHcdwq9UWltTs6mEvjk2UoHdLoFrvcSJipiE3sL8kdJMd51t87vcwPCfk7BA5KPwa4%2B1IYzYaK6WwbqOoQB%2FqiJVfni602HiE%2BZAomW7WA3Tjhjy3D%2B9xrLFCipiroDQ%3D&sign_type=RSA2×tamp=2016-11-25+15%3A00%3A59&version=1.0&sign=MhtfosO8AKbwctDgfGitzLvhbcvi%2FMv3iBES7fRnIXn%2BHcdwq9UWltTs6mEvjk2UoHdLoFrvcSJipiE3sL8kdJMd51t87vcwPCfk7BA5KPwa4%2B1IYzYaK6WwbqOoQB%2FqiJVfni602HiE%2BZAomW7WA3Tjhjy3D%2B9xrLFCipiroDQ%3D
c. 开始认证方式1：商户有自己的APP，使用native的方式唤起支付宝客户端（可选）。
在商户APP使用如下示例代码（传入认证URL）使用native代码唤起支付宝客户端进行认证。
Android版本
/**
* 启动支付宝进行认证
* @param url 开放平台返回的URL
*/
private void doVerify(String url) {
if (hasApplication()) {
Intent action = new Intent(Intent.ACTION_VIEW);
StringBuilder builder = new StringBuilder();
builder.append("alipays://platformapi/startapp?appId=20000067&url=");
builder.append(URLEncoder.encode(url));
action.setData(Uri.parse(builder.toString()));
startActivity(action);
} else {
//处理没有安装支付宝的情况
new AlertDialog.Builder(this)
.setMessage("是否下载并安装支付宝完成认证?")
.setPositiveButton("好的", new DialogInterface.OnClickListener() {
@Override
public void onClick(DialogInterface dialog, int which) {
Intent action = new Intent(Intent.ACTION_VIEW);
action.setData(Uri.parse("https://m.alipay.com"));
startActivity(action);
}
}).setNegativeButton("算了", new DialogInterface.OnClickListener() {
@Override
public void onClick(DialogInterface dialog, int which) {
dialog.dismiss();
}
}).show();
}
}
/**
* 判断是否安装了支付宝
* @return true 为已经安装
*/
private boolean hasApplication() {
PackageManager manager = getPackageManager();
Intent action = new Intent(Intent.ACTION_VIEW);
action.setData(Uri.parse("alipays://"));
List<ResolveInfo> list = manager.queryIntentActivities(action, PackageManager.GET_RESOLVED_FILTER);
return list != null && list.size() > 0;
}
IOS版本
- (void)doVerify:(NSString *)url {
NNSString *alipayUrl = [NSString stringWithFormat:@"alipays://platformapi/startapp?appId=20000067&url=%@", [self URLEncodedStringWithUrl:url]];
if ([self canOpenAlipay]) {
[[UIApplication sharedApplication] openURL:[NSURL URLWithString:alipayUrl] options:@{} completionHandler:nil];
} else {
UIAlertView *alertView = [[UIAlertView alloc] initWithTitle:@"" message:@"是否下载并安装支付宝完成认证?" delegate:self cancelButtonTitle:@"取消" otherButtonTitles:@"好的", nil];
[alertView show];
}
}
-(NSString *)URLEncodedStringWithUrl:(NSString *)url {
NSString *encodedString = (NSString *)CFBridgingRelease(CFURLCreateStringByAddingPercentEscapes(NULL,(CFStringRef)url,NULL,(CFStringRef) @"!*'();:@&=+$,%#[]|",kCFStringEncodingUTF8));
return encodedString;
}
- (void)alertView:(UIAlertView *)alertView clickedButtonAtIndex:(NSInteger)buttonIndex {
if (buttonIndex == 1) {
NSString *appstoreUrl = @"itms-apps://itunes.apple.com/app/id333206289";
[[UIApplication sharedApplication] openURL:[NSURL URLWithString:appstoreUrl] options:@{} completionHandler:nil];
}
}
- (BOOL)canOpenAlipay {
return [[UIApplication sharedApplication] canOpenURL:[NSURL URLWithString:@"alipays://"]];
}
// 并且在Info.plist文件中配置alipays到LSApplicationQueriesSchemes参数中
d. 开始认证方式2：商户没有自己的APP，使用H5页面的方式唤起支付宝客户端（可选）。
在商户的H5页面跳转到认证URL，进入芝麻认证引导页，芝麻认证引导页会唤起支付宝客户端。
e. 开始认证方式3：根据认证URL生成二维码，让用户打开支付宝客户端扫码（可选）。
商户根据认证URL生成二维码，然后提供二维码让用户使用支付宝客户端扫码进入认证引导页。
3. 芝麻认证查询接口zhima.customer.certification.query：
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
ZhimaCustomerCertificationQueryRequest request = new ZhimaCustomerCertificationQueryRequest();
request.setBizContent("{\"biz_no\":\"ZM201611103000000888800000733621\"}");
ZhimaCustomerCertificationQueryResponse response = alipayClient.execute(request);
if (response.isSuccess()) {
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}
关于沙箱
如何接入沙箱
沙箱环境是开放平台提供给开发者调试接口的环境，具体操作步骤见 沙箱接入指南。
芝麻认证沙箱接入注意点
1、 芝麻认证支持沙箱接入；在沙箱调通接口后，必须在线上进行测试与验收，所有返回码及业务逻辑以线上为准；
2、 芝麻认证中初始化接口请使用沙箱账号进行测试：点击管理中心-沙箱环境-沙箱账号。
3、 芝麻认证中开始认证接口请使用沙箱版钱包测试：点击管理中心-沙箱环境-沙箱工具。
4、沙箱调用芝麻认证开始认证接口只能看认证的流程，并不能在沙箱中进行认证。如果需要认证需要使用正式环境测试。
