付款码支付接口文档
第一步:创建应用并获取 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 非对称密钥,明确交易双方的身份,保证交易主体的正确性和唯一性。
- 条码定时刷新,防止被拍照。
- 防止截屏(截屏后二维码失效)。
第五步:调用接口
开发者需要确认自己的应用在审核通过后显示“已上线”,同时完成当面付功能的签约后,才能顺利调用以下接口。否则会有缺少权限的报错。条码支付的调用流程如下图所示:
a. 创建交易并支付(如图,1-1.1.3 步所示)。
b. 根据返回的结果,确定支付状态,从而进行相应处理(包括必要时关闭交易), 如图 opt 区块中所示,第 2 步表示支付成功, 返回支付成功页。
c. 第 3 步表示返回的参数为待用户付款(code=10003)或者系统异常(code=20000)、网络超时等场景下处理方式。
d. 第 4 步表示轮询结束仍未处理成功,需要撤销订单。
e. 第 5 步表示返回支付失败(code=40004) 时, 需要重新检查参数,重新发起支付。
更多请参考 异常处理。
支付
商家系统将用户付款码与订单信息一起通过 统一收单交易支付接口(条码支付)alipay.trade.pay 请求到支付宝,并从接口同步返回中获取支付结果。根据公共返回参数中的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 | 未知异常 | 调用查询接口确认支付结果,详见 异常处理。 |
以 JAVA 语言为例,统一收单交易支付接口(条码支付)alipay.trade.pay 接入代码如下:
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\"," + //即用户在支付宝客户端内出示的付款码,使用一次即失效,需要刷新后再去付款
" \"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位交易号 |
查询交易
以 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 | 交易当前状态 |