扫码支付快速接入

本文档展示了如何从零开始,使用支付宝开放平台服务端 SDK 快速接入当面付扫码支付功能。
注意:
文档中的代码示例和 Demo 是用来阐述 API 基本使用方法的,仅针对大众场景,供 ISV(系统服务商) 参考,特殊情况还请 ISV 自行扩展,确保符合自身业务需求。

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

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

第二步:配置应用

添加功能

应用创建完成后,系统会自动跳转到应用详情页面。您可以在 功能列表 中点击 添加功能 来添加 当面付 功能。

配置密钥

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

  • 应用公钥(商户自身的 RSA/RSA2 公钥): 支付宝使用该公钥验证该交易是商户发起。
  • 支付宝公钥(支付宝的 RSA/RSA2 公钥):商户使用该公钥验证该结果是支付宝返回的。

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

上线和签约

开发者在添加功能和配置密钥后,即可将应用提交审核,预计会有一个工作日的审核时间,请耐心等待,详细步骤可参考 上线应用
应用上线完成后,要使用当面付功能,您还需要完成签约。当面付功能需要签约才能生效,请点击功能列表右侧 签约,提交相关信息;完成签约后,需要一个工作日左右的时间审核(审批结果会以短信和邮件形式告知),待审核完毕后,功能的状态会变成“已生效”,您的应用即可使用当面付功能。

详细步骤可以参考 签约功能,第三方应用可以 代替商户签约。当面付除了可以在开放平台签约外,还支持在 支付宝商家中心 签约。

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

下载服务端 SDK

为了帮助开发者调用开放接口,我们提供了开放平台服务端 SDK,包含 JAVA、PHP、Python、NodeJS 和 .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
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 对象。

注意:
ISV/开发者可以通过“第三方应用授权”得到商户授权令牌(app_auth_token)作为请求参数传入,商户签约完成后,可实现代商户发起请求的能力;具体方法请参考第三方应用授权)。

第四步:接入设计

扫码支付适合有各类自助终端的商家,用户在自助终端通过扫码完成支付。当面付扫码支付采用商家/系统服务商后台转发方式接入,商家先预下单到商家后台,再请求到支付宝。具体流程如下图所示:


开发者可以点击下载 支付宝支付物料 或者直接进行 物料系统申请
支付宝为了保证交易安全而采取的一系列安全手段以保证交易安全。点击了解更多安全设计指南

  • 采用 HTTPS 协议传输交易数据,防止数据被截获,解密。
  • 采用 RSA/RSA2 非对称密钥,明确交易双方的身份,保证交易主体的正确性和唯一性。

第五步:调用接口

开发者需要确认自己的应用在审核通过后显示“已上线”,同时完成当面付功能的签约后,才能顺利调用以下接口。否则会有缺少权限的报错。扫码支付的调用流程如下图所示:

  1. 商户系统调用支付宝预下单接口 alipay.trade.precreate,获得该订单的二维码串 qr_code,开发者需要利用二维码生成工具获得最终的订单二维码图片。
  2. 发起轮询获得支付结果:等待 5 秒后调用 交易查询接口 alipay.trade.query 通过支付时传入的商户订单号(out_trade_no)查询支付结果(返回参数 TRADE_STATUS),如果仍然返回等待用户付款(WAIT_BUYER_PAY),则再次等待 5 秒后继续查询,直到返回确切的支付结果(成功 TRADE_SUCCESS 或 已撤销关闭 TRADE_CLOSED),或是超出轮询时间。在最后一次查询仍然返回等待用户付款的情况下,必须立即调用 交易撤销接口 alipay.trade.cancel 将这笔交易撤销,避免用户继续支付。
  3. 除了主动轮询,当订单支付成功时,商户也可以通过设置异步通知(notify_url)来获得支付宝服务端返回的支付结果,详见扫码异步通知,注意一定要对异步通知验签,确保通知是支付宝发出的。

注意
如商户由于客观原因(如无公网服务器接受支付宝请求等)无法接受异步支付通知,则忽略上图中的步骤 3.4 和3.4.1。
更多注意事项请参考异常处理

预下单

以 JAVA 语言为例,交易预下单接口 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 订单二维码(有效时间 2 小时)以字符串的格式返回,开发者需要自己使用工具根据内容生成二维码图片

查询交易

以 JAVA 语言为例,交易查询接口 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 交易当前状态

撤销交易

以 JAVA 语言为例,交易撤销接口 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:产生了退款

退款

当商户由于业务原因(如金额错误,用户退款或者对账不平等等)可能需要退款,商家可以使用 交易成功的商户订单号 支付宝交易号 进行退款 , 支持全额和部分退款:

  • 退款的途径按照支付途径原路返回;
  • 支付渠道为花呗、余额等退款即时到账;
  • 银行卡的退款时间以银行退款时间为准,一般情况下 2 小时内可到账;
  • 开发者也可以在商家中心(b.alipay.com)中退款;
  • 退款是否成功可以根据同步响应的 fund_change 参数来判断,返回值为 Y 则表示退款成功。

退款接口 alipay.trade.refund 的调用过程如下图所示:


点击了解更多退款流程细节。

扩展功能

优惠与运营

开发者或商家可以为商品进行促销活动。
点击了解更多优惠运营支持方式;点击了解更多开发接入优惠

对账

为了保障交易的正确性,支付宝提供了交易账单数据提供给商户对账。
点击了解更多对账接入;如果对账不平,点击了解更多单边账的处理方式

返佣

服务商帮助商户接入支付能力时候可以获取交易的返佣。 返佣技术接入只需在 API 中传入返佣服务商ID,开发者即可获取返佣。
为了确保得到返佣,需要返佣的 ISV 请确保传入正确的返佣参数。建议系统商接入的所有订单都加入 sys_service_provider_id 参数,并检查参数是否正确。系统商如果传入错误的参数将无法获得返佣。
点击在开放平台查看返佣明细

接入沙箱

支付能力直接涉及到交易与资金,为了方便开放者调试支付能力,开放平台已经准备好沙箱环境,包括沙箱环境账号和沙箱版支付宝钱包,这样开发者就可以在沙箱环境调试了。点击了解如何接入沙箱接入沙箱环境
当面付沙箱接入的注意点如下:

  1. 在沙箱调通接口后,必须在线上进行测试与验收,所有返回码及业务逻辑以线上为准;
  2. 当面付只支持余额支付,不支持银行卡、余额宝等其他支付方式;
  3. 当面付不支持优惠核销;
  4. 扫码支付中的扫码以及条码支付中的付款码请使用沙箱版钱包测试:点击开发者中心-沙箱环境-沙箱工具;
  5. 查询对账单下载地址,仅测试该接口在沙箱环境中是否可以成功下载对账单,下载的 CSV 对账单仅为账单模板(数据为空),实际数据请使用生产环境。

接口调用结果码说明

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

监控应用

应用上线后还可以在开放平台,查看应用运行情况以及交易状态。
点击了解更多监控产品;点击开始监控

onlineServer