支付宝支付

superC aliyunpayintegrated-development

# 一、支付宝支付

# 支付方式

当面付（二维码）
App支付
电脑网站支付
刷脸付

能力名称	应用场景	支持账户类型
当面付 (opens new window)	超市、餐馆线下交易场景，商家可生成订单二维码供用户扫码支付；也可扫描用户二维码完成收款。	企业支付宝账户、个体工商户
App 支付 (opens new window)	支付宝为商家提供了客户端&服务端 SDK，帮助商家快速在自有 App 中集成支付宝支付功能。	企业支付宝账户、个体工商户
手机网站支付 (opens new window)	为商家移动端网页应用提供集成支付宝支付功能接口。	企业支付宝账户、个体工商户
电脑网站支付 (opens new window)	为商家 PC 端网页应用提供集成支付宝支付功能接口。	企业支付宝账户、个体工商户
刷脸付 (opens new window)	商场、无人售货等线下自助支付场景，用户可通过刷脸操作使用支付宝付款。	企业支付宝账户、个体工商户
互联网平台直付通 (opens new window)	集支付、结算、分账等功能为一体的直付通能力，可帮助电商、互娱平台解决可能存在的合规问题。	企业支付宝账户
支付宝预授权 (opens new window)	租车、充电宝、酒店预订等需要用户在服务前做一笔预授权，商家在服务完结时从预授权资金中扣除消费金额场景，可通过支付宝预授权能力实现。	企业支付宝账户
新当面资金授权 (opens new window)	酒店、景区等线下需要提前缴纳一定的押金，消费结束进行结算时，再根据实际消费情况从押金中扣除消费金额的消费场景，可通过新当面资金授权能力实现。	企业支付宝账户
周期扣款 (opens new window)	会员收费、话费定时充值等周期定额扣款场景，可通过周期扣款能力进行代扣订单创建及扣款，无需用户重复确认及输入支付密码。	企业支付宝账户

# 二、集成当面付

本项目集成支付宝-当面付-扫码支付。

# 当面付简介

当面付包括付款码支付和扫码支付两种收款方式。

付款码支付：商家使用扫码枪或其他扫码机具扫描用户出示的付款码，来实现收款。
扫码支付：商家提供收款二维码，由用户通过支付宝扫码支付，来实现收款。

适用于线下实体店支付、面对面支付、自助售货机等场景。

该能力对企业支付宝账户和个体工商户（即提交营业资质的个人账户）开放。

# 计费模式

支付工具	服务名称	费率	结算周期
支付宝支付	单笔费率	0.6%	T+1

说明：

当前产品费用按单笔收费，支持的支付工具有余额、银行卡（储蓄卡和信用卡）、花呗、花呗分期等，均按此费率收取。
退款是否退费以交易发生时刻合约中的退费约定为准。

退款说明

退款周期：根据合约约定周期，交易发生后在合约约定期限内可发起退款，超过合约约定期限则不可发起退款。
退款方式：资金原路返回原支付账户。
退款退费：退款是否退费以交易发生时刻合约中的退费约定为准。

# 结算说明

收款账户：默认收款至签约账号的支付宝余额，实时到账。

注意：根据相关要求，新签约该产品未满90日或连续交易未满30日的商家，通过该产品收款的资金都将于下一个工作日结算。

# 提现说明

提现收费标准如下：

服务名称	费率
当日到账费率	单笔金额0 - 10 万元（含 10 万元）：0.2%（最低 2 元，最高 25 元）10 万元 - 500 万元（不含 10 万元）：0.025%（无上、下限）
次日到账	0 元（无上、下限）
限额	单笔：500 万元当日：500 万元

# 当面付接口API

当面付接口API列表 (opens new window)

统一收单交易支付接口（alipay.trade.pay）

通过本接口上送至支付宝发起支付。
统一收单线下交易查询（alipay.trade.query）

通过该接口主动查询订单状态。
统一收单线下交易预创建（alipay.trade.precreate）

调用该接口生成二维码。商家可调用 alipay.trade.precreate (opens new window)（统一收单线下交易预创建接口），传入订单商品及金额的信息创建订单。支付宝将返回支付二维码信息用于用户扫码支付。
统一收单交易退款接口（alipay.trade.refund）

