支付接口说明
第一步:创建应用
要在您的应用中接入电脑网站支付能力,您需要登录支付宝开放平台(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 代码为例:
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 对象。
注意: ISV /开发者可以通过 第三方应用授权 得到商户授权令牌(app_auth_token)作为请求参数传入,实现代商户发起请求的能力。
第四步:接口调用
支付
电脑网站支付的支付接口 alipay.trade.page.pay 调用时序图如下:
调用顺序如下:
- 商户系统请求支付宝接口 alipay.trade.page.pay,支付宝对商户请求参数进行校验,而后重新定向至用户登录页面。
- 用户确认支付后,支付宝通过 get 请求 returnUrl(商户入参传入),返回同步返回参数。
- 交易成功后,支付宝通过 post 请求 notifyUrl(商户入参传入),返回异步通知参数。
- 若由于网络等问题异步通知没有到达,商户可自行调用交易查询接口 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 的代码示例如下:
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.putOtherTextParam("app_auth_token", "201611BB8xxxxxxxxxxxxxxxxxxxedcecde6");//如果 ISV 代商家接入电脑网站支付能力,则需要传入 app_auth_token,使用第三方应用授权;自研开发模式请忽略
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();
}
对异步返回结果进行验签的 JAVA 示例代码如下:
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.
}
以 JAVA 语言为例,调用统一收单线下交易查询接口 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( "调用失败" );
}