付款码支付接口文档
<h1>第一步：创建应用并获取 APPID</h1>
<p>要在您的应用中接入支付宝开放平台中的能力，您需要先登录支付宝开放平台（<a href="https://open.alipay.com/">open.alipay.com</a>），在开发者中心中创建登记您的应用，并提交审核，审核通过后会为您生成应用唯一标识（APPID），并且可以申请开通开放产品使用权限。通过 APPID 您的应用才能调用开放产品的接口能力。需要详细了解开放平台创建应用步骤请参考<a href="https://opendocs.alipay.com/open/200/105310">《开放平台应用创建指南》</a>。</p>
<h1>第二步：配置应用</h1>
<h2>添加功能</h2>
<p>应用创建完成后，系统会自动跳转到应用详情页面。您可以在 <strong>功能列表</strong> 中点击 <strong>添加功能</strong> 来添加 当面付 功能。</p>
<h2>配置密钥</h2>
<p>为了保证交易双方（商户和支付宝）的身份和数据安全，开发者在调用接口前，需要配置双方密钥，对交易数据进行双方校验。密钥包含应用私钥（APP_PRIVATE_KEY）和应用公钥（APP_PUBLIC_KEY）。生成密钥后，开发者需要在开放平台开发者中心进行密钥配置，配置完成后可以获取支付宝公钥（ALIPAY_PUBLIC_KEY），配置的详细步骤请参考《<a href="https://opendocs.alipay.com/open/291/105971">配置应用环境</a>》。您还可以通过观看 <a href="https://opendocs.alipay.com/open/291/106103/">快速签名教程</a> 学习密钥的配置。密钥的配置旨在对交易数据进行双方校验。具体流程如下图所示：</p>
<p><img src="https://gw.alipayobjects.com/zos/skylark-tools/public/files/f0b9c2f51f2698c9f1b3163e0123e23e.png" alt="img" /></p>
<ul>
<li>应用公钥（商户自身的 RSA/RSA2 公钥）: 支付宝使用该公钥验证该交易是商户发起。</li>
<li>支付宝公钥（支付宝的 RSA/RSA2 公钥）：商户使用该公钥验证该结果是支付宝返回的。</li>
</ul>
<p><strong>说明</strong>：</p>
<p>支付宝开放平台 SDK 封装了签名和验签过程，只需配置账号及密钥参数，建议开发者使用。开发者还可以通过 <a href="https://opendocs.alipay.com/open/291/106096">自助排查流程</a> 和 <a href="https://opendocs.alipay.com/open/200/106120">验签教程</a> 自助排查配置应用过程中遇到的问题。</p>
<h2>上线和签约</h2>
<p>开发者在添加功能和配置密钥后，即可将应用提交审核，预计会有一个工作日的审核时间，请耐心等待，详细步骤可参考 <a href="https://opendocs.alipay.com/open/200/golive/">上线应用</a>。</p>
<p>应用上线完成后，要使用当面付功能，您还需要完成签约。当面付功能需要签约才能生效，请点击功能列表右侧 <strong>签约</strong>，提交相关信息；完成签约后，需要一个工作日左右的时间审核（审批结果会以短信和邮件形式告知），待审核完毕后，功能的状态会变成“已生效”，您的应用即可使用当面付功能。</p>
<p>详细步骤可以参考 <a href="https://opendocs.alipay.com/open/200/105314/">签约功能</a>，第三方应用可以 <a href="https://opendocs.alipay.com/open/20171218110821153225/dangmianfu">代替商户签约</a>。当面付除了可以在开放平台签约外，还支持在 <a href="https://b.alipay.com/signing/productSetV2.htm?mrchportalwebServer=https%3A%2F%2Fmrchportalweb.alipay.com">支付宝商家中心</a> 签约。</p>
<h1>第三步：搭建和配置开发环境</h1>
<h2>下载服务端 SDK</h2>
<p>为了帮助开发者调用开放接口，我们提供了<a href="https://opendocs.alipay.com/open/54/103419/">开放平台服务端 SDK</a>，包含 JAVA、PHP、Python、NodeJS 和 .NET五种语言版本，封装了签名、验签和 HTTP 接口请求等基础功能。请先下载对应语言版本的 SDK 并引入您的开发工程。</p>
<h2>接口调用配置</h2>
<p>在 SDK 调用前需要进行初始化，以 JAVA 代码为例：</p>
<pre><code class="language-javascript">AlipayClient alipayClient = new DefaultAlipayClient ( URL , APP_ID , APP_PRIVATE_KEY , FORMAT , CHARSET , ALIPAY_PUBLIC_KEY , SIGN_TYPE );</code></pre>
<p>关键参数说明：</p>
<table>
<thead>
<tr>
<th>配置参数</th>
<th>示例值解释</th>
<th>获取方式/示例值</th>
</tr>
</thead>
<tbody>
<tr>
<td>URL</td>
<td>支付宝网关（固定）</td>
<td><a href="https://openapi.alipay.com/gateway.do">https://openapi.alipay.com/gateway.do</a></td>
</tr>
<tr>
<td>APP_ID</td>
<td>APPID 即创建应用后生成</td>
<td>详情见 <strong>第一步：创建应用并获取 APPID</strong></td>
</tr>
<tr>
<td>APP_PRIVATE_KEY</td>
<td>开发者应用私钥，由开发者自己生成</td>
<td>详见<a href="https://opendocs.alipay.com/open/#s1"> </a><strong>第二步：配置应用</strong> > <strong>配置密钥</strong></td>
</tr>
<tr>
<td>FORMAT</td>
<td>参数返回格式，只支持 json 格式</td>
<td>json（固定）</td>
</tr>
<tr>
<td>CHARSET</td>
<td>请求和签名使用的字符编码格式，支持 GBK 和 UTF-8</td>
<td>开发者根据实际工程编码配置</td>
</tr>
<tr>
<td>ALIPAY_PUBLIC_KEY</td>
<td>支付宝公钥，由支付宝生成</td>
<td>详见 <strong>第二步：配置应用</strong> > <strong>配置密钥</strong></td>
</tr>
<tr>
<td>SIGN_TYPE</td>
<td>商户生成签名字符串所使用的签名算法类型，目前支持 RSA2 和 RSA，推荐商家使用 RSA2。</td>
<td>RSA2</td>
</tr>
</tbody>
</table>
<p>接下来，开发者就可以用 alipayClient 来调用具体的 API 了。alipayClient 只需要初始化一次，后续调用不同的 API 都可以使用同一个 alipayClient 对象。</p>
<p><strong>注意：</strong></p>
<p>ISV/开发者可以通过“第三方应用授权”得到商户授权令牌（app_auth_token）作为请求参数传入，商户签约完成后，可实现代商户发起请求的能力；具体方法请参考 <a href="https://opendocs.alipay.com/isv/10467/xldcyq">第三方应用授权</a>）。</p>
<h1>第四步：接入设计</h1>
<p>在开始开发前，您需要明确接入的方式或者所需物料等。应用接入方式分为两类：<strong>门店直连方式和商户</strong> 和 <strong>系统商后台转发</strong> 方式。</p>
<p>开发者可以点击下载 <a href="https://open.alipay.com/isv/stuffTemplateDownload.htm?type=basicDomesticPayment">支付宝支付物料</a> 或者直接进行 <a href="https://openhome.alipay.com/isv/stuffApplyList.htm">物料系统申请</a>。</p>
<h2>门店直连方式</h2>
<p>商家收银台直接通过公网向支付宝发起收款；个人商户或者单独门店建议采用直连方式接入。具体流程如下图所示：</p>
<p><img src="https://gw.alipayobjects.com/zos/skylark-tools/public/files/4c5ae9bbeb064e8b63b9910057ec14e6.png" alt="img" /></p>
<h2>商户/系统商后台转发方式</h2>
<p>商家收银台先请求到商家后台，再请求到支付宝；有多家门店的商户，大型商户, 自有商户后台的商户建议采用该方式接入。具体流程如下图所示：</p>
<p><img src="https://gw.alipayobjects.com/zos/skylark-tools/public/files/f37109f7dc24d870fdcbcec05a6bc07b.png" alt="img" /></p>
<h2>安全设计</h2>
<p>支付宝为了保证交易安全而采取的一系列安全手段以保证交易安全。点击了解 <a href="https://opendocs.alipay.com/open/common/105912">更多安全设计指南</a>。</p>
<ul>
<li>采用 HTTPS 协议传输交易数据，防止数据被截获，解密。</li>
<li>采用 RSA/RSA2 非对称密钥，明确交易双方的身份，保证交易主体的正确性和唯一性。</li>
<li>条码定时刷新，防止被拍照。</li>
<li>防止截屏（截屏后二维码失效）。</li>
</ul>
<h1>第五步：调用接口</h1>
<p>开发者需要确认自己的应用在审核通过后显示“已上线”，同时完成当面付功能的签约后，才能顺利调用以下接口。否则会有缺少权限的报错。条码支付的调用流程如下图所示：</p>
<p><img src="https://gw.alipayobjects.com/zos/skylark-tools/public/files/112a3120eb54e301a345b277f9d2cb49.png" alt="img" /></p>
<p>a. 创建交易并支付（如图，1-1.1.3 步所示）。</p>
<p>b. 根据返回的结果，确定支付状态，从而进行相应处理（包括必要时关闭交易), 如图 opt 区块中所示，第 2 步表示支付成功， 返回支付成功页。</p>
<p>c. 第 3 步表示返回的参数为待用户付款（code=10003）或者系统异常（code=20000）、网络超时等场景下处理方式。</p>
<p>d. 第 4 步表示轮询结束仍未处理成功，需要撤销订单。</p>
<p>e. 第 5 步表示返回支付失败（code=40004） 时， 需要重新检查参数，重新发起支付。</p>
<p>更多请参考 <a href="https://opendocs.alipay.com/open/194/105322/#异常处理">异常处理</a>。</p>
<h2>支付</h2>
<p>商家系统将用户付款码与订单信息一起通过 统一收单交易支付接口（条码支付）<a href="https://opendocs.alipay.com/apis/api_1/alipay.trade.pay">alipay.trade.pay</a> 请求到支付宝，并从接口同步返回中获取支付结果。根据公共返回参数中的code，这笔交易可能有四种状态：支付成功（10000），支付失败（40004），等待用户付款（10003）和未知异常（20000）。</p>
<table>
<thead>
<tr>
<th>结果码</th>
<th>说明</th>
<th>处理方式</th>
</tr>
</thead>
<tbody>
<tr>
<td>10000</td>
<td>支付成功</td>
<td>记录交易结果并在客户端显示支付成功，进入后续的业务处理。</td>
</tr>
<tr>
<td>40004</td>
<td>支付失败</td>
<td>记录交易结果并在客户端显示错误信息（display_message）。</td>
</tr>
<tr>
<td>10003</td>
<td>等待用户付款</td>
<td>发起轮询流程：等待 5 秒后调用 <a href="https://opendocs.alipay.com/apis/api_1/alipay.trade.query/">交易查询接口 alipay.trade.query</a>。 通过支付时传入的商户订单号（out_trade_no）查询支付结果（返回参数 TRADE_STATUS ），如果仍然返回等待用户付款（WAIT_BUYER_PAY），则再次等待5秒后继续查询，直到返回确切的支付结果（成功 TRADE_SUCCESS 或 已撤销关闭TRADE_CLOSED），或是超出轮询时间。在最后一次查询仍然返回等待用户付款的情况下，必须立即调用 <a href="https://opendocs.alipay.com/apis/api_1/alipay.trade.cancel">交易撤销接口 alipay.trade.cancel</a> 将这笔交易撤销，避免用户继续支付。</td>
</tr>
<tr>
<td>20000</td>
<td>未知异常</td>
<td>调用查询接口确认支付结果，详见 <a href="https://opendocs.alipay.com/open/194/105322/#e449cf10">异常处理</a>。</td>
</tr>
</tbody>
</table>
<p>以 JAVA 语言为例，统一收单交易支付接口（条码支付）<a href="https://opendocs.alipay.com/apis/api_1/alipay.trade.pay">alipay.trade.pay</a> 接入代码如下：</p>
<pre><code class="language-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\"," + //即用户在支付宝客户端内出示的付款码，使用一次即失效，需要刷新后再去付款
" \"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中的结果继续业务逻辑处理</code></pre>
<p>关键入参：</p>
<table>
<thead>
<tr>
<th>参数名称</th>
<th>参数说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>out_trade_no</td>
<td>商户订单号，需要保证不重复</td>
</tr>
<tr>
<td>scene</td>
<td>条码支付固定传入 bar_code</td>
</tr>
<tr>
<td>auth_code</td>
<td>用户付款码，25-30 开头的长度为 16-24 位的数字，实际字符串长度以开发者获取的付款码长度为准；付款码使用一次即失效</td>
</tr>
<tr>
<td>subject</td>
<td>订单标题</td>
</tr>
<tr>
<td>store_id</td>
<td>商户门店编号</td>
</tr>
<tr>
<td>total_amount</td>
<td>订单金额</td>
</tr>
<tr>
<td>timeout_express</td>
<td>交易超时时间</td>
</tr>
</tbody>
</table>
<p>关键出参：</p>
<table>
<thead>
<tr>
<th>参数名称</th>
<th>参数说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>trade_no</td>
<td>支付宝28位交易号</td>
</tr>
</tbody>
</table>
<h2>查询交易</h2>
<p>以 JAVA 语言为例，交易查询接口 <a href="https://opendocs.alipay.com/apis/api_1/alipay.trade.query">alipay.trade.query</a> 接入代码如下：</p>
<pre><code class="language-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中的结果继续业务逻辑处理</code></pre>
<p>关键入参：</p>
<table>
<thead>
<tr>
<th>参数名称</th>
<th>参数说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>out_trade_no</td>
<td>支付时传入的商户订单号，与 trade_no 必填一个</td>
</tr>
<tr>
<td>trade_no</td>
<td>支付时返回的支付宝交易号，与 out_trade_no 必填一个</td>
</tr>
</tbody>
</table>
<p>关键出参：</p>
<table>
<thead>
<tr>
<th>参数名称</th>
<th>参数说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>trade_no</td>
<td>支付宝 28 位交易号</td>
</tr>
<tr>
<td>out_trade_no</td>
<td>支付时传入的商户订单号</td>
</tr>
<tr>
<td>trade_status</td>
<td>交易当前状态</td>
</tr>
</tbody>
</table>