通过退款接口将支付款退还给买家。
统一收单交易退款查询（alipay.trade.fastpay.refund.query）

使用该接口查询自已通过alipay.trade.refund提交的退款请求是否执行成功。

# 扫码支付流程

扫码支付调用说明文档 (opens new window)

# 接入设计

扫码支付适合有各类自助终端的商家，用户在自助终端通过扫码完成支付。当面付扫码支付采用 商家/系统服务商后台转发 方式接入，商家先预下单到商家后台，再请求到支付宝。

# 流程图

支付宝为了保证交易安全采取了一系列安全手段以保证交易安全。

请商家务必注意：

采用 HTTPS 协议传输交易数据，防止数据被截获、解密。
采用 RSA/RSA2 非对称密钥，明确交易双方的身份，保证交易主体的正确性和唯一性。

# 调用流程

商户系统调用 alipay.trade.precreate (opens new window)（统一收单线下交易预创建接口），获得该订单的二维码串 qr_code，开发者需要利用二维码生成工具获得最终的订单二维码图片；
发起轮询获得支付结果：等待 5 秒后调用 alipay.trade.query (opens new window)（统一收单线下交易查询接口），通过支付时传入的商户订单号（out_trade_no）查询支付结果（返回参数 TRADE_STATUS），如果仍然返回等待用户付款（WAIT_BUYER_PAY），则再次等待 5 秒后继续查询，直到返回确切的支付结果（成功 TRADE_SUCCESS 或已撤销关闭 TRADE_CLOSED），或是超出轮询时间。在最后一次查询仍然返回等待用户付款的情况下，必须立即调用 alipay.trade.cancel (opens new window)（统一收单交易撤销接口）将这笔交易撤销，避免用户继续支付；
除了主动轮询，当订单支付成功时，商户也可以通过设置异步通知（notify_url）来获得支付宝服务端返回的支付结果，详见扫码异步通知 (opens new window)，注意一定要对异步通知验签，确保通知是支付宝发出的。

注意：

开发者需要确认自己的应用在审核通过后显示 已上线，同时完成当面付功能的签约后，才能顺利调用以下接口。否则会有缺少权限的报错。
如商户由于客观原因（如无公网服务器接受支付宝请求等）无法接受异步支付通知，则忽略上图中的步骤 3.4 和 3.4.1。更多注意事项请参考异常处理 (opens new window)。

# 接入准备

具体操作文档 (opens new window)

# 沙箱环境

沙箱环境说明文档 (opens new window)

沙箱环境 (Beta) 是支付宝开放平台为开发者提供的与生产环境完全隔离的联调测试环境，在沙箱环境中完成的调用不会对生产环境中的数据造成任何影响，尤其适合涉及资金链路的能力的调试。

除此之外，沙箱环境还会自动完成或忽略一些场景的商业门槛，如：开发者无需等待产品签约，即可直接在沙箱环境发起 OpenAPI 的调用，使得开发集成工作可以与商务流程并行，从而提高项目整体的交付效率。

注意：

由于沙箱为模拟环境，在沙箱完成接口开发及主要功能调试后，请务必在生产环境进行完整的功能验收测试。所有返回码及业务逻辑以生产环境为准。
为保证沙箱稳定，沙箱环境测试数据会进行定期数据清理。Beta 测试阶段每周日中午 12 点至每周一中午 12 点为维护时间，在此时间内沙箱环境部分功能可能不可用，敬请谅解。
请勿在沙箱进行压力测试，以免触发相应的限流措施，导致无法正常使用沙箱环境。
沙箱支持的各个开放产品，沙箱使用的特别说明请查看各产品的沙箱调试章节。

# 支付宝密钥生成器

支付宝开放平台开发助手简介 (opens new window)

支付宝开放平台开发助手即密钥生成工具，用于对应用的客户端服务端之间的交互进行加密保护。工具主要功能有生成密钥、签名、验签、格式转换、密钥匹配、智能反馈、开放社区。

# 集成并配置 SDK

服务端 SDK 需要商户集成在自己的服务端系统中，用于后续的服务端接口（OpenAPI）调用。

第一步：下载服务端 SDK

为了帮助开发者调用开放接口，支付宝提供了开放平台服务端 SDK (opens new window)，包含 JAVA、PHP、NodeJS、Python 和 .NET 五种语言，封装了签名 & 验签、HTTP 接口请求等基础功能。

