手机网站支付快速接入

本文档展示了如何从零开始，使用蚂蚁金服开放平台服务端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详细使用说明，请参考《服务端SDK使用说明》

在使用SDK调用具体API前，进行初始化，代码如下：

配置参数	示例值解释	获取方式/示例值
URL	支付宝网关（固定）	https://openapi.alipay.com/gateway.do
APP_ID	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对象。

TIPS：手机网站支付不支持第三方授权，不能代商家发起请求。

第四步：调用接口

手机网站支付产品包含两类API：

页面跳转类：需要从前端页面以Form表单的形式发起请求，浏览器会自动跳转至支付宝的相关页面（一般是收银台或签约页面），用户在该页面完成相关业务操作后再回跳到商户指定页面。例如本产品中的手机网站支付接口alipay.trade.wap.pay。

系统调用类：直接从服务端发起HTTP请求，支付宝会同步返回请求结果。例如本产品中的交易查询等配套API。

调用流程

如上图所示，用户在商户的H5网站下单支付后，商户系统按照手机网站支付接口alipay.trade.wap.payAPI的参数规范生成订单数据，然后在前端页面通过Form表单的形式请求到支付宝。此时支付宝会自动将页面跳转至支付宝H5收银台页面，如果用户手机上安装了支付宝APP，则自动唤起支付宝APP。开发者需要关注安装了支付宝和未安装支付宝的两种测试场景，对于在手机浏览器唤起H5页面的模式下，如果安装了支付宝却没有唤起，大部分原因是当前浏览器不在支付宝配置的白名单内，对于商户app内嵌webview中的支付场景，建议集成支付宝App支付产品。

用户在支付宝APP或H5收银台完成支付后，会根据商户在手机网站支付API中传入的前台回跳地址return_url自动跳转回商户页面，同时在URL请求中以Query String的形式附带上支付结果参数，详细回跳参数见“手机网站支付接口alipay.trade.wap.pay”前台回跳参数。

同时，支付宝还会根据原始支付API中传入的异步通知地址notify_url，通过POST请求的形式将支付结果作为参数通知到商户系统，详情见支付结果异步通知。

除了正向支付流程外，支付宝也提供交易查询、关闭、退款、退款查询以及对账等配套API。

特别注意：

由于前台回跳的不可靠性，前台回跳只能作为商户支付结果页的入口，最终支付结果必须以异步通知或查询接口返回为准，不能依赖前台回跳。

商户系统接收到异步通知以后，必须通过验签（验证通知中的sign参数）来确保支付通知是由支付宝发送的。详细验签规则参考异步通知验签。

接受到异步通知并验签通过后，一定要检查通知内容，包括通知中的app_id, out_trade_no, total_amount是否与请求中的一致，并根据trade_status进行后续业务处理。

使用SDK快速接入

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

关键入参：

参数名称	参数说明
out_trade_no	商户订单号，需要保证不重复
subject	订单标题
seller_id	实际收款账号，一般填写商户PID即可
total_amount	订单金额

异步通知验签：

关键通知参数：

参数名称	参数说明
trade_no	支付宝28位交易号
trade_status	交易状态
total_amount	订单金额

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

关键入参：

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

关键出参：

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

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

关键入参：

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

关键出参：

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

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

关键入参：

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

关键出参：

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

下载账单文件：

关于沙箱

如何接入沙箱

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

手机网站支付沙箱接入注意点

1、手机网站支付支持沙箱接入；在沙箱调通接口后，必须在线上进行测试与验收，所有返回码及业务逻辑以线上为准；
2、手机网站支付只支持余额支付，不支持银行卡、余额宝等其他支付方式；
3、支付时，请使用沙箱买家账号支付，在登录支付宝，输入手机号的页面，点击右下角 支付宝账户登录；