本文档展示了如何从零开始，使用蚂蚁金服开放平台服务端SDK快速接入当面付产品，完成与支付宝对接的部分。

注意：文档中的代码示例和Demo是用来阐述API基本使用方法的，仅针对大众场景。供ISV参考，特殊情况还请ISV自行扩展，确保符合自身业务需求。

第一步：创建应用并获取APPID

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

第二步：配置密钥

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

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

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

2.接口调用配置
在SDK调用前需要进行初始化，以JAVA代码为例：

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

关键参数说明：

接下来，就可以用alipayClient来调用具体的API了。alipayClient只需要初始化一次，后续调用不同的API都可以使用同一个alipayClient对象。

条码支付

场景介绍

条码支付是支付宝给到线下传统行业的一种收款方式。商户使用扫码枪等条码识别设备扫描用户支付宝钱包上的条码/二维码，完成收款。用户仅需出示付款码，所有操作由商户端完成。

调用流程

接口调用时序图：

1. 商户系统将用户付款码与订单信息一起通过交易支付接口alipay.trade.pay请求到支付宝，并从接口同步返回中获取支付结果。
2. 根据公共返回参数中的code，这笔交易可能有四种状态：支付成功（10000），支付失败（40004），等待用户付款（10003）和未知异常（20000）。

使用SDK快速接入

交易支付接口alipay.trade.pay：

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2"); //获得初始化的AlipayClient
AlipayTradePayRequest request = new AlipayTradePayRequest(); //创建API对应的request类
request.setBizContent("{" +
"    \"out_trade_no\":\"20150320010101001\"," +
"    \"scene\":\"bar_code\"," +
"    \"auth_code\":\"28763443825664394\"," +
"    \"subject\":\"Iphone6 16G\"," +
"    \"store_id\":\"NJ_001\"," +
"    \"timeout_express\":\"2m\"," +
"    \"total_amount\":\"88.88\"" +
"  }"); //设置业务参数
AlipayTradePayResponse response = alipayClient.execute(request); //通过alipayClient调用API，获得对应的response类
System.out.print(response.getBody());
// 根据response中的结果继续业务逻辑处理

关键入参：

关键出参：

交易查询接口alipay.trade.query：

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2"); //获得初始化的AlipayClient
AlipayTradeQueryRequest request = new AlipayTradeQueryRequest();//创建API对应的request类
request.setBizContent("{" +
"    \"out_trade_no\":\"20150320010101001\"," +
"    \"trade_no\":\"2014112611001004680073956707\"}"); //设置业务参数
AlipayTradeQueryResponse response = alipayClient.execute(request);//通过alipayClient调用API，获得对应的response类
System.out.print(response.getBody());
//根据response中的结果继续业务逻辑处理

关键入参：

关键出参：

交易撤销接口alipay.trade.cancel：

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2"); //获得初始化的AlipayClient
AlipayTradeCancelRequest request = new AlipayTradeCancelRequest();//创建API对应的request类
request.setBizContent("{" +
"    \"out_trade_no\":\"20150320010101001\"," +
"    \"trade_no\":\"2014112611001004680073956707\"}"); //设置业务参数
AlipayTradeCancelResponse response = alipayClient.execute(request);//通过alipayClient调用API，获得对应的response类
System.out.print(response.getBody());
//根据response中的结果继续业务逻辑处理

关键入参：

关键出参：

扫码支付

场景介绍

扫码支付，指用户打开支付宝钱包中的“扫一扫”功能，扫描商户针对每个订单实时生成的订单二维码，并在手机端确认支付。

调用流程

1. 商户系统调用支付宝预下单接口alipay.trade.precreate，获得该订单二维码图片地址。
2. 发起轮询获得支付结果：等待5秒后调用交易查询接口alipay.trade.query通过支付时传入的商户订单号(out_trade_no)查询支付结果（返回参数TRADE_STATUS），如果仍然返回等待用户付款（WAIT_BUYER_PAY），则再次等待5秒后继续查询，直到返回确切的支付结果（成功TRADE_SUCCESS 或 已撤销关闭TRADE_CLOSED），或是超出轮询时间。在最后一次查询仍然返回等待用户付款的情况下，必须立即调用交易撤销接口alipay.trade.cancel将这笔交易撤销，避免用户继续支付。
3. 除了主动轮询，也可以通过接受异步通知获得支付结果，详见扫码异步通知，注意一定要对异步通知做验签，确保通知是支付宝发出的。

使用SDK快速接入

预下单接口alipay.trade.precreate：

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2"); //获得初始化的AlipayClient
AlipayTradePrecreateRequest request = new AlipayTradePrecreateRequest();//创建API对应的request类
request.setBizContent("{" +
"    \"out_trade_no\":\"20150320010101002\"," +
"    \"total_amount\":\"88.88\"," +
"    \"subject\":\"Iphone6 16G\"," +
"    \"store_id\":\"NJ_001\"," +
"    \"timeout_express\":\"90m\"}");//设置业务参数
AlipayTradePrecreateResponse response = alipayClient.execute(request);
System.out.print(response.getBody());
//根据response中的结果继续业务逻辑处理