请先下载对应语言最新版本的 SDK 并引入本地开发工程。

MAVEN项目依赖

alipay服务端SDK-MAVEN依赖 (opens new window)

<dependency>
  <groupId>com.alipay.sdk</groupId>
  <artifactId>alipay-sdk-java</artifactId>
  <version>4.23.26.ALL</version>
</dependency>

1
2
3
4
5

Alipay SDK 集成说明

由于实例化 SDK 客户端时需要指定应用的私钥信息，请务必注意不要将私钥信息配置在源码中（比如配置为常量或储存在配置文件的某个字段中等），因为私钥的保密等级往往比源码高得多，将会增加私钥泄露的风险。推荐将私钥信息储存在专用的私钥文件中，将私钥文件通过安全的流程分发到服务器的安全储存区域上，仅供自己的应用运行时读取。
SDK 已经对加签验签逻辑做了封装，使用 SDK 时传入支付宝公钥等内容可直接通过 SDK 自动进行加验签。

第二步：接口调用配置

调用具体的 API 前需要进行 AlipayClient 对象初始化。AlipayClient 对象只需要初始化一次，后续调用不同的 API 都可以使用同一个 AlipayClient 对象。

普通公钥模式加签

接口加签方式为普通公钥模式加签时 alipayClient 对象初始化的 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 即创建应用后生成。	获取见查看 APPID (opens new window)。
APP_PRIVATE_KEY	开发者私钥，由开发者自己生成。	获取见配置接口加签方式 (opens new window)。
FORMAT	参数返回格式，只支持 JSON 格式。	json
CHARSET	编码集，支持 GBK/UTF-8。	开发者根据实际工程编码配置。
ALIPAY_PUBLIC_KEY	支付宝公钥，由支付宝生成。	获取详见配置接口加签方式 (opens new window)。说明：传入本参数后，支付宝 SDK 将自动对同步响应进行验签操作。若未传入本参数则需开发者自行验签。
SIGN_TYPE	商户生成签名字符串所使用的签名算法类型，目前支持 RSA2 和 RSA，推荐使用 RSA2。	RSA2

# 调用接口-预下单

预下单（生成支付二维码）（alipay.trade.precreate）

商家可调用 alipay.trade.precreate (opens new window)（统一收单线下交易预创建接口），传入订单商品及金额的信息创建订单。支付宝将返回支付二维码信息用于用户扫码支付。

注意：

预下单请求生成的二维码有效时间为2小时。

# 示例代码

