支付宝支付接入整理

2021-06-12 5,664 阅读17分钟

这是我参与更文挑战的第1天，活动详情查看：更文挑战

背景

一般公司都会有接入支付宝以及微信支付的相关需求，在此处记录文档相关内容，以及个人记录

支付宝支付

特别注意：支付宝是由两个版本的接口的，历史系统可能走的是旧接口

旧版本(mapi)

新版本(openapi)

支付宝支持的支付用途如下，因为只用过 网页&移动应用，因此主要针对这个展开。

以 网页&移动应用为例，大体的流程是如下图的

图片来源于支付宝

文档查看说明

支付宝文档中的分类，以我个人的观看经验，可以分为三步，如下图

第一步，注册账号，了解应用
查看使用场景，以及开放能力，以支付为例，业务场景符合哪个支付能力，并查看接入示例(也有支付宝的sdk&demo)
针对2中接入步骤，需要接入的详细api的开发文档

开发前

创建应用

使用支付宝账号登录开放平台控制台后，可以选择创建应用，主要分为 自研型应用 和 第三方应用(适用于服务商)，两种应用的主要区别在于用户不是开发者本身。

创建可以根据文档中的流程来一步一步进行。其中需要注意的是应用环境中的开发信息

图片来源于支付宝

字段名称	描述
接口加签方式（步骤1）	必填。开发者可根据接入产品需求选择公钥证书模式或公钥模式，并保证接口中使用的私钥与此处设置公钥成对匹配，否则无法调用接口，且接口参数 sign_type=RSA2。详情请参见生成密钥并上传。
IP 白名单（步骤2）	可选。为提高商户访问开放平台的安全性，避免商户因应用私钥泄露等原因导致业务受损，开放平台提供 IP 白名单机制，详情可参考 IP 白名单接入指南。IP 白名单旨在保证开发者的资金安全，开发者视实际情况选用。
应用网关（步骤3）	可选。用于接收支付宝异步通知，开发者视实际需要填写。例如：现金红包、转账到支付宝账户中单据状态变更后触发的 alipay.fund.trans.order.changed （转账单据状态变更通知）。[C2C 现金红包](opendocs.alipay.com/open/201901… 现金红包) 退款成功时触发的 alipay.fund.trans.refund.success(资金退回成功通知) 。注意：支付结果异步通知支付宝会根据支付 API 中传入的异步通知地址 notify_url，通过 POST 请求的形式将支付结果作为参数通知到商户系统。
接口内容加密方式（步骤4）	可选。即 AES 密钥可用于加解密数据信息。接入获取会员手机号、运动数据等需解密数据功能必须配置。详情请参考内容加密指引。
授权回调地址（步骤5）	可选。第三方应用授权或 [用户信息授权](opendocs.alipay.com/open/284/we… redirect_uri 的说明) 后回调地址。授权链接中配置的 redirect_uri 的值必须与此值保持一致 (如：www.alipay.com) ，用户成功授权后将在该 url 后携带授权码等信息并跳转至该页。注意：当填入该地址时，系统会自动进行安全检测，详情请参考安全检测。

绑定应用

绑定应用分为类似创建应用，也分为两种，普通商户绑定 和 服务商待商家绑定操作，主要区别在于应用是不是你的。

同一主体账号绑定应用不会通知商户，且不同主体账号不支持绑定应用

密钥

对于系统交互的接口来说，密钥的重要性毋庸置疑。支付宝提供了三种生成密钥工具：

Web 在线加密（免下载，新上线）推荐
WINDOWS（windows 版本工具请不要安装在含有空格的目录路径下，否则会导致公私钥乱码的问题）
MAC_OSX

更多相关内容请查看开发助手简介

开放能力

支付宝为满足开发者的业务诉求，将支付宝业务能力以接口的形式开放出来，开发者通过这些开放的接口与支付宝服务端进行交互，实现业务逻辑。

这个对应支付宝的文档的右上角第二个文档目录，我们这里着重看支付能力，会提到不同的能力对应的应用场景

支付能力

为解决网页、移动、平台商户及线下支付等场景支持用户使用支付宝付款需求，支付宝提供了如下支付能力供商家快速集成。

包含当面付、App支付、手机网站支付、电脑网站支付等，用下面这个表格来简单介绍

