付款码支付接口文档
第一步：创建应用并获取 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 | 交易当前状态 |