文档中心 > 开放平台

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

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

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

第二步:配置密钥

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

条码支付

场景介绍

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

调用流程

接口调用时序图:
时序图

  1. 商户系统将用户付款码与订单信息一起通过交易支付接口alipay.trade.pay请求到支付宝,并从接口同步返回中获取支付结果。
  2. 根据公共返回参数中的code,这笔交易可能有四种状态:支付成功(10000),支付失败(40004),等待用户付款(10003)和未知异常(20000)。
结果码 说明 处理方式
10000 支付成功 记录交易结果并在客户端显示支付成功,进入后续的业务处理。
40004 支付失败 记录交易结果并在客户端显示错误信息(display_message)。
10003 等待用户付款 发起轮询流程:等待5秒后调用交易查询接口alipay.trade.query通过支付时传入的商户订单号(out_trade_no)查询支付结果(返回参数TRADE_STATUS),如果仍然返回等待用户付款(WAIT_BUYER_PAY),则再次等待5秒后继续查询,直到返回确切的支付结果(成功TRADE_SUCCESS 或 已撤销关闭TRADE_CLOSED),或是超出轮询时间。在最后一次查询仍然返回等待用户付款的情况下,必须立即调用交易撤销接口alipay.trade.cancel将这笔交易撤销,避免用户继续支付。
20000 未知异常 调用查询接口确认支付结果,详见异常处理
特别注意:商户订单号out_trade_no在任何情况下不可重复,即时对于失败或撤销的交易,商户订单号也可能已经被使用了,如需再次发起支付,必须使用新的商户订单号调用接口,否则会报错。

使用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中的结果继续业务逻辑处理

关键入参:

参数名称 参数说明
out_trade_no 商户订单号,需要保证不重复
scene 条码支付固定传入bar_code
auth_code 用户付款码
subject 订单标题
store_id 商户门店编号
total_amount 订单金额
timeout_express 交易超时时间

关键出参:

参数名称 参数说明
trade_no 支付宝28位交易号

交易查询接口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中的结果继续业务逻辑处理

关键入参:

参数名称 参数说明
out_trade_no 支付时传入的商户订单号,与trade_no必填一个
trade_no 支付时返回的支付宝交易号,与out_trade_no必填一个

关键出参:

参数名称 参数说明
trade_no 支付宝28位交易号
out_trade_no 支付时传入的商户订单号
trade_status 交易当前状态

交易撤销接口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中的结果继续业务逻辑处理

关键入参:

参数名称 参数说明
out_trade_no 支付时传入的商户订单号,与trade_no必填一个
trade_no 支付时返回的支付宝交易号,与out_trade_no必填一个

关键出参:

参数名称 参数说明
retry_flag 是否需要重试,Y/N
action 本次撤销触发的交易动作 close:关闭交易,无退款 refund:产生了退款

扫码支付

场景介绍

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

调用流程

时序图

  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中的结果继续业务逻辑处理

关键入参:

参数名称 参数说明
out_trade_no 商户订单号,需要保证不重复
total_amount 订单金额
subject 订单标题
store_id 商户门店编号
timeout_express 交易超时时间

关键出参:

参数名称 参数说明
qr_code 订单二维码图片地址

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

退款

场景介绍

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

调用流程

image

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

特别注意

退款接口会根据外部请求号out_request_no幂等返回,因此同一笔需要多次部分退款时,必须使用不同的out_request_no。

使用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中的结果继续业务逻辑处理

关键入参:

参数名称 参数说明
out_trade_no 支付时传入的商户订单号,与trade_no必填一个
trade_no 支付时返回的支付宝交易号,与out_trade_no必填一个
out_request_no 本次退款请求流水号,部分退款时必传
refund_amount 本次退款金额

关键出参:

参数名称 参数说明
refund_fee 该笔交易已退款的总金额

对账

场景介绍

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

调用流程

image

  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中的结果继续业务逻辑处理

关键入参:

参数名称 参数说明
bill_type 固定传入trade
bill_date 需要下载的账单日期,最晚是当期日期的前一天

关键出参:

参数名称 参数说明
bill_download_url 账单文件下载地址,30秒有效

下载账单文件:

//将接口返回的对账单下载地址传入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";
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("Charsert", "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();
    }
}

接口调用结果码说明

同步返回结果码 含义 说明
10000 接口调用成功,调用结果请参考具体的API文档所对应的业务返回参数
40001~40006 业务处理失败 具体失败原因请参考“公共错误码”。其它请参考API文档。
20000 业务出现未知错误或者系统异常 业务出现未知错误或者系统异常

关于沙箱

如何接入沙箱

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

当面付沙箱接入注意点

1、当面付支持沙箱接入;在沙箱调通接口后,必须在线上进行测试与验收,所有返回码及业务逻辑以线上为准;
2、当面付只支持余额支付,不支持银行卡、余额宝等其他支付方式;
3、当面付不支持优惠核销;
4、扫码支付中的扫码以及条码支付中的付款码请使用沙箱版钱包测试:点击管理中心-沙箱环境-沙箱工具
5、查询对账单下载地址 接口获取的账单为测试数据,仅供参考,实际账单请在线上调试;

FAQ

关于此文档暂时还没有FAQ
返回
顶部