能力名称	应用场景	支持账户类型
当面付	超市、餐馆线下交易场景，商家可生成订单二维码供用户扫码支付；也可扫描用户二维码完成收款。	企业支付宝账户个体工商户
App 支付	支付宝为商家提供了客户端&服务端 SDK，帮助商家快速在自有 App 中集成支付宝支付功能。	企业支付宝账户个体工商户
手机网站支付	为商家移动端网页应用提供集成支付宝支付功能接口。	企业支付宝账户个体工商户
电脑网站支付	为商家 PC 端网页应用提供集成支付宝支付功能接口。	企业支付宝账户个体工商户
刷脸付	商场、无人售货等线下自助支付场景，用户可通过刷脸操作使用支付宝付款。	企业支付宝账户个体工商户
互联网平台直付通	集支付、结算、分账等功能为一体的直付通能力，可帮助电商、互娱平台解决可能存在的合规问题。	企业支付宝账户

当面付

主要对应线下场景，主要的是用方式应该大家平时也在用： 条码支付 和 扫码支付,最直观理解可以理解为 你扫商家还是商家扫你，注意，扫码支付需要调用一个预支付

当面付的特点有:

线下快捷的支付
对用户手机没有网络要求，可以离线支付
商家收款资金实时到账，无现金流压力

条码支付

买家出示支付宝钱包中的条码、二维码，商家扫描用户条码即可完成 条码支付 收款，所有收款流程由商家端完成。

条码支付比较适合于需要对接各类商家系统，对账强需求的商家，比如商场超市等。其中分为两类接入方式： 门店直连方式 和 商户/系统商后台转发

流程如下:

创建交易并支付（ alipay.trade.pay(统一收单交易支付接口)）

根据返回的结果，确定支付状态，从而进行相应处理（包括必要时关闭交易), 如图 opt 区块中所示，第 2 步表示支付成功，返回支付成功页；

第 3 步表示返回的参数为待用户付款（code=10003）或者系统异常（code=20000）、网络超时等场景下处理方式；

第 4 步表示轮询结束仍未处理成功，需要撤销订单；

第 5 步表示返回支付失败（code=40004）时，需要重新检查参数，重新发起支付。

详情请参见异常处理。

条码支付方式流程图

条码支付-门店直连方式

条码支付-后台转发方式

涉及api：

接口英文名	接口中文名	描述
alipay.trade.pay	统一收单交易支付接口（条码支付）	通过调用该接口创建支付宝交易订单
alipay.trade.query	统一收单线下交易查询	通过调用该接口查询订单的状态
alipay.trade.cancel	统一收单交易撤销接口	通过调用该接口撤销订单
alipay.trade.create	统一收单交易创建接口	创建支付宝交易订单
alipay.trade.refund	统一收单交易退款接口	支持部分和全部退款
alipay.trade.close	统一收单交易关闭接口	交易关闭接口
alipay.trade.fastpay.refund.query	统一收单交易退款查询接口	通过调用该接口查询通过 alipay.trade.refund 提交的退款请求是否执行成功
alipay.data.dataservice.bill.downloadurl.query	查询对账单下载地址接口	查询并下载对账单
monitor.heartbeat.syn	交易保障接口	交易保障接口
alipay.trade.refund.depositback.completed	收单退款冲退完成通知	退款到银行卡通知

扫码支付

买家通过使用支付宝 扫一扫 功能，扫描商家收款二维码即可完成 扫码支付 付款

扫码支付比较适合单独定价、无人值守、自助售货机等商家(不需要强对账)，比如线下小型便利店，自助售货机等，用户在自助终端通过扫码完成支付。

流程如下：

商户系统调用 alipay.trade.precreate(统一收单线下交易预创建)接口，获得该订单的二维码串 qr_code，开发者需要利用二维码生成工具获得最终的订单二维码图片；

发起轮询获得支付结果：等待 5 秒后调用 alipay.trade.query(统一收单线下交易查询)接口，通过支付时传入的商户订单号（out_trade_no）查询支付结果（返回参数 TRADE_STATUS），如果仍然返回等待用户付款（WAIT_BUYER_PAY），则再次等待 5 秒后继续查询，直到返回确切的支付结果（成功 TRADE_SUCCESS 或已撤销关闭 TRADE_CLOSED），或是超出轮询时间。在最后一次查询仍然返回等待用户付款的情况下，必须立即调用 alipay.trade.cancel(统一收单交易撤销接口)将这笔交易撤销，避免用户继续支付；

除了主动轮询，当订单支付成功时，商户也可以通过设置异步通知（notify_url）来获得支付宝服务端返回的支付结果，详见扫码异步通知，注意一定要对异步通知验签，确保通知是支付宝发出的。

注意：如商户由于客观原因（如无公网服务器接受支付宝请求等）无法接受异步支付通知，则忽略上图中的步骤 3.4 和 3.4.1。更多注意事项请参考异常处理。

