支付宝支付接口说明
产品介绍
在商家开发的小程序中,用户也可以唤起支付宝收银台进行支付。小程序支付和 APP 支付的支付流程与体验基本一致,小程序支付也支持核销口碑券和口碑商户优惠功能。已签约小程序支付或在口碑开店的商户建议接入小程序支付。
系统服务商可以通过代签约接口 alipay.open.agent.facetoface.sign 代替商家签约当面付,使用小程序支付。
小程序支付在小程序内不能通过扫码、条码、声波付等方式支付,只能唤起收银台进行支付;目前小程序支付还不支持免密支付。
小程序支付的使用流程如下:
- 用户在小程序中选择商品下单并确认购买,进入支付环节,用户点击确认支付;
- 进入到支付宝页面后,小程序唤起支付宝支付,出现支付界面;
- 用户确认收款方和金额,点击 立即付款 后进行支付;
- 输入正确支付密码后,显示支付成功页;
点击支付成功页右上角 完成 按钮,可跳转到自定义页面,开发者可根据付款结果个性化展示订单处理结果,如下图所示。(支持跳转到生活号页面,但仅允许跳转至与该小程序关联的生活号页面,更多跳转方式信息请参见 生活号客户端跳转链接。)
准入条件
- 该能力对企业支付宝账户和个体工商户开放;
- 申请者必须拥有经过实名认证的支付宝账户;
- 需提供真实有效的营业执照,且支付宝账户名称需与营业执照主体一致;
- 网站能正常访问且页面显示完整,网站需要明确经营内容且有完整的商品信息;
- 网站必须通过 ICP 备案。如为个体工商户,网站备案主体需要与支付宝账户主体名称一致;如为个体工商户,则团购不开放,且古玩、珠宝等奢侈品、投资类行业无法申请本产品。
计费模式
费率按单笔计算,四舍五入,保留后两位。 一般行业费率:0.6%;特殊行业费率:1.2%,特殊行业范围包括:手机、通讯设备销售;家用电器;数码产品及配件;休闲游戏;网络游戏点卡、渠道代理;游戏系统商;网游周边服务、交易平台;网游运营商(含网页游戏)。
关联产品推荐
小程序支付目前支持 花呗分期 的付款方式支付;
在支付完成后,开发者可以根据支付宝交易号(trade_no)将订单信息同步到“订单中心”小程序,查看 详细接入步骤。
接入指引
第一步:创建小程序
要在您的小程序内使用小程序支付功能,您需要首先完成 开发者入驻 并 创建小程序。
第二步:添加功能
小程序创建完成后,开发者在 功能列表 部分可以点击 添加功能 来给创建的小程序添加功能,如下图所示;开发者勾选 小程序支付 功能后,点击右下角 确定 即完成添加功能。
注意:
第三方应用代商户实现小程序支付需要:
1、在三方应用上添加当面付功能。
2、代商户签约当面付,参考文档 代商家签约。
第三步:签约功能
添加完成功能后,请点击功能列表右侧对应功能的 签约 链接;用户签约后,需要 1 个工作日左右的审批时间(审批结果会以短信和邮件形式告知),审批通过后,功能状态会变为“已生效”,即可调用小程序支付功能。
第四步:集成并配置 SDK
服务端 SDK 需要商户集成在自己的服务端系统中,用于后续的服务端接口调用。
下载服务端 SDK
为了帮助开发者调用开放接口,我们提供了 开放平台服务端 SDK ,包含 JAVA、PHP、NodeJS、Python 和 .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 |
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)作为请求参数传入,实现代商户发起请求的能力。
> 如果您在调用 API 时出现报错: > > > > - 欢迎前往 开放社区 提问、留言; > - 在 公共错误码 中根据错误码的类型,查找相关错误码及解决方案; > - 在 蚂蚁问答 问答页面直接输入您遇到的错误码; > - 在 云排查 中排查遇到的问题; > - 您还可以在 文档中心 直接搜索您要的答案。
第五步:调用接口
小程序支付调用流程如下图所示:
1.在小程序端调用 my.request 接口,连接到商户服务端。
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'});
}
});
2.在服务端调用 alipay.trade.create (统一收单交易创建接口),获得支付宝交易号 tradeNO(以 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();
}
注意:
小程序支付场景中 alipay.trade.create 接口中的 buyer_id 为必填项, 该值为付款用户的支付宝 user_id,获取详情参见 用户授权文档。
3.在小程序端使用 tradeNO,调用 my.tradePay 接口唤起支付收银台。
my.tradePay({
tradeNO: '2017111521001104105336677922',
success: function(res) {
my.alert({
content: JSON.stringify(res),
});
},
fail: function(res) {
my.alert({
content: JSON.stringify(res),
});
},
});
接入花呗分期说明
小程序支付目前支持 花呗分期 的付款方式。要在小程序支付中使用花呗分期付款,只需要开发者在 alipay.trade.create (统一收单交易创建接口接口)中传入对应的参数即可。小程序支持以下两种模式接入花呗分期。
标准收银台模式
支付宝标准收银台展示花呗分期渠道(仅支持用户承担手续费),无需额外签约花呗分期,且无需进行额外的花呗分期参数的透传开发工作,可以直接在支付宝标准收银台中展示出花呗分期渠道。
单通道模式
商家可以根据需要,将花呗分期资金渠道前置或者与其他付款方式并列,实现花呗分期单通道模式。该方式下,如果当前花呗分期渠道无法支付成功,则可以继续使用其他支付渠道进行付款。
开发者需要将花呗分期参数传入到 extend_params
中,格式如下:
"extend_params":{"hb_fq_num":"3","hb_fq_seller_percent":"100"}
hb_fq_num
代表花呗分期数,仅支持传入 3、6、12,其他期数暂不支持,传入会报错;hb_fq_seller_percent
代表卖家承担收费比例,商家承担手续费传入 100,用户承担手续费传入 0,仅支持传入 100、0 两种,其他比例暂不支持,传入会报错。
API 列表
接口名称 | 接口中文名称 |
---|---|
alipay.trade.create | 统一收单交易创建接口 |
my.tradePay | 小程序唤起支付 |
my.request | 向指定服务器发起一个跨域 http 请求 |
alipay.open.agent.facetoface.sign | 代签约当面付接口(也适用于服务商代替商户签约小程序支付) |
快速接入DEMO
支付宝开放平台还为开发者提供了小程序支付 DEMO,开发者可以参考 快速示例 文档进行体验和实现快速接入。
异步通知
订单支付成功时,商户可以通过在 alipay.trade.create 设置异步通知(notify_url)来获得支付宝服务端返回的支付结果,当异步通知中返回的 trade_status(交易状态)为 TRADE_SUCCESS 时,表示支付成功。其他有关异步通知的问题可参考 服务器异步通知参数说明 。
注意:
开发者设置的 notify_url 需要为外部网络环境可正常访问的网址,且状态码为200,支付结果请以异步通知或 支付订单查询接口 返回值为准。
补充说明
- 服务端接口调用,请查看 服务端 SDK ;
- 服务端支付API,比如撤销、退款、关闭等,查看 支付 OpenAPI ;
- 签名逻辑 ;
- 请求参数及同步通知参数说明 ;
- 交易辅助接口 ;
- 对账说明 。
常见问题
> 如果您在调用 API 时出现报错: > > > > - 欢迎前往 开放社区 提问、留言; > - 在 公共错误码 中根据错误码的类型,查找相关错误码及解决方案; > - 在 蚂蚁问答 问答页面直接输入您遇到的错误码; > - 在 云排查 中排查遇到的问题; > - 您还可以在 文档中心 直接搜索您要的答案。
Q:在 IDE 上调用 my.tradePay 报错 “error2: 无效的 API入参”,如何处理?
A:目前IDE模拟器调用my.tradePay后会生成一个支付二维码(有效时间10分钟),开发者在支付宝客户端扫码支付,支付结果会同步my.tradePay回调。
Q:小程序支付无法调起支付,如何处理?
A:可能原因如下:
- 服务端回传的 tradeNO 出错,导致传入 my.tradePay 的 tradeNO 参数错误。
- 小程序支付无法在 IDE 模拟器中进行测试。
解决方案:
1、在服务端调用 alipay.trade.create (统一收单交易创建接口),获得支付宝交易号 tradeNO(以 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\"," +
"\"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();
}
2、将获得的 tradeNO 参数传入 my.tradePay 中(设置为固定值),并在真机上进行测试。
Q:如果想实现识别支付的卡做立减活动,小程序支付是否能查询到用户支付时使用的是什么银行的银行卡?
A:涉及用户的敏感信息,无法实现 。
Q:小程序支付是否支持绑定多个收款账号?
A:不支持,小程序支付默认收款账号为小程序拥有账号。
Q:小程序支付时报错 ALIN10046 是什么原因?
A:报错描述:花呗分期暂不可用,请更换付款方式(ALIN10046);
报错原因:
1、用户尚未开通花呗或花呗分期可用额度不足
2、商户未签约花呗分期产品,暂不支持花呗分期,或选择的商品不支持花呗分期
3、分期金额未达到商户设定的分期起点金额
4、交易触发了限制规则,被判定为高风险交易,导致被风控
解决方案:
1、检查用户是否开通花呗分期,以及用户花呗可用额度是否大于交易金额;
2、商户是否签约了花呗分期产品;
3、可设置goods_type=1;goods_type:商品主类型:0表示虚拟类商品,1表示实物类商品(默认)
4、花呗分期交易金额建议设置成至少100元以上;
5、判断是否被风控,可以联系 商户客服 进行核实;
Q:小程序支付如何接入小程序订单中心?
A:使用小程序支付且成功支付后参考 异步同步 接入。