电脑网站支付快速接入

电脑网站支付快速接入更新时间:2017-09-01

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

第一步:创建应用

要在您的应用中使用支付宝开放产品的接口能力:

  1. 您需要先去蚂蚁金服开放平台(open.alipay.com),在开发者中心创建登记您的应用,此时您将获得应用唯一标识(APPID);
  2. 请在【功能信息】中点击【添加功能】,选择【电脑网站支付】;
  3. 提交审核,等待审核通过,该应用正式可以使用。

需要详细了解开放平台创建应用步骤请参考《开放平台应用创建指南》。
TIPS:电脑网站支付接口需签约后才能调用,点此签约

第二步:配置密钥

开发者调用接口前需要先生成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 即创建应用后生成 获取见上面创建应用
APP_PRIVATE_KEY 开发者私钥,由开发者自己生成 获取详见上面配置密钥
FORMAT 参数返回格式,只支持json json(固定)
CHARSET 编码集,支持GBK/UTF-8 开发者根据实际工程编码配置
ALIPAY_PUBLIC_KEY 支付宝公钥,由支付宝生成 获取详见上面配置密钥
SIGN_TYPE 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 RSA2

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

第四步:接口调用

调用流程

image

image

image

支付接口(alipay.trade.page.pay):

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

**TIPS:
**由于同步返回的不可靠性,支付结果必须以异步通知或查询接口返回为准,不能依赖同步跳转。
商户系统接收到异步通知以后,必须通过验签(验证通知中的sign参数)来确保支付通知是由支付宝发送的。详细验签规则参考异步通知验签
接收到异步通知并验签通过后,一定要检查通知内容,包括通知中的app_id、out_trade_no、total_amount是否与请求中的一致,并根据trade_status进行后续业务处理。
退款接口(alipay.trade.refund):
若用户或商户需要退款,商户可调用alipay.trade.refund接口进行退款,支付宝同步返回退款参数。 
退款查询接口(alipay.trade.fastpay.refund.query):
若退款接口由于网络等原因返回异常,商户可调用alipay.trade.fastpay.refund.query退款查询接口查询指定交易的退款信息。
注意:退款信息一定以退款接口同步返回或者退款查询接口alipay.trade.fastpay.refund.query为准。
交易关闭接口(alipay.trade.close):
通常交易关闭是通过alipay.trade.page.pay中的超时时间来控制,支付宝也提供给商户一个手动关闭交易的接口alipay.trade.close。若用户一直未支付,商户可以调用该接口关闭指定交易。  成功关闭交易后该交易不可支付。
查询对账单下载地址查询接口:
为方便商户快速查账,支持商户通过alipay.data.dataservice.bill.downloadurl.query接口获取商户离线账单下载地址。

SDK接入

1. 统一收单下单并支付页面接口alipay.trade.page.pay:
对于页面跳转类API,SDK不会也无法像系统调用类API一样自动请求支付宝并获得结果,而是在接受request请求对象后,为开发者生成前台页面请求需要的完整form表单的html(包含自动提交脚本),商户直接将这个表单的String输出到http response中即可。

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

异步通知验签:

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

2. 统一收单交易退款接口alipay.trade.refund:

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key");
AlipayTradeRefundRequest request = new AlipayTradeRefundRequest();
request.setBizContent("{" +
"    \"out_trade_no\":\"20150320010101001\"," +
"    \"trade_no\":\"2014112611001004680073956707\"," +
"    \"refund_amount\":200.12," +
"    \"refund_reason\":\"正常退款\"," +
"    \"out_request_no\":\"HZ01RF001\"," +
"    \"operator_id\":\"OP001\"," +
"    \"store_id\":\"NJ_S_001\"," +
"    \"terminal_id\":\"NJ_T_001\"" +
"  }");
AlipayTradeRefundResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

3. 统一收单交易退款查询接口alipay.trade.fastpay.refund.query:

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

4. 统一收单线下交易查询接口alipay.trade.query:

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

5. 统一收单交易关闭接口alipay.trade.close:

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

6. 查询对账单下载地址接口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);
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";
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();
    }
}

注意事项

1. 统一收单下单并支付页面接口alipay.trade.page.pay:
在支付宝端,partnerId与out_trade_no唯一对应一笔单据,商户端保证不同次支付out_trade_no不可重复,若重复,支付宝会关联到原单据,基本信息一致的情况下会以原单据为准进行支付。
2. 统一收单交易退款接口alipay.trade.refund:

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

关于沙箱

沙箱环境是开放平台提供给开发者调试接口的环境,具体操作步骤见沙箱接入指南
电脑网站支付沙箱接入注意点:

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