支付宝支付接口说明
<h2>产品介绍 <a href="https://opendocs.alipay.com/mini/cloudservice/khf843"><img src="https://gw.alipayobjects.com/zos/bmw-prod/c0416ebb-8c69-40cd-8cdc-ac265ee4ea26.svg" alt="image" /> </a></h2>
<p>在商家开发的小程序中，用户也可以唤起支付宝收银台进行支付。小程序支付和 APP 支付的支付流程与体验基本一致，小程序支付也支持核销口碑券和口碑商户优惠功能。已签约小程序支付或在口碑开店的商户建议接入小程序支付。</p>
<p>系统服务商可以通过代签约接口 <a href="https://docs.open.alipay.com/api_50/alipay.open.agent.facetoface.sign/">alipay.open.agent.facetoface.sign</a> 代替商家签约当面付，使用小程序支付。</p>
<p>小程序支付在小程序内不能通过扫码、条码、声波付等方式支付，只能唤起收银台进行支付；目前小程序支付还不支持免密支付。</p>
<p>小程序支付的使用流程如下：</p>
<ol>
<li>用户在小程序中选择商品下单并确认购买，进入支付环节，用户点击确认支付；</li>
<li>进入到支付宝页面后，小程序唤起支付宝支付，出现支付界面；</li>
<li>用户确认收款方和金额，点击 <strong>立即付款</strong> 后进行支付；</li>
<li>输入正确支付密码后，显示支付成功页；</li>
</ol>
<p><img src="https://gw.alipayobjects.com/zos/skylark-tools/public/files/2be317a893dbba908e519ab31eb37a1c.png?x-oss-process=image/resize,w_2000" alt="小程序支付.png" /></p>
<p>点击支付成功页右上角 <strong>完成</strong> 按钮，可跳转到自定义页面，开发者可根据付款结果个性化展示订单处理结果，如下图所示。（支持跳转到生活号页面，但仅允许跳转至与该小程序关联的生活号页面，更多跳转方式信息请参见 <a href="https://docs.alipay.com/fw/api/luteex">生活号客户端跳转链接</a>。）</p>
<p><img src="https://gw.alipayobjects.com/zos/skylark-tools/public/files/ae649798710933be8b4afc3abc113243.png" alt="img" /></p>
<h2>准入条件</h2>
<ul>
<li>该能力对企业支付宝账户和个体工商户开放；</li>
<li>申请者必须拥有经过实名认证的支付宝账户；</li>
<li>需提供真实有效的营业执照，且支付宝账户名称需与营业执照主体一致；</li>
<li>网站能正常访问且页面显示完整，网站需要明确经营内容且有完整的商品信息；</li>
<li>网站必须通过 ICP 备案。如为个体工商户，网站备案主体需要与支付宝账户主体名称一致；如为个体工商户，则团购不开放，且古玩、珠宝等奢侈品、投资类行业无法申请本产品。</li>
</ul>
<h2>计费模式</h2>
<p>费率按单笔计算，四舍五入，保留后两位。 一般行业费率：0.6%；特殊行业费率：1.2%，特殊行业范围包括：手机、通讯设备销售；家用电器；数码产品及配件；休闲游戏；网络游戏点卡、渠道代理；游戏系统商；网游周边服务、交易平台；网游运营商（含网页游戏）。</p>
<h2>关联产品推荐</h2>
<p>小程序支付目前支持 <a href="https://opendocs.alipay.com/mini/introduce/antcreditpay-istallment#接入指引">花呗分期</a> 的付款方式支付；</p>
<p>在支付完成后，开发者可以根据支付宝交易号（trade_no）将订单信息同步到“订单中心”小程序，查看 <a href="https://opendocs.alipay.com/mini/introduce/ordercenter#异步同步">详细接入步骤</a>。</p>
<h2>接入指引</h2>
<h3>第一步：创建小程序</h3>
<p>要在您的小程序内使用小程序支付功能，您需要首先完成 <a href="https://docs.alipay.com/mini/introduce/register">开发者入驻</a> 并 <a href="https://docs.alipay.com/mini/introduce/create">创建小程序</a>。</p>
<h3>第二步：添加功能</h3>
<p>小程序创建完成后，开发者在 <strong>功能列表</strong> 部分可以点击 <strong>添加功能</strong> 来给创建的小程序添加功能，如下图所示；开发者勾选 <strong>小程序支付</strong> 功能后，点击右下角 <strong>确定</strong> 即完成添加功能。</p>
<p><img src="http://mdn.alipayobjects.com/afts/img/A*dadNTp2xCGbzG-hHt78ovwBkAa8wAA/original?bz=openpt_doc&t=WX1fgt7vnpuHCORJVmP1sAAAAABkMK8AAAAA" alt="image" /> </p>
<p><strong>注意</strong>：</p>
<p>第三方应用代商户实现小程序支付需要：</p>
<p>1、在三方应用上添加当面付功能。</p>
<p>2、代商户签约当面付，参考文档 <a href="https://opendocs.alipay.com/mini/isv/zdfy7u">代商家签约</a>。</p>
<h3>第三步：签约功能</h3>
<p>添加完成功能后，请点击功能列表右侧对应功能的 <strong>签约</strong> 链接；用户签约后，需要 1 个工作日左右的审批时间（审批结果会以短信和邮件形式告知），审批通过后，功能状态会变为“已生效”，即可调用小程序支付功能。</p>
<h3>第四步：集成并配置 SDK</h3>
<p>服务端 SDK 需要商户集成在自己的服务端系统中，用于后续的服务端接口调用。</p>
<h4>下载服务端 SDK</h4>
<p>为了帮助开发者调用开放接口，我们提供了 <a href="https://docs.open.alipay.com/54/103419">开放平台服务端 SDK</a> ，包含 JAVA、PHP、NodeJS、Python 和 .NET 五种语言，封装了签名 & 验签、HTTP 接口请求等基础功能。请先下载对应语言版本的 SDK 并引入您的开发工程。</p>
<h4>接口调用配置</h4>
<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><code>https://openapi.alipay.com/gateway.do</code></td>
</tr>
<tr>
<td>APPID</td>
<td>APPID 即创建应用后生成</td>
<td>获取见 <a href="https://docs.open.alipay.com/200/105310#s5">创建应用</a></td>
</tr>
<tr>
<td>APP_PRIVATE_KEY</td>
<td>开发者私钥，由开发者自己生成</td>
<td>获取见 <a href="https://docs.open.alipay.com/291/105971">配置密钥</a></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>获取详见 <a href="https://docs.open.alipay.com/291/105971">配置密钥</a></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 /开发者可以通过 <a href="https://docs.alipay.com/isv/10467/xldcyq">第三方应用授权</a> 得到商户授权令牌（app_auth_token）作为请求参数传入，实现代商户发起请求的能力。</p>
<blockquote>
<p>如果您在调用 API 时出现报错：</p>
<ul>
<li>欢迎前往 <a href="https://forum.alipay.com/mini-app">开放社区</a> 提问、留言；</li>
<li>在 <a href="https://opensupport.alipay.com/support/knowCategory/20057/46838">公共错误码</a> 中根据错误码的类型，查找相关错误码及解决方案；</li>
<li>在 <a href="https://opensupport.alipay.com/workflow/consultation/question.htm?channelCode=miniApp&ant_source=opendoc">蚂蚁问答</a> 问答页面直接输入您遇到的错误码；</li>
<li>在 <a href="https://opensupport.alipay.com/support/tools/cloudparse">云排查</a> 中排查遇到的问题；</li>
<li>您还可以在 <a href="https://docs.open.alipay.com/catalog">文档中心</a> 直接搜索您要的答案。</li>
</ul>
</blockquote>
<h3>第五步：调用接口</h3>
<p>小程序支付调用流程如下图所示：</p>
<p><img src="https://gw.alipayobjects.com/zos/skylark-tools/public/files/0e3fc255e4af921d2c099a31548d3d48.png" alt="22.png" /></p>
<p>1.在小程序端调用 <a href="https://docs.alipay.com/mini/api/owycmh">my.request</a> 接口，连接到商户服务端。</p>
<pre><code class="language-javascript">my.request({
url: '商户服务端地址',//须加httpRequest域白名单
method: 'POST',
data: {//data里的key、value是开发者自定义的
from: '支付宝',
order: 'XXXXX',//订单信息
},
dataType: 'json',
success: function(res) {
my.alert({content: 'success'});
},
fail: function(res) {
my.alert({content: 'fail'});
},
complete: function(res) {
my.hideLoading();
my.alert({content: 'complete'});
}
});</code></pre>
<p>2.在服务端调用 <a href="https://docs.open.alipay.com/api_1/alipay.trade.create/"> alipay.trade.create</a> (统一收单交易创建接口)，获得支付宝交易号 tradeNO（以 Java 代码为例）：</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");
//实例化具体API对应的request类,类名称和接口名称对应,当前调用接口名称：alipay.trade.create.
AlipayTradeCreateRequest request = new AlipayTradeCreateRequest();
//SDK已经封装掉了公共参数，这里只需要传入业务参数。
request.setBizContent("{" +
"\"out_trade_no\":\"20171115010101001\"," +// 可以随机生成订单号：String outTradeNo = UUID.randomUUID().toString().replace("-", "");
"\"total_amount\":0.01," +
"\"subject\":\"Iphone616G\"," +
"\"buyer_id\":\"用户pid\"" + // 小程序支付场景中该参数必传
"}");
try {
AlipayTradeCreateResponse response = alipayClient.execute(request);
String trade_no = response.getTradeNo();// 获取返回的tradeNO。
} catch (AlipayApiException e) {
e.printStackTrace();
}</code></pre>
<p>注意：</p>
<p>小程序支付场景中 <a href="https://docs.open.alipay.com/api_1/alipay.trade.create/">alipay.trade.create</a> 接口中的 buyer_id 为必填项， 该值为付款用户的支付宝 user_id，获取详情参见 <a href="https://opendocs.alipay.com/mini/introduce/authcode">用户授权文档</a>。</p>
<p>3.在小程序端使用 tradeNO，调用 <a href="https://docs.alipay.com/mini/api/openapi-pay">my.tradePay</a> 接口唤起支付收银台。</p>
<pre><code class="language-javascript">my.tradePay({
tradeNO: '2017111521001104105336677922',
success: function(res) {
my.alert({
content: JSON.stringify(res),
});
},
fail: function(res) {
my.alert({
content: JSON.stringify(res),
});
},
});</code></pre>
<h2>接入花呗分期说明</h2>
<p>小程序支付目前支持 <a href="https://docs.alipay.com/mini/introduce/antcreditpay-istallment">花呗分期</a> 的付款方式。要在小程序支付中使用花呗分期付款，只需要开发者在 <a href="https://docs.open.alipay.com/api_1/alipay.trade.create/">alipay.trade.create</a> （统一收单交易创建接口接口）中传入对应的参数即可。小程序支持以下两种模式接入花呗分期。</p>
<p><strong>标准收银台模式</strong></p>
<p>支付宝标准收银台展示花呗分期渠道（仅支持用户承担手续费），无需额外签约花呗分期，且无需进行额外的花呗分期参数的透传开发工作，可以直接在支付宝标准收银台中展示出花呗分期渠道。</p>
<p><strong>单通道模式</strong></p>
<p>商家可以根据需要，将花呗分期资金渠道前置或者与其他付款方式并列，实现花呗分期单通道模式。该方式下，如果当前花呗分期渠道无法支付成功，则可以继续使用其他支付渠道进行付款。</p>
<p>开发者需要将花呗分期参数传入到 <code>extend_params</code> 中，格式如下：</p>
<pre><code class="language-javascript">"extend_params":{"hb_fq_num":"3","hb_fq_seller_percent":"100"}</code></pre>
<ul>
<li><code>hb_fq_num</code> 代表花呗分期数，仅支持传入 3、6、12，其他期数暂不支持，传入会报错；</li>
<li><code>hb_fq_seller_percent</code> 代表卖家承担收费比例，商家承担手续费传入 100，用户承担手续费传入 0，仅支持传入 100、0 两种，其他比例暂不支持，传入会报错。</li>
</ul>
<h2>API 列表</h2>
<table>
<thead>
<tr>
<th>接口名称</th>
<th>接口中文名称</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="https://docs.open.alipay.com/api_1/alipay.trade.create/">alipay.trade.create</a></td>
<td>统一收单交易创建接口</td>
</tr>
<tr>
<td><a href="https://docs.alipay.com/mini/api/openapi-pay">my.tradePay</a></td>
<td>小程序唤起支付</td>
</tr>
<tr>
<td><a href="https://docs.alipay.com/mini/api/owycmh">my.request</a></td>
<td>向指定服务器发起一个跨域 http 请求</td>
</tr>
<tr>
<td><a href="https://docs.open.alipay.com/api_50/alipay.open.agent.facetoface.sign/">alipay.open.agent.facetoface.sign</a></td>
<td>代签约当面付接口（也适用于服务商代替商户签约小程序支付）</td>
</tr>
</tbody>
</table>
<h2>快速接入DEMO</h2>
<p>支付宝开放平台还为开发者提供了小程序支付 DEMO，开发者可以参考 <a href="https://docs.alipay.com/mini/quick-example/payment">快速示例</a> 文档进行体验和实现快速接入。</p>
<h2>异步通知</h2>
<p>订单支付成功时，商户可以通过在 <a href="https://docs.open.alipay.com/api_1/alipay.trade.create/">alipay.trade.create</a> 设置异步通知（notify_url）来获得支付宝服务端返回的支付结果，当异步通知中返回的 trade_status(交易状态)为 TRADE_SUCCESS 时，表示支付成功。其他有关异步通知的问题可参考 <a href="https://docs.open.alipay.com/194/103296/">服务器异步通知参数说明</a> 。</p>
<p><strong>注意：</strong></p>
<p>开发者设置的 notify_url 需要为外部网络环境可正常访问的网址，且状态码为200，支付结果请以异步通知或 <a href="https://docs.open.alipay.com/api_1/alipay.trade.query">支付订单查询接口</a> 返回值为准。</p>
<h2>补充说明</h2>
<ul>
<li>服务端接口调用，请查看 <a href="https://docs.open.alipay.com/54/103419/">服务端 SDK</a> ；</li>
<li>服务端支付API，比如撤销、退款、关闭等，查看 <a href="https://docs.open.alipay.com/api_1">支付 OpenAPI</a> ；</li>
<li><a href="https://docs.open.alipay.com/291/105971/">签名逻辑</a> ；</li>
<li><a href="https://docs.open.alipay.com/api_1/alipay.trade.create/">请求参数及同步通知参数说明</a> ；</li>
<li><a href="https://docs.open.alipay.com/204/105303/">交易辅助接口</a> ；</li>
<li><a href="https://docs.open.alipay.com/204/106262/">对账说明</a> 。</li>
</ul>
<h2>常见问题</h2>
<blockquote>
<p>如果您在调用 API 时出现报错：</p>
<ul>
<li>欢迎前往 <a href="https://forum.alipay.com/mini-app">开放社区</a> 提问、留言；</li>
<li>在 <a href="https://opensupport.alipay.com/support/knowCategory/20057/46838">公共错误码</a> 中根据错误码的类型，查找相关错误码及解决方案；</li>
<li>在 <a href="https://opensupport.alipay.com/workflow/consultation/question.htm?channelCode=miniApp&ant_source=opendoc">蚂蚁问答</a> 问答页面直接输入您遇到的错误码；</li>
<li>在 <a href="https://opensupport.alipay.com/support/tools/cloudparse">云排查</a> 中排查遇到的问题；</li>
<li>您还可以在 <a href="https://docs.open.alipay.com/catalog">文档中心</a> 直接搜索您要的答案。</li>
</ul>
</blockquote>
<h3>Q：在 IDE 上调用 my.tradePay 报错 “error2： 无效的 API入参”，如何处理？</h3>
<p>A：目前IDE模拟器调用my.tradePay后会生成一个支付二维码（有效时间10分钟），开发者在支付宝客户端扫码支付，支付结果会同步my.tradePay回调。</p>
<p><img src="http://mdn.alipayobjects.com/afts/img/A*KLeQT4b6EowAAAAAAAAAAABkAa8wAA/1024w_1024h_1l.png?bz=openpt_doc&t=uUhXKS1VEy9FqApyCjij1AAAAABkMK8AAAAA" alt="image" /> </p>
<h3>Q：小程序支付无法调起支付，如何处理？</h3>
<p>A：可能原因如下：</p>
<ul>
<li>服务端回传的 tradeNO 出错，导致传入 my.tradePay 的 tradeNO 参数错误。</li>
<li>小程序支付无法在 IDE 模拟器中进行测试。</li>
</ul>
<p>解决方案：</p>
<p>1、在服务端调用 <a href="https://docs.open.alipay.com/api_1/alipay.trade.create/"> alipay.trade.create</a> (统一收单交易创建接口)，获得支付宝交易号 tradeNO（以 Java 代码为例）。</p>
<pre><code class="language-javascript">//实例化客户端
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
//实例化具体API对应的request类,类名称和接口名称对应,当前调用接口名称：alipay.trade.create.
AlipayTradeCreateRequest request = new AlipayTradeCreateRequest();
//SDK已经封装掉了公共参数，这里只需要传入业务参数。
request.setBizContent("{" +
"\"out_trade_no\":\"20171115010101001\"," +
"\"total_amount\":0.01," +
"\"subject\":\"Iphone616G\"," +
"\"buyer_id\":\"用户pid\"" +
"}");
try {
//使用的是execute
AlipayTradeCreateResponse response = alipayClient.execute(request);
String trade_no = response.getTradeNo();//获取返回的tradeNO。
} catch (AlipayApiException e) {
e.printStackTrace();
}</code></pre>
<p>2、将获得的 tradeNO 参数传入 my.tradePay 中（设置为固定值），并在真机上进行测试。</p>
<h3>Q：如果想实现识别支付的卡做立减活动，小程序支付是否能查询到用户支付时使用的是什么银行的银行卡？</h3>
<p>A：涉及用户的敏感信息，无法实现 。</p>
<h3>Q：小程序支付是否支持绑定多个收款账号？</h3>
<p>A：不支持，小程序支付默认收款账号为小程序拥有账号。</p>
<h3>Q：小程序支付时报错 ALIN10046 是什么原因？</h3>
<p>A：报错描述：花呗分期暂不可用，请更换付款方式(ALIN10046)；</p>
<p>报错原因：</p>
<p>1、用户尚未开通花呗或花呗分期可用额度不足</p>
<p>2、商户未签约花呗分期产品，暂不支持花呗分期，或选择的商品不支持花呗分期</p>
<p>3、分期金额未达到商户设定的分期起点金额</p>
<p>4、交易触发了限制规则，被判定为高风险交易，导致被风控</p>
<p>解决方案：</p>
<p>1、检查用户是否开通花呗分期，以及用户花呗可用额度是否大于交易金额；</p>
<p>2、商户是否签约了花呗分期产品；</p>
<p>3、可设置goods_type=1；goods_type：商品主类型：0表示虚拟类商品，1表示实物类商品（默认）</p>
<p>4、花呗分期交易金额建议设置成至少100元以上；</p>
<p>5、判断是否被风控，可以联系 <a href="https://cschannel.alipay.com/newPortal.htm?scene=mysjbzzx">商户客服</a> 进行核实；</p>
<h3>Q：小程序支付如何接入小程序订单中心？</h3>
<p>A：使用小程序支付且成功支付后参考 <a href="https://opendocs.alipay.com/mini/introduce/ordercenter#异步同步">异步同步</a> 接入。</p>