涉及api

接口英文名	接口中文名	描述
alipay.trade.query	统一收单线下交易查询	通过调用该接口查询订单的状态
alipay.trade.cancel	统一收单交易撤销接口	通过调用该接口撤销订单
alipay.trade.create	统一收单交易创建接口	创建支付宝交易订单
alipay.trade.refund	统一收单交易退款接口	支持部分和全部退款
alipay.trade.precreate	统一收单线下交易预创建（扫码支付）	创建支付宝交易订单（扫码）
alipay.trade.close	统一收单交易关闭接口	交易关闭接口
alipay.trade.fastpay.refund.query	统一收单交易退款查询接口	通过调用该接口查询通过 alipay.trade.refund 提交的退款请求是否执行成功
alipay.data.dataservice.bill.downloadurl.query	查询对账单下载地址接口	查询并下载对账单
monitor.heartbeat.syn	交易保障接口	交易保障接口
alipay.trade.refund.depositback.completed	收单退款冲退完成通知	退款到银行卡通知

APP支付

App支付主要指在商家的App中需要拉起支付宝支付的情况。商家APP调用支付宝提供的 SDK，SDK 再调用支付宝APP内的支付模块。

如果用户已经安装支付宝App，跳转支付宝支付

如果用户没有安装支付宝App，拉起支付宝网页支付收银台支付

[常见问题](App 支付常见问题)

客户端 iOS 集成流程

opendocs.alipay.com/open/204/10…

客户端Android 集成流程

opendocs.alipay.com/open/204/10…

服务端接入流程

服务端接入需要先通过沙箱环境，一笔订单的系统交互流程如下

交易的签名，必须在服务端进行，创建下单的接口为alipay.trade.app.pay (app支付接口2.0)

涉及api

API英文名	API中文名字	文档
alipay.trade.app.pay	app 支付接口 2.0	查看文档
alipay.trade.query	交易查询接口	查看文档
alipay.trade.close	交易关闭接口	查看文档
alipay.trade.refund	交易退款接口	查看文档
alipay.trade.fastpay.refund.query	交易退款查询接口	查看文档
alipay.data.dataservice.bill.downloadurl.query	查询账单下载地址接口	查看文档
alipay.trade.refund.depositback.completed	收单退款冲退完成通知	查看文档

手机网站支付

手机网站支付提供的是在商家的移动端网页中集成支付宝支付功能。在页面下单，返回支付宝链接，拉起支付宝客户端(h5的支付页面只有旧商家支持)。

如果是在web-view 中打开的话，可以考虑转用 手机网站转APP支付

由于手机网站产品为了商家以及用户更好的支付安全保障，进行了产品优化升级。在用户安装了支付宝客户端的前提下，产品支付流程基本不变，按原流程直接唤起钱包进行支付。在未安装支付宝客户端的前提下，支付流程有所变化，升级后不再唤起 h5 网页支付，会引导用户下载支付宝客户端进行支付。

2019 年 8 月份开始签约的手机网站支付产品会走新的支付流程，历史签约产品商家仍然支持唤起 h5 页面支付。

对于部分历史签约商户，若您的 h5 支付成功率极低的，为了提升支付体验和安全性，也会升级为新产品流程。

服务端接入流程

手机网站支付流程图

用户在商户的H5网站下单支付后，商户系统 调用 alipay.trade.wap.pay（手机网站支付接口2.0）接口参数规范生成订单数据；然后在前端页面通过 Form 表单的形式向 支付宝系统 发送支付请求。此时支付宝会自动将页面跳转至支付宝 H5 收银台页面，如果用户手机上安装了支付宝 App，则自动唤起支付宝 App，否则提示下载支付宝 App。
用户在支付宝 App 或 H5 收银台完成支付后，会根据商户在手机网站支付 API 中传入的前台回跳地址 return_url 自动跳转回商户页面，同时在 URL 请求中以 Query String 的形式附带上支付结果参数，详细回跳参数详见文末附录一：前台回跳参数说明。
除了正向支付流程外，支付宝也提供交易查询、关闭、退款、退款查询以及对账等配套API。

说明：

开发者需要关注安装了支付宝和未安装支付宝的两种测试场景，对于在手机浏览器唤起 H5 页面的模式下，如果安装了支付宝却没有唤起，大部分原因是当前浏览器不在支付宝配置的白名单内。

对于商户 App 内嵌 web-view 中的支付场景，建议集成支付宝 App支付产品。或者您可以使用手机网站支付转Native支付的方案，不建议在您的 App 中直接接入手机网站支付。

