快速接入

本文展示了如何从零开始,使用支付宝开放平台服务端 SDK 快速接入电脑网站支付产品,完成与支付宝对接的部分。

由于支付产品全面升级,若您使用的是旧版本接口,请移步即时到账文档。若您希望从即时到账(使用旧版本接口)升级为电脑网站支付(使用新版本接口),请参考以下步骤完成即时到账新版本(即电脑网站支付)的接入工作。若想了解更多关于新版本的升级改造内容,可参考即时到账新老版本接口对比


注意

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


第一步:创建应用


要在您的应用中接入电脑网站支付能力,您需要登录支付宝开放平台(open.alipay.com),在开发者中心中创建您的应用,应用审核通过后会生成应用唯一标识(APPID),并且可以申请开通开放产品使用权限。通过 APPID 您的应用才能调用开放产品的接口能力。需要详细了解开放平台创建应用步骤请参考《开放平台应用创建指南》


第二步:配置应用

添加功能并签约


应用创建完成后,系统会自动跳转到应用详情页面。开发者可以在 功能列表 中点击 添加功能 来添加电脑网站支付功能。待应用上线后,您可以给添加的功能进行签约。电脑网站支付功能支持两种签约方式:商家中心签约和应用详情的功能列表处签约(如下图所示)。

详细步骤步骤可以参考添加应用功能,第三方应用可以代替商户签约。


配置密钥


为了保证交易双方(商户和支付宝)的身份和数据安全,开发者在调用接口前,需要配置双方密钥,对交易数据进行双方校验。密钥包含应用私钥(APP_PRIVATE_KEY)和应用公钥(APP_PUBLIC_KEY)。生成密钥后,开发者需要在开放平台开发者中心进行密钥配置,配置完成后可以获取支付宝公钥(ALIPAY_PUBLIC_KEY),配置的详细步骤请参考《配置应用环境》。您还可以通过观看快速签名教程学习密钥的配置。


说明

支付宝开放平台 SDK 封装了签名和验签过程,只需配置账号及密钥参数,建议开发者使用。开发者还可以通过自助排查流程验签教程自助排查配置应用过程中遇到的问题。


第三步:集成并配置 SDK


要接入电脑网站支付,开发者需要集成服务端 SDK。服务端 SDK 需要商户集成在自己的服务端系统中,用于后续的服务端接口调用。


下载服务端 SDK


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


接口调用配置


在 SDK 调用前需要进行初始化,以 JAVA 代码为例

1AlipayClient 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 即创建应用后生成

获取见上方创建应用

APP_PRIVATE_KEY

开发者私钥,由开发者自己生成

获取见配置密钥

FORMAT

参数返回格式,只支持 json

json(固定)

CHARSET

编码集,支持 GBK/UTF-8

开发者根据实际工程编码配置

ALIPAY_PUBLIC_KEY

支付宝公钥,由支付宝生成

获取详见配置密钥

SIGN_TYPE

商户生成签名字符串所使用的签名算法类型,目前支持 RSA2 和 RSA,推荐使用 RSA2

RSA2

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


注意:

ISV /开发者可以通过第三方应用授权得到商户授权令牌(app_auth_token)作为请求参数传入,实现代商户发起请求的能力。


第四步:接口调用

支付


电脑网站支付的支付接口 alipay.trade.page.pay 调用时序图如下:

电脑网站支付.png


调用顺序如下: 

  1. 商户系统请求支付宝接口 alipay.trade.page.pay,支付宝对商户请求参数进行校验,而后重新定向至用户登录页面。
  2. 用户确认支付后,支付宝通过 get 请求 returnUrl(商户入参传入),返回同步返回参数。
  3. 交易成功后,支付宝通过 post 请求 notifyUrl(商户入参传入),返回异步通知参数。
  4. 若由于网络等问题异步通知没有到达,商户可自行调用交易查询接口 alipay.trade.query 进行查询,根据查询接口获取交易以及支付信息(商户也可以直接调用查询接口,不需要依赖异步通知)。


注意 

  • 由于同步返回的不可靠性,支付结果必须以异步通知或查询接口返回为准,不能依赖同步跳转。
  • 商户系统接收到异步通知以后,必须通过验签(验证通知中的 sign 参数)来确保支付通知是由支付宝发送的。详细验签规则参考异步通知验签
  • 接收到异步通知并验签通过后,一定要检查通知内容,包括通知中的 app_id、out_trade_no、total_amount 是否与请求中的一致,并根据 trade_status 进行后续业务处理。
  • 在支付宝端,partnerId 与 out_trade_no 唯一对应一笔单据,商户端保证不同次支付 out_trade_no 不可重复;若重复,支付宝会关联到原单据,基本信息一致的情况下会以原单据为准进行支付。


开放平台提供了支持主流开发语言的 SDK 接入的方式。对于页面跳转类 API,SDK 不会也无法像系统调用类 API 一样自动请求支付宝并获得结果,而是在接受 request 请求对象后,为开发者生成前台页面请求需要的完整 form 表单的 html(包含自动提交脚本),商户直接将这个表单的 String 输出到 http response 中即可。