关键入参：

关键出参：

查询、撤销接口参见条码支付中的示例。

退款

场景介绍

商户因业务原因需要退款时，可通过成功交易的商户订单号或支付宝交易号进行退款 ，支持部分退款。

调用流程

商户系统调用交易退款接口alipay.trade.refund，传入商户订单号或支付宝交易号、退款请求号、退款金额等参数请求退款，并同步获得退款结果。

特别注意

使用SDK快速接入

交易退款接口alipay.trade.refund：

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2"); //获得初始化的AlipayClient
AlipayTradeRefundRequest request = new AlipayTradeRefundRequest();//创建API对应的request类
request.setBizContent("{" +
"    \"out_trade_no\":\"20150320010101001\"," +
"    \"trade_no\":\"2014112611001004680073956707\"," +
"    \"out_request_no\":\"1000001\"," +
"    \"refund_amount\":\"1.00\"}"); //设置业务参数
AlipayTradeRefundResponse response = alipayClient.execute(request);//通过alipayClient调用API，获得对应的response类
System.out.print(response.getBody());
//根据response中的结果继续业务逻辑处理

关键入参：

关键出参：

对账

场景介绍

商户/系统商可通过接口下载指定日期（当天除外）的业务明细账单文件，并结合自身业务系统实现自动对账。

调用流程

1. 商户系统调用查询对账单下载地址接口alipay.data.dataservice.bill.downloadurl.query，传入指定日期，获得该日期账单文件的下载地址。
2. 商户系统通过HTTP方式后台访问账单下载链接，将账单csv文件下载到本地后自行处理。注意该下载链接仅30秒，在得到链接后系统需要立刻请求下载账单文件。

使用SDK快速接入

查询对账单下载地址接口alipay.data.dataservice.bill.downloadurl.query：

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");//获得初始化的AlipayClient
AlipayDataDataserviceBillDownloadurlQueryRequest request = new AlipayDataDataserviceBillDownloadurlQueryRequest();//创建API对应的request类
request.setBizContent("{" +
"    \"bill_type\":\"trade\"," +
"    \"bill_date\":\"2016-04-05\"}"); //设置业务参数
AlipayDataDataserviceBillDownloadurlQueryResponse response = alipayClient.execute(request);//通过alipayClient调用API，获得对应的response类
System.out.print(response.getBody());
//根据response中的结果继续业务逻辑处理

关键入参：

关键出参：

下载账单文件：

//将接口返回的对账单下载地址传入urlStr
String urlStr = "http://dwbillcenter.alipay.com/downloadBillFile.resource?bizType=X&userId=X&fileType=X&bizDates=X&downloadFileName=X&fileId=X";
//指定希望保存的文件路径
String filePath = "/Users/fund_bill_20160405.csv.zip";
URL url = null;
HttpURLConnection httpUrlConnection = null;
InputStream fis = null;
FileOutputStream fos = null;
try {
    url = new URL(urlStr);
    httpUrlConnection = (HttpURLConnection) url.openConnection();
    httpUrlConnection.setConnectTimeout(5 * 1000);
    httpUrlConnection.setDoInput(true);
    httpUrlConnection.setDoOutput(true);
    httpUrlConnection.setUseCaches(false);
    httpUrlConnection.setRequestMethod("GET");
    httpUrlConnection.setRequestProperty("CHARSET", "UTF-8");
    httpUrlConnection.connect();
    fis = httpUrlConnection.getInputStream();
    byte[] temp = new byte[1024];
    int b;
    fos = new FileOutputStream(new File(filePath));
    while ((b = fis.read(temp)) != -1) {
        fos.write(temp, 0, b);
        fos.flush();
    }
} catch (MalformedURLException e) {
    e.printStackTrace();
} catch (IOException e) {
    e.printStackTrace();
} finally {
    try {
        if(fis!=null) fis.close();
        if(fos!=null) fos.close();
        if(httpUrlConnection!=null) httpUrlConnection.disconnect();
    } catch (IOException e) {
        e.printStackTrace();
    }
}

接口调用结果码说明

在线验收

在线验收是面向商户提供的一种验证检查的能力，可以帮助商户在接入支付宝产品后，迅速验证接入的规范情况。它也可以帮助商户在活动上线前，迅速验证优惠活动的正确性。具体操作步骤请参见当面付开发线上验收。

关于沙箱

如何接入沙箱

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

当面付沙箱接入注意点

1、当面付支持沙箱接入，详见接入指引；在沙箱调通接口后，必须在线上进行测试与验收，所有返回码及业务逻辑以线上为准；
2、当面付只支持余额支付，不支持银行卡、余额宝等其他支付方式；
3、当面付不支持优惠核销；
4、扫码支付中的扫码以及条码支付中的付款码请使用沙箱版钱包测试：点击开发者中心-沙箱环境-沙箱工具
5、查询对账单下载地址，仅测试该接口在沙箱环境中是否可以成功下载对账单，下载的CSV对账单仅为账单模板(数据为空)，实际数据请使用生产环境；

FAQ