在 IOS 系统中，唤起支付宝 App 支付完成后，不会自动回到浏览器或商户 App。用户可手工切回到浏览器或商户 App；支付宝 H5 收银台会自动跳转回商户 return_url 指定的页面。

支付宝还会根据原始支付 API 中传入的异步通知地址 notify_url，通过 POST 请求的形式将支付结果作为参数通知到商户系统，详情见支付结果异步通知。

涉及api

API 英文名	API 中文名
alipay.trade.wap.pay	手机网站支付接口2.0
alipay.trade.query	交易查询接口
alipay.trade.close	交易关闭接口
alipay.trade.refund	交易退款接口
alipay.trade.fastpay.refund.query	交易退款查询接口
alipay.data.dataservice.bill.downloadurl.query	查询账单下载地址接口

电脑网站支付

可以商家的PC端网站中直接跳到支付宝PC网站收银台完成收款，流程如下

用户在商户网站选择需购买的商品及商品款式后，点击立即购买(可以在PC淘宝网址下随便找一个商品尝试 or 优酷网页版购买会员)
网页跳转到支付宝收银台页面，此时有两种付款方式供用户选择
1. 用户可以使用支付宝 APP 扫一扫屏幕二维码，待手机提示付款后选择支付工具输入密码即可完成支付
2. 如果不使用手机支付，也可以点击图 1 页面右侧的 登录账户付款，输入支付宝账号和支付密码登录 PC 收银台
用户选择付款方式后，输入支付密码并点击 确认付款，付款成功则页面跳转到付款成功页。

接入流程

商户系统调用 alipay.trade.page.pay（统一收单下单并支付页面接口向支付宝发起支付请求，支付宝对商户请求参数进行校验，而后重新定向至用户登录页面。
用户确认支付后，支付宝通过 get 请求 returnUrl（商户入参传入），返回同步返回参数。
交易成功后，支付宝通过 post 请求 notifyUrl（商户入参传入），返回异步通知参数。
若由于网络等原因，导致商户系统没有收到异步通知，商户可自行调用 alipay.trade.query（统一收单线下交易查询接口查询交易以及支付信息（商户也可以直接调用该查询接口，不需要依赖异步通知）。

涉及api

接口英文名	接口中文名
alipay.trade.page.pay	统一收单下单并支付页面接口
alipay.trade.refund	统一收单交易退款接口
alipay.trade.fastpay.refund.query	统一收单交易退款查询接口
alipay.trade.query	统一收单线下交易查询接口
alipay.trade.close	统一收单交易关闭接口
alipay.data.dataservice.bill.downloadurl.query	查询对账单下载地址
alipay.trade.refund.depositback.completed	收单退款冲退完成通知

API

支付API的文档类似微信，主要区别在于下单，其余都通用，主要用于讲述详细的接口参数内容。

建议主要从支付文档的开放能力处，了解 具体业务需要的接口 以及 需要开通什么内容，再回到支付文档中查看接口明细

图片还来源于支付宝

下单接口api	接口场景	接口方法
统一收单交易支付接口	商家扫你的付款码码(扫码枪)	alipay.trade.pay
统一收单线下交易预创建	你扫商家的收款码，收款码是商家通过收银台或者商户后台调用支付宝接口生成	alipay.trade.precreate
app支付接口2.0	外部的APP通过调用支付宝的sdk拉起支付宝	alipay.trade.app.pay
手机网站支付接口2.0	在手机上网站上请求支付宝	alipay.trade.wap.pay
统一收单下单并支付页面接口	在PC网址上请求支付宝拉起页面	alipay.trade.page.pay

总结

对于支付宝支付接入来说，创建完应用，最主要的应该是【开放能力】这一栏，这里详细说了每个能力需要的 准备、业务场景，以及示例和相关代码的下载，可以让开发者又明确的方向。

api的接入，可以先在【开放能力】对应业务的api列表中查看。再详细对接各个接口(文章中也有列出)

在接入过程中，也有对应的小工具或沙箱环境，帮助更好的接入,如产品介绍中的 XXX接入助手

在【开放能力】中，每个具体的场景也会有对应的常见问题提供，有疑惑一般也可以在这里找到解答。如果真的在文档中找不到答案，也可以选择需要在线解答，点击页面右边的咨询提问即可。

问题

1. 新增网关配置密钥会不会影响旧的密钥以及接口

支付宝是存在新旧两个汪公馆接口的，其中是各自不影响的。

相关文档

友情链接：