以 JAVA 语言为例,调用统一收单下单并支付页面接口 alipay.trade.page.pay 的代码示例如下:


 1public void doPost(HttpServletRequest httpRequest,
 2                      HttpServletResponse httpResponse) throws ServletException, IOException {
 3    AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, FORMAT, CHARSET, ALIPAY_PUBLIC_KEY, SIGN_TYPE); //获得初始化的AlipayClient
 4    AlipayTradePagePayRequest alipayRequest = new AlipayTradePagePayRequest();//创建API对应的request
 5    alipayRequest.setReturnUrl("http://domain.com/CallBack/return_url.jsp");
 6    alipayRequest.setNotifyUrl("http://domain.com/CallBack/notify_url.jsp");//在公共参数中设置回跳和通知地址
 7    alipayRequest.setBizContent("{" +
 8        "    \"out_trade_no\":\"20150320010101001\"," +
 9        "    \"product_code\":\"FAST_INSTANT_TRADE_PAY\"," +
10        "    \"total_amount\":88.88," +
11        "    \"subject\":\"Iphone6 16G\"," +
12        "    \"body\":\"Iphone6 16G\"," +
13        "    \"passback_params\":\"merchantBizType%3d3C%26merchantBizNo%3d2016010101111\"," +
14        "    \"extend_params\":{" +
15        "    \"sys_service_provider_id\":\"2088511833207846\"" +
16        "    }"+
17        "  }");//填充业务参数
18    String form="";
19    try {
20        form = alipayClient.pageExecute(alipayRequest).getBody(); //调用SDK生成表单
21    } catch (AlipayApiException e) {
22        e.printStackTrace();
23    }
24    httpResponse.setContentType("text/html;charset=" + CHARSET);
25    httpResponse.getWriter().write(form);//直接将完整的表单html输出到页面
26    httpResponse.getWriter().flush();
27    httpResponse.getWriter().close();
28}



对异步返回结果进行验签的 JAVA 示例代码如下:


1Map<String, String> paramsMap = ... //将异步通知中收到的所有参数都存放到 map 中
2boolean signVerified = AlipaySignature.rsaCheckV1(paramsMap, ALIPAY_PUBLIC_KEY, CHARSET, SIGN_TYPE) //调用SDK验证签名
3if(signVerfied){
4    // TODO 验签成功后,按照支付结果异步通知中的描述,对支付结果中的业务内容进行二次校验,校验成功后在response中返回success并继续商户自身业务处理,校验失败返回failure
5}else{
6    // TODO 验签失败则记录异常日志,并在response中返回failure.
7}



以 JAVA 语言为例,调用统一收单线下交易查询接口 alipay.trade.query 的示例代码如下:


 1AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
 2AlipayTradeQueryRequest request = new AlipayTradeQueryRequest();
 3request.setBizContent("{" +
 4"    \"out_trade_no\":\"20150320010101001\"," +
 5"    \"trade_no\":\"2014112611001004680 073956707\"" +
 6"  }");
 7AlipayTradeQueryResponse response = alipayClient.execute(request);
 8if(response.isSuccess()){
 9System.out.println("调用成功");
10} else {
11System.out.println("调用失败");
12}


退款


若用户或商户需要退款,商户可调用 alipay.trade.refund 接口进行退款,支付宝同步返回退款参数。电脑网站支付的退款接口 alipay.trade.refund 调用时序图如下:

image.png


若退款接口由于网络等原因返回异常,商户可调用退款查询接口 alipay.trade.fastpay.refund.query 查询指定交易的退款信息。


注意

  • 当交易发生之后一段时间内,由于买家或者卖家的原因需要退款时,卖家可以通过退款接口将支付款退还给买家,支付宝将在收到退款请求并且验证成功之后,按照退款规则将支付款按原路退回到买家账号上。
  • 交易超过约定时间(签约时设置的可退款时间)的订单无法进行退款。
  • 支付宝退款支持单笔交易分多次退款,多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。
  • 一笔退款失败后重新提交,要采用原来的退款单号。
  • 总退款金额不能超过用户实际支付金额。
  • 退款信息以退款接口同步返回或者退款查询接口 alipay.trade.fastpay.refund.query 为准。


开放平台提供了支持主流开发语言的 SDK 接入的方式,以 JAVA 语言为例,调用统一收单交易退款接口 alipay.trade.refund 的代码示例如下:


 1AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key");
 2AlipayTradeRefundRequest request = new AlipayTradeRefundRequest();
 3request.setBizContent("{" +
 4"    \"out_trade_no\":\"20150320010101001\"," +
 5"    \"trade_no\":\"2014112611001004680073956707\"," +
 6"    \"refund_amount\":200.12," +
 7"    \"refund_reason\":\"正常退款\"," +
 8"    \"out_request_no\":\"HZ01RF001\"," +
 9"    \"operator_id\":\"OP001\"," +
10"    \"store_id\":\"NJ_S_001\"," +
11"    \"terminal_id\":\"NJ_T_001\"" +
12"  }");
13AlipayTradeRefundResponse response = alipayClient.execute(request);
14if(response.isSuccess()){
15System.out.println("调用成功");
16} else {
17System.out.println("调用失败");
18}



