快速接入

本文档展示了如何从零开始,使用支付宝开放平台服务端 SDK 快速接入当面付产品,完成与支付宝对接。

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

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

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

第二步:配置应用

添加功能并签约

应用创建完成后,系统会自动跳转到应用详情页面。开发者可以在 功能列表 中点击 添加功能 来添加当面付功能,详细步骤和后续签约步骤可以参考添加应用功能,第三方应用可以代替商户签约。

配置密钥

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

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

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

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

2.接口调用配置
在 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)作为请求参数传入,商户签约完成后,可实现代商户发起请求的能力;具体方法请参考第三方应用授权)。

第四步:开始接入

条码支付调用流程

条码支付的接口调用顺序如下图所示:

  1. 商户系统将用户付款码与订单信息一起通过统一收单交易支付接口(条码支付)alipay.trade.pay 请求到支付宝,并从接口同步返回中获取支付结果。

  2. 根据公共返回参数中的code,这笔交易可能有四种状态:支付成功(10000),支付失败(40004),等待用户付款(10003)和未知异常(20000)。

结果码 说明 处理方式
10000 支付成功 记录交易结果并在客户端显示支付成功,进入后续的业务处理。
40004 支付失败 记录交易结果并在客户端显示错误信息(display_message)。
10003 等待用户付款 发起轮询流程:等待5秒后调用交易查询接口 alipay.trade.query。 通过支付时传入的商户订单号(out_trade_no)查询支付结果(返回参数 TRADE_STATUS ),如果仍然返回等待用户付款(WAIT_BUYER_PAY),则再次等待5秒后继续查询,直到返回确切的支付结果(成功 TRADE_SUCCESS 或 已撤销关闭TRADE_CLOSED),或是超出轮询时间。在最后一次查询仍然返回等待用户付款的情况下,必须立即调用交易撤销接口 alipay.trade.cancel 将这笔交易撤销,避免用户继续支付。
20000 未知异常 调用查询接口确认支付结果,详见异常处理

注意:
商户订单号 out_trade_no 在任何情况下不可重复,即时对于失败或撤销的交易,商户订单号也可能已经被使用了,如需再次发起支付,必须使用新的商户订单号调用接口,否则会报错。

使用SDK快速接入条码支付

交易支付接口 alipay.trade.pay 接入代码如下(以 JAVA 语言为例):

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2"); //获得初始化的AlipayClient
AlipayTradePayRequest request = new AlipayTradePayRequest(); //创建API对应的request类
request.setBizContent("{" +
"    \"out_trade_no\":\"20150320010101001\"," +
"    \"scene\":\"bar_code\"," +
"    \"auth_code\":\"28763443825664394\"," +//auth_code 即付款码,使用一次后即失效,再次使用需要刷新
"    \"subject\":\"Iphone6 16G\"," +
"    \"store_id\":\"NJ_001\"," +
"    \"timeout_express\":\"2m\"," +
"    \"total_amount\":\"88.88\"" +
"  }"); //设置业务参数
AlipayTradePayResponse response = alipayClient.execute(request); //通过alipayClient调用API,获得对应的response类
System.out.print(response.getBody());
// 根据response中的结果继续业务逻辑处理

关键入参:

参数名称 参数说明
out_trade_no 商户订单号,需要保证不重复
scene 条码支付固定传入 bar_code
auth_code 用户付款码,25-30 开头的长度为 16-24 位的数字,实际字符串长度以开发者获取的付款码长度为准
subject 订单标题
store_id 商户门店编号
total_amount 订单金额
timeout_express 交易超时时间

关键出参:

参数名称 参数说明
trade_no 支付宝28位交易号

交易查询接口 alipay.trade.query 接入代码如下(以 JAVA 语言为例):

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 交易当前状态

交易撤销接口 alipay.trade.cancel 接入代码如下(以 JAVA 语言为例):

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:产生了退款

扫码支付调用流程

扫码支付的接口调用顺序如下图所示:

  1. 商户系统调用支付宝预下单接口 alipay.trade.precreate,获得该订单二维码图片地址。

  2. 发起轮询获得支付结果:等待5秒后调用 交易查询接口 alipay.trade.query 通过支付时传入的商户订单号(out_trade_no)查询支付结果(返回参数 TRADE_STATUS),如果仍然返回等待用户付款(WAIT_BUYER_PAY),则再次等待5秒后继续查询,直到返回确切的支付结果(成功 TRADE_SUCCESS 或 已撤销关闭 TRADE_CLOSED),或是超出轮询时间。在最后一次查询仍然返回等待用户付款的情况下,必须立即调用 交易撤销接口 alipay.trade.cancel 将这笔交易撤销,避免用户继续支付。

  3. 除了主动轮询,也可以通过接受异步通知获得支付结果,详见扫码异步通知,注意一定要对异步通知做验签,确保通知是支付宝发出的。

使用SDK快速接入扫码支付

预下单接口 alipay.trade.precreate 接入代码如下(以 JAVA 语言为例):

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小时)的内容,开发者需要自己使用工具根据内容生成二维码图片

第五步:上线应用

应用开发完成后,请开发者自行进行验收和安全性检查(安全性检查可参考《开放平台第三方应用安全开发指南》),验收检查完成后,可申请上线,上线成功后,状态变为已上线,这个状态下的应用能够调用生产环境的接口。
点击了解详细上线应用步骤

接口调用结果码说明

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

关于沙箱

如何接入沙箱

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

当面付沙箱接入注意点

  1. 当面付支持沙箱接入,详见接入指引;在沙箱调通接口后,必须在线上进行测试与验收,所有返回码及业务逻辑以线上为准;

  2. 当面付只支持余额支付,不支持银行卡、余额宝等其他支付方式;

  3. 当面付不支持优惠核销;

  4. 扫码支付中的扫码以及条码支付中的付款码请使用沙箱版钱包测试:点击开发者中心-沙箱环境-沙箱工具;

  5. 查询对账单下载地址,仅测试该接口在沙箱环境中是否可以成功下载对账单,下载的 CSV 对账单仅为账单模板(数据为空),实际数据请使用生产环境。

onlineServer