AlipayTradePrecreateRequest request = new AlipayTradePrecreateRequest();
AlipayTradePrecreateModel model = new AlipayTradePrecreateModel();
model.setOutTradeNo("20150320010101001"); // 商户订单号
model.setTotalAmount("88.88"); // 订单总金额，单位为元，精确到小数点后两位
model.setSubject("Iphone6 16G"); // 订单标题。
request.setBizModel(model);
AlipayTradePrecreateResponse response = null;
try {
    response = alipayClient.execute(request);
    String body = response.getBody();
    if (response.isSuccess()) {
        logger.info("调用成功");
        logger.info(body);
        cn.hutool.json.JSONObject jsonObject = JSONUtil.parseObj(body);
        cn.hutool.json.JSONObject result = (cn.hutool.json.JSONObject) jsonObject.get("alipay_trade_precreate_response");
        // 当前预下单请求生成的二维码码串，有效时间2小时
        String qrCode = (String) result.get("qr_code");
        return qrCode;
    } else {
        logger.error("调用失败");
        return null;
    }
} catch (AlipayApiException e) {
    logger.error("【捕获异常】\r\n异常记录：", e);
    throw new BusinessException(ResponseCode.UNKNOWN);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# 请求参数

参数	类型	是否必填	最大长度	描述	示例值
out_trade_no	String	必选	64	商户订单号。由商家自定义，64个字符以内，仅支持字母、数字、下划线且需保证在商户端不重复。	20150320010101001
total_amount	Price	必选	11	订单总金额，单位为元，精确到小数点后两位，取值范围为 [0.01,100000000]，金额不能为 0。如果同时传入了【可打折金额】，【不可打折金额】，【订单总金额】三者，则必须满足如下条件：【订单总金额】=【可打折金额】+【不可打折金额】	88.88
subject	String	必选	256	订单标题。注意：不可使用特殊字符，如 /，=，& 等。	Iphone6 16G
product_code	String	可选	64	销售产品码。如果签约的是当面付快捷版，则传 OFFLINE_PAYMENT；其它支付宝当面付产品传 FACE_TO_FACE_PAYMENT；不传则默认使用 FACE_TO_FACE_PAYMENT。	FACE_TO_FACE_PAYMENT
seller_id	String	可选	28	卖家支付宝用户 ID。如果该值为空，则默认为商户签约账号对应的支付宝用户 ID。不允许收款账号与付款方账号相同	2088102146225135
body	String	可选	128	订单附加信息。如果请求时传递了该参数，将在异步通知、对账单中原样返回，同时会在商户和用户的pc账单详情中作为交易描述展示	Iphone6 16G
goods_detail	GoodsDetail[]	可选		订单包含的商品列表信息，为 JSON 格式，其它说明详见商品明细说明
extend_params	ExtendParams	可选		业务扩展参数
discountable_amount	Price	可选	11	可打折金额。参与优惠计算的金额，单位为元，精确到小数点后两位，取值范围为 [0.01,100000000]。如果该值未传入，但传入了【订单总金额】和【不可打折金额】，则该值默认为【订单总金额】-【不可打折金额】	80.00
store_id	String	可选	32	商户门店编号。指商户创建门店时输入的门店编号。	NJ_001
operator_id	String	可选	28	商户操作员编号。	yx_001
terminal_id	String	可选	32	商户机具终端编号。	NJ_T_001
merchant_order_no	String	可选	32	商户原始订单号，最大长度限制 32 位	20161008001

注意：请严格按照接口文档中的参数入参，传入非接口文档中的参数是无效的，并且可能会导致请求被拦截或其他异常。

out_trade_no：商户订单号，需要保证商家系统不重复。
total_amount：订单金额。
subject：商品的标题/交易标题/订单标题/订单关键字等。不可使用特殊字符，如 /，=，& 等。

# 公共响应参数

参数	类型	是否必填	最大长度	描述	示例值
code	String	是	-	网关返回码,详见文档 (opens new window)	40004
msg	String	是	-	网关返回码描述,详见文档 (opens new window)	Business Failed
sub_code	String	否	-	业务返回码，参见具体的API接口文档	ACQ.TRADE_HAS_SUCCESS
sub_msg	String	否	-	业务返回码描述，参见具体的API接口文档	交易已被支付
sign	String	是	-	签名,详见文档 (opens new window)	DZXh8ee...=

# 响应参数

参数	类型	是否必填	最大长度	描述	示例值
out_trade_no	String	必选	64	商户的订单号	6823789339978248
qr_code	String	必选	1024	当前预下单请求生成的二维码码串，有效时间2小时	https://qr.alipay.com/bavh4wjlxf12tper3a

qr_code：订单二维码（有效时间 2 小时）以字符串的格式返回，开发者需要自己使用工具根据内容生成二维码图片。

# 调用接口-交易查询

统一收单线下交易查询（alipay.trade.query）

发起轮询获得支付结果：等待 5 秒后调用 alipay.trade.query (opens new window)（统一收单线下交易查询接口），通过支付时传入的商户订单号（out_trade_no）查询支付结果（返回参数 TRADE_STATUS），

# 扫码异步通知

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

该异步通知主要作用于配置应用网关，详情请参见配置应用环境 (opens new window)-应用网关。

异步通知是指一笔订单支付完成后，支付宝会将该笔订单的变更信息，沿着商户调用支付请求时所传入的异步通知地址 notify_url，通过 POST 请求的形式将支付结果作为参数通知到商户系统。

异步回调地址状态码(http 状态码) 为 200 时表示异步通知成功，返回码为 404 或 500 时则表示服务器内部错误，需要商户自行排查。

商户如果因为其他原因没有收到支付宝服务端返回的异步通知，可根据异步通知问题 (opens new window) 进行排查。

# 三、支付宝相关资料

开发API通用文档 (opens new window)

服务端SDK (opens new window)

示例DEMO (opens new window)

沙箱环境 (opens new window)

沙箱环境基板信息查看 (opens new window)

当面付接口API列表 (opens new window)

Swagger 三方库API

超炫之家