调用统一收单交易退款查询接口 alipay.trade.fastpay.refund.query 的 JAVA 示例代码如下:


 1AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key");
 2AlipayTradeFastpayRefundQueryRequest request = new AlipayTradeFastpayRefundQueryRequest();
 3request.setBizContent("{" +
 4"    \"trade_no\":\"20150320010101001\"," +
 5"    \"out_trade_no\":\"2014112611001004680073956707\"," +
 6"    \"out_request_no\":\"2014112611001004680073956707\"" +
 7"  }");
 8AlipayTradeFastpayRefundQueryResponse response = alipayClient.execute(request);
 9if(response.isSuccess()){
10System.out.println("调用成功");
11} else {
12System.out.println("调用失败");
13}


关闭交易


通常交易关闭是通过 alipay.trade.page.pay 中的超时时间来控制,支付宝也提供给商户一个手动关闭交易的接口alipay.trade.close。若用户一直未支付,商户可以调用该接口关闭指定交易;成功关闭交易后该交易不可支付。交易关闭接口的调用时序图 alipay.trade.close 如下图所示:



开放平台提供了支持主流开发语言的 SDK 接入的方式,以 JAVA 语言为例,调用统一收单交易关闭接口 alipay.trade.close 的代码示例如下:

 1AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
 2AlipayTradeCloseRequest request = new AlipayTradeCloseRequest();
 3request.setBizContent("{" +
 4"    \"trade_no\":\"2013112611001004680073956707\"," +
 5"    \"out_trade_no\":\"HZ0120131127001\"," +
 6"    \"operator_id\":\"YX01\"" +
 7"  }");
 8AlipayTradeCloseResponse response = alipayClient.execute(request);
 9if(response.isSuccess()){
10System.out.println("调用成功");
11} else {
12System.out.println("调用失败");
13}


下载账单


为方便商户快速查账,开放平台支持商户通过查询对账单下载地址接口 alipay.data.dataservice.bill.downloadurl.query 获取商户离线账单下载地址。调用该接口的时序图如下:


开放平台提供了支持主流开发语言的 SDK 接入的方式,以 JAVA 语言为例,调用查询对账单下载地址接口 alipay.data.dataservice.bill.downloadurl.query 的代码示例如下:

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


开发者在得到接口返回的账单下载地址(bill_download_url)后还可以下载账单文件,JAVA 示例代码如下:

 1//将接口返回的对账单下载地址传入urlStr
 2String urlStr = "http://dwbillcenter.alipay.com/downloadBillFile.resource?bizType=X&userId=X&fileType=X&bizDates=X&downloadFileName=X&fileId=X";
 3//指定希望保存的文件路径
 4String filePath = "/Users/fund_bill_20160405.csv";
 5URL url = null;
 6HttpURLConnection httpUrlConnection = null;
 7InputStream fis = null;
 8FileOutputStream fos = null;
 9try {
10    url = new URL(urlStr);
11    httpUrlConnection = (HttpURLConnection) url.openConnection();
12    httpUrlConnection.setConnectTimeout(5 * 1000);
13    httpUrlConnection.setDoInput(true);
14    httpUrlConnection.setDoOutput(true);
15    httpUrlConnection.setUseCaches(false);
16    httpUrlConnection.setRequestMethod("GET");
17    httpUrlConnection.setRequestProperty("Charsert", "UTF-8");
18    httpUrlConnection.connect();
19    fis = httpUrlConnection.getInputStream();
20    byte[] temp = new byte[1024];
21    int b;
22    fos = new FileOutputStream(new File(filePath));
23    while ((b = fis.read(temp)) != -1) {
24        fos.write(temp, 0, b);
25        fos.flush();
26    }
27} catch (MalformedURLException e) {
28    e.printStackTrace();
29} catch (IOException e) {
30    e.printStackTrace();
31} finally {
32    try {
33        if(fis!=null) fis.close();
34        if(fos!=null) fos.close();
35        if(httpUrlConnection!=null) httpUrlConnection.disconnect();
36    } catch (IOException e) {
37        e.printStackTrace();
38    }
39}


关于沙箱


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

沙箱接入注意事项:

  • 电脑网站支付支持沙箱接入;在沙箱调通接口后,必须在线上进行测试与验收,所有返回码及业务逻辑以线上为准;
  • 电脑网站支付只支持余额支付,不支持银行卡、余额宝等其他支付方式;
  • 支付时,请使用沙箱买家账号支付;
  • 如果扫二维码付款时,请使用沙箱支付宝客户端扫码付款